Conceptos básicos de empaquetado

9 ejemplos para empezar con Empaquetado y Publicación: 6 básicos y 3 intermedios.

Prerrequisitos

• Python 3.14.0 con uv 0.6+ o pip
• Un proyecto con pyproject.toml y diseño src/
• Cuenta de PyPI (o TestPyPI) para publicar ejemplos

Ejemplos básicos

1. Compilar una rueda (Wheel)

Una rueda (.whl) es el formato de distribución binaria estándar.

uv build
ls dist/
# myapp-0.1.0-py3-none-any.whl
# myapp-0.1.0.tar.gz

• uv build crea la rueda y el sdist en dist/
• py3-none-any significa Python puro, cualquier plataforma
• Las ruedas se instalan más rápido que los sdists (sin paso de compilación)
• Nunca incluyas dist/ en el control de versiones: compila en CI

Relacionado: Backends de compilación - hatchling vs setuptools

2. pyproject.toml para empaquetado

Los metadatos del paquete residen en [project].

[project]
name = "myapp"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = ["httpx>=0.28"]
 
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

• name es el nombre del paquete en PyPI (minúsculas, guiones)
• version sigue SemVer
• [build-system] declara el backend de compilación
• El nombre de importación puede diferir del nombre del paquete (my_app vs my-app)

Relacionado: Explicación de pyproject.toml

3. Diseño src

Mantén el código fuente en src/ para un empaquetado y pruebas fiables.

myapp/
├── pyproject.toml
├── src/myapp/
│   ├── __init__.py
│   └── core.py
└── tests/

• src/ evita importaciones accidentales desde la raíz del repositorio
• El backend de compilación descubre los paquetes a partir de la configuración
• Las pruebas importan el paquete instalado
• Estándar de la industria para nuevos proyectos

4. Instalar desde una compilación local

Prueba tu paquete antes de publicarlo.

uv build
uv pip install dist/myapp-0.1.0-py3-none-any.whl
python -c "import myapp; print(myapp.__version__)"

• Instala la rueda para verificar que el empaquetado es correcto
• Detecta archivos faltantes y errores de importación
• Prueba en un venv nuevo para mayor precisión
• Prueba también pip install . (ruta sdist)

5. Versiona tu paquete

Expón la versión en __init__.py o usa versionado dinámico.

[project]
version = "0.1.0"

# src/myapp/__init__.py
__version__ = "0.1.0"

• Se prefiere una única fuente de verdad en pyproject.toml
• Versionado dinámico desde etiquetas git con hatchling
• SemVer: MAJOR.MINOR.PATCH
• Versión preliminar: 0.2.0b1

Relacionado: Versionado y Changelogs

6. Punto de entrada de script de consola

Envía un comando CLI con tu paquete.

[project.scripts]
myapp = "myapp.cli:main"

# src/myapp/cli.py
def main() -> None:
    print("Hello from myapp CLI")

• Se instala en .venv/bin/myapp al hacer pip install
• Usa project.scripts en pyproject.toml
• La función no toma argumentos (usa argparse/click internamente)
• Prueba con uv pip install -e . y luego myapp

Relacionado: Puntos de entrada y scripts de consola

Ejemplos intermedios

7. Publicar en TestPyPI

Simula la publicación antes de la producción en PyPI.

uv build
uv publish --index testpypi
# Instalar prueba:
uv pip install --index-url https://test.pypi.org/simple/ myapp

• TestPyPI es un registro sandbox
• Verifica que los metadatos, la instalación y la CLI funcionen
• Usa publicación confiable (OIDC) en CI, no contraseñas
• Promociona a PyPI después de la verificación en TestPyPI

Relacionado: Publicar en PyPI

8. Incluir datos del paquete

Envía archivos no Python (plantillas, valores predeterminados de configuración).

[tool.hatch.build.targets.wheel]
packages = ["src/myapp"]
 
[tool.hatch.build.targets.wheel.force-include]
"src/myapp/templates" = "myapp/templates"

• Las plantillas, esquemas JSON y activos estáticos necesitan inclusión explícita
• force-include mapea la fuente a la ruta de instalación
• Usa importlib.resources para acceder en tiempo de ejecución
• Verifica con pip install e inspecciona site-packages

9. Compilar en CI

Automatiza la compilación de ruedas en cada etiqueta de lanzamiento.

- run: uv build
- uses: actions/upload-artifact@v4
  with:
    name: dist
    path: dist/

• Artefactos de compilación adjuntos a los lanzamientos de GitHub
• La misma rueda se publica en PyPI desde CI
• Firma GPG opcional para paquetes de alta seguridad
• cibuildwheel para extensiones nativas multiplataforma

Relacionado: Mejores prácticas de empaquetado

Versiones de la pila: Esta página se escribió para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ y uv 0.6+.