Pour configurer la détection de packages pour un projet Python utilisant la structure src sous macOS, pointez setuptools vers src dans pyproject.toml, puis définissez des filtres de noms de packages uniquement si vous devez contrôler quels packages sont distribués. Pour un projet conventionnel, setuptools peut souvent détecter la structure automatiquement ; des paramètres de détection explicites sont utiles lorsque vous souhaitez des inclusions ou exclusions prévisibles. Ces instructions s'appliquent à setuptools, et non à tous les backends de build Python.

Vérifier la structure du projet et le backend de build

Depuis le Terminal, placez-vous à la racine du projet — le dossier contenant pyproject.toml — et inspectez les fichiers avec le shell par défaut de macOS, zsh, ou avec bash si c'est votre shell configuré :

cd '/path/to/project'
find src -maxdepth 3 -type f -print

Remplacez le chemin entre guillemets par l'emplacement réel du projet. Les guillemets simples empêchent l'interprétation des espaces et des métacaractères du shell dans un chemin. Un package typique peut se trouver dans src/my_package/__init__.py, avec des sous-packages dans des répertoires situés en dessous. Le nom d'importation est my_package ; le répertoire nommé src n'est qu'un conteneur et ne fait pas partie de ce nom.

Vérifiez que pyproject.toml sélectionne setuptools sous [build-system], par exemple avec requires = ["setuptools>=61"] et build-backend = "setuptools.build_meta". La documentation de setuptools décrit la détection automatique pour les structures courantes, y compris src, lorsque les listes de packages et de modules ne sont pas fournies explicitement. D'autres backends ont leur propre configuration, ne copiez donc pas les paramètres de setuptools dans la table de configuration d'un autre backend. Setuptools: Configuring setuptools using pyproject.toml files

Configurer la détection explicite dans pyproject.toml

Si vous souhaitez une détection spécifiquement enracinée dans src, ajoutez la configuration setuptools suivante au fichier existant :

[tool.setuptools.packages.find]
where = ["src"]

Cela indique à setuptools où chercher les packages. Cela ne modifie ni le nom du projet ni le nom d'importation du package. Si vous disposez déjà d'une table [tool.setuptools.packages.find], modifiez cette table plutôt que d'en ajouter une seconde. Les fichiers TOML ne peuvent pas contenir de définitions en double d'une même table.

Pour restreindre la détection à un seul package et à ses sous-packages, ajoutez un motif include correspondant au nom complet du package avec points :

[tool.setuptools.packages.find]
where = ["src"]
include = ["my_package*"]

Remplacez my_package par le nom réel du package d'importation. L'astérisque * permet au motif de correspondre aux sous-packages tels que my_package.tools ; les motifs sont comparés aux noms complets des packages. Vous pouvez également exclure certains packages, par exemple avec exclude = ["my_package.tests*"]. Setuptools documente ces motifs d'inclusion et d'exclusion, ainsi que where, dans son guide de détection de packages.

Choisir comment la détection gère les packages d'espace de noms (namespace packages)

Par défaut, la détection de pyproject.toml par setuptools analyse les packages d'espace de noms implicites : les répertoires peuvent être traités comme des packages même lorsqu'ils ne contiennent pas de fichier __init__.py. Conservez ce comportement par défaut si votre package utilise intentionnellement les packages d'espace de noms selon la PEP 420. Si chaque package doit comporter un __init__.py, vous pouvez désactiver l'analyse des espaces de noms :

[tool.setuptools.packages.find]
where = ["src"]
namespaces = false

Avec ce paramètre, les répertoires sans __init__.py ne sont pas détectés comme des packages. L'absence d'un package dans la distribution générée peut donc s'expliquer par l'emplacement de recherche, un motif include ou exclude, ou le paramètre d'espace de noms. Le guide de packaging aborde ce comportement et montre comment la détection peut être limitée à des packages d'espace de noms sélectionnés. Python Packaging User Guide: Packaging namespace packages

Savoir quand la détection automatique est suffisante

Pour un projet simple de type src/my_package, il est possible que vous n'ayez pas du tout besoin d'une table de détection. Setuptools sait reconnaître les structures courantes lorsque packages et py-modules ne sont pas spécifiés. Ajoutez une configuration explicite lorsque vous devez restreindre la sélection de packages, gérer une arborescence moins conventionnelle ou lever toute ambiguïté sur le répertoire source. Évitez de coder en dur des listes de packages séparées, sauf si vous avez l'intention de les maintenir à mesure que l'arborescence des packages évolue ; les listes explicites risquent d'entraîner facilement l'omission de sous-packages nouvellement ajoutés.

Une structure src signifie également que l'exécution de Python depuis la racine du dépôt n'ajoute pas automatiquement le package au chemin d'importation (import path). C'est normal : la documentation de setuptools précise qu'une installation modifiable (editable install) est nécessaire pour utiliser le package de cette manière depuis une copie locale des sources. La configuration de détection contrôle ce qui est inclus dans une distribution ; elle ne remplace pas l'installation du projet dans l'environnement Python que vous utilisez pour le développement. Setuptools: Package Discovery and Namespace Packages

Sources