Empaquetado y distribución
Empaquetar es convertir tu carpeta de código en un artefacto que otra máquina puede instalar sin saber nada de ti. La mitad de los problemas vienen de una confusión: una rueda y un sdist no son lo mismo, y una instala cosas que la otra no.
En una línea
Sección titulada «En una línea»La rueda es lo que se instala; el sdist es lo que se reconstruye. Todo lo que no esté en la rueda, no existe para el usuario.
Los dos artefactos
Sección titulada «Los dos artefactos»| Artefacto | Qué es | Cuándo se usa |
|---|---|---|
mi_paquete-0.1.0-py3-none-any.whl |
ZIP con el código ya preparado | Instalación normal |
mi_paquete-0.1.0.tar.gz (sdist) |
Fuente: se construye al instalar si no hay rueda | Referencia y auditoría |
La rueda es la vía rápida: pip install descomprime y copia. El sdist requiere ejecutar el backend de build en la máquina del usuario, con sus dependencias.
El flujo
Sección titulada «El flujo»python -m build # genera dist/*.whl y dist/*.tar.gzpython -m twine check dist/* # valida los metadatos y el READMEpython -m build usa un entorno aislado con las dependencias de [build-system]. Eso garantiza que el artefacto no depende de lo que tengas instalado.
Para publicar, en lugar de subir con twine upload y un token guardado en tu máquina o en los secretos del CI, usa Trusted Publishing: PyPI confía en un flujo concreto de GitHub Actions y le da un token de vida corta, sin secreto que robar. Se configura una vez en PyPI (proyecto, repositorio, workflow) y el workflow queda así:
publicar: runs-on: ubuntu-latest environment: pypi permissions: id-token: write # permite pedir el token efímero a PyPI steps: - uses: actions/download-artifact@v4 # los dist/* generados por el job de build with: { name: dist, path: dist/ } - uses: pypa/gh-action-pypi-publish@release/v1twine upload sigue siendo válido para un índice privado que no soporte Trusted Publishing.
Lo que se olvida siempre
Sección titulada «Lo que se olvida siempre»Comprobado con hatchling y python -m build sobre un proyecto con src/mi_paquete/ y una carpeta plantillas/ en la raíz: sin force-include, la rueda trae mi_paquete/__init__.py, cli.py y datos/tabla.csv (lo que vive dentro del paquete), pero no plantillas/factura.html; con la tabla force-include aparece como mi_paquete/plantillas/factura.html. Un archivo dentro del paquete listado en .gitignore tampoco entró en la rueda. El sdist sí incluyó plantillas/: la rueda y el sdist pueden diferir, y por eso se inspecciona la rueda.
En el workflow de publicación, el job suele dispararse con on: release: types: [published] o con una etiqueta, y el entorno pypi debe existir en GitHub y coincidir con el configurado en PyPI como trusted publisher. El YAML de este capítulo y el del 08 se validaron con yaml.safe_load; la publicación real no se ejecutó aquí.
- Los datos del paquete. Un
.json, una plantilla o un archivo de configuración que el código lee conPath(__file__).parent / "datos.json"no está en la rueda si el backend no lo incluye. Con hatchling (el backend de este manual) los archivos que viven dentro desrc/mi_paquete/se incluyen salvo que estén ignorados por.gitignore; los que viven fuera del paquete hay que declararlos ([tool.hatch.build.targets.wheel.force-include]). Con setuptools se declaran en[tool.setuptools.package-data]. - La versión duplicada.
versionenpyproject.tomly otra constante__version__en el módulo se desincronizan. Una sola fuente: leer la del paquete conimportlib.metadata.version("mi-paquete"). - Las dependencias de desarrollo en producción.
pytestendependenciesen lugar de[project.optional-dependencies]infla la instalación y la superficie de ataque. - El
READMEque PyPI no muestra.readme = "README.md"ylicenseen elpyproject.toml.
La comprobación que lo detecta todo
Sección titulada «La comprobación que lo detecta todo»python -m venv /tmp/limpio/tmp/limpio/bin/pip install dist/mi_paquete-0.1.0-py3-none-any.whl/tmp/limpio/bin/python -c "import mi_paquete; print(mi_paquete.__file__)"En Windows (PowerShell) cambia bin por Scripts:
python -m venv $env:TEMP\limpio& $env:TEMP\limpio\Scripts\pip install dist\mi_paquete-0.1.0-py3-none-any.whl& $env:TEMP\limpio\Scripts\python -c "import mi_paquete; print(mi_paquete.__file__)"Con uv es lo mismo en dos líneas: uv venv /tmp/limpio y uv pip install --python /tmp/limpio dist/*.whl.
Si eso falla, el paquete está roto, por muy verde que esté el CI. Es el único entorno que se parece al del usuario: sin tu PYTHONPATH, sin tu carpeta de trabajo en sys.path, sin tus dependencias globales.
La trampa
Sección titulada «La trampa»Cuándo no aplica
Sección titulada «Cuándo no aplica»- Uso interno: instala desde el repositorio (
pip install git+https://...) con una etiqueta, o un índice privado simple. - Una aplicación: no necesita distribución; se despliega con su lockfile.
- Un script: un archivo y ya.
Ejercicio
Sección titulada «Ejercicio»Tu paquete instala bien, pero al usarlo lanza FileNotFoundError: plantillas/factura.html. En desarrollo funciona. Diagnostica y corrige.
Solución
El archivo existe en el repositorio pero no se incluyó en la rueda: o está fuera de src/mi_paquete/, o .gitignore lo excluye (hatchling respeta .gitignore), o el backend en uso (setuptools, por ejemplo) sólo empaqueta código Python salvo que se le diga lo contrario.
Diagnóstico:
python -c "import zipfile; print(zipfile.ZipFile('dist/mi_paquete-0.1.0-py3-none-any.whl').namelist())"Si plantillas/factura.html no aparece, confirmado.
Corrección, con hatchling: mover plantillas/ dentro de src/mi_paquete/ (y comprobar que .gitignore no la excluye). Si tiene que quedarse fuera, en pyproject.toml:
[tool.hatch.build.targets.wheel.force-include]"plantillas" = "mi_paquete/plantillas"(Con setuptools sería [tool.setuptools.package-data] con mi_paquete = ["plantillas/*.html"].)
Además, la lectura debe ser robusta a la instalación: Path(__file__).parent / "plantillas" funciona en la rueda (los archivos se copian junto al módulo), pero importlib.resources.files("mi_paquete") / "plantillas/factura.html" es la forma correcta y funciona también dentro de un ZIP.
La verificación es la del capítulo: instalar la rueda en un venv limpio y ejecutar el caso que usa la plantilla.
Referencias
Sección titulada «Referencias»- Lott, S. F. Modern Python Cookbook, 3ª ed. Capítulos 16 y 17.
- Python Packaging User Guide:
pyproject.toml,build,twine. - Parte VII, capítulo 01: estructura del proyecto.
Capítulos relacionados
Sección titulada «Capítulos relacionados»- 01 · Paquetes y entornos: el diseño con
src/. - 08 · CI: el build automatizado.
- 02 · Configuración: lo que el paquete lee al arrancar.