Para configurar la detección de paquetes para un proyecto de Python que utiliza el diseño src en macOS, dirija setuptools hacia src en pyproject.toml y luego defina filtros de nombres de paquete solo si necesita controlar qué paquetes se distribuyen. En un proyecto convencional, setuptools a menudo puede detectar el diseño automáticamente; las opciones explícitas de detección son útiles cuando desea inclusiones o exclusiones predecibles. Estas instrucciones se aplican a setuptools, no a todos los backends de compilación de Python.

Verificar la estructura del proyecto y el backend de compilación

Desde Terminal, cámbiese a la raíz del proyecto —la carpeta que contiene pyproject.toml— e inspeccione los archivos con el shell predeterminado de macOS, zsh, o con bash si ese es el shell que tiene configurado:

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

Reemplace la ruta entre comillas con la ubicación real del proyecto. Las comillas simples evitan que se interpreten los espacios y los metacaracteres del shell en una ruta. Un paquete típico podría estar ubicado en src/my_package/__init__.py, con subpaquetes en directorios debajo de él. El nombre de importación es my_package; el directorio llamado src es solo un contenedor y no forma parte de ese nombre.

Verifique que pyproject.toml seleccione setuptools en [build-system], por ejemplo con requires = ["setuptools>=61"] y build-backend = "setuptools.build_meta". La documentación de setuptools describe la detección automática para diseños comunes, incluido src, cuando no se proporcionan explícitamente las listas de paquetes y módulos. Otros backends tienen su propia configuración, por lo que no debe copiar los ajustes de setuptools en la tabla de configuración de otro backend. Setuptools: Configuring setuptools using pyproject.toml files

Configurar la detección explícita en pyproject.toml

Si desea que la detección tenga su raíz específicamente en src, añada la siguiente configuración de setuptools al archivo existente:

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

Esto le indica a setuptools dónde buscar los paquetes. No cambia el nombre del proyecto ni el nombre de importación del paquete. Si ya tiene una tabla [tool.setuptools.packages.find], edite esa tabla en lugar de añadir una segunda. Los archivos TOML no pueden contener definiciones duplicadas de una misma tabla.

Para restringir la detección a un paquete y sus subpaquetes, añada un patrón include que coincida con el nombre de paquete completo separado por puntos:

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

Reemplace my_package por el nombre de importación real del paquete. El * permite que el patrón coincida con subpaquetes como my_package.tools; los patrones se comparan con los nombres completos de los paquetes. También puede excluir paquetes seleccionados, por ejemplo exclude = ["my_package.tests*"]. Setuptools documenta estos patrones de inclusión y exclusión, así como where, en su guía de detección de paquetes.

Elegir cómo gestiona la detección los paquetes de espacio de nombres

De forma predeterminada, la detección de pyproject.toml en setuptools analiza paquetes de espacio de nombres implícitos: los directorios pueden tratarse como paquetes incluso cuando no contienen __init__.py. Mantenga este valor predeterminado si su paquete utiliza intencionalmente paquetes de espacio de nombres del PEP 420. Si cada paquete debe tener un __init__.py, puede desactivar el escaneo de espacios de nombres:

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

Con este ajuste, los directorios sin __init__.py no se detectan como paquetes. Por lo tanto, la falta de un paquete en la distribución compilada puede explicarse por la ubicación de búsqueda, un patrón include o exclude, o la configuración del espacio de nombres. La guía de empaquetado analiza este comportamiento y muestra cómo se puede limitar la detección a paquetes de espacio de nombres seleccionados. Python Packaging User Guide: Packaging namespace packages

Saber cuándo basta con la detección automática

Para un proyecto sencillo estructurado como src/my_package, es posible que no necesite una tabla de detección en absoluto. Setuptools puede reconocer diseños comunes cuando packages y py-modules no se especifican. Añada una configuración explícita cuando necesite acotar la selección de paquetes, manejar un árbol menos convencional o asegurarse de que el directorio de origen sea inequívoco. Evite definir manualmente listas de paquetes por separado a menos que tenga la intención de mantenerlas a medida que cambie el árbol de paquetes; las listas explícitas pueden hacer que sea fácil omitir subpaquetes recién agregados.

Un diseño src también implica que ejecutar Python desde la raíz del repositorio no coloca automáticamente el paquete en la ruta de importación. Esto es lo esperado: la documentación de setuptools señala que se necesita una instalación editable para usar el paquete desde una copia de trabajo del código fuente de esta manera. La configuración de detección controla lo que se incluye en una distribución; no sustituye la instalación del proyecto en el entorno de Python que utiliza para el desarrollo. Setuptools: Package Discovery and Namespace Packages

Fuentes