Saltearse al contenido

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.

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.

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.

Ventana de terminal
python -m build # genera dist/*.whl y dist/*.tar.gz
python -m twine check dist/* # valida los metadatos y el README

python -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/v1

twine upload sigue siendo válido para un índice privado que no soporte Trusted Publishing.

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 con Path(__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 de src/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. version en pyproject.toml y otra constante __version__ en el módulo se desincronizan. Una sola fuente: leer la del paquete con importlib.metadata.version("mi-paquete").
  • Las dependencias de desarrollo en producción. pytest en dependencies en lugar de [project.optional-dependencies] infla la instalación y la superficie de ataque.
  • El README que PyPI no muestra. readme = "README.md" y license en el pyproject.toml.
Ventana de terminal
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:

Ventana de terminal
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.

  • 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.

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:

Ventana de terminal
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.

  • 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.
  • 01 · Paquetes y entornos: el diseño con src/.
  • 08 · CI: el build automatizado.
  • 02 · Configuración: lo que el paquete lee al arrancar.