Habilidad de Empaquetado y Publicación

Estructura de proyectos y lanzamientos en PyPI - una Habilidad de Agente para Python 3.14 y uv 0.6+.

Qué Hace Esta Habilidad

Crea una estructura de biblioteca publicable: src/<paquete>/, pyproject.toml (PEP 621), README.md, LICENSE, CHANGELOG.md, release.yml de GitHub Actions, pasos de prueba de simulación en TestPyPI y política de incremento de versión.

Cuándo Invocar

• Extraer utilidades compartidas de un monorepo a una biblioteca
• Primer lanzamiento de código abierto de un paquete interno
• Modernizar un proyecto heredado con setup.py a pyproject
• Revisar una PR que rompe los metadatos sdist/wheel

Entradas

Salidas

• src/<nombre>/__init__.py con __version__
• [project.scripts] si se necesita un punto de entrada CLI
• Bloque de verificación uv build / python -m build
• Flujo de trabajo OIDC de editor confiable o token a través de secretos de GitHub
• twine check dist/* en CI

Barreras de Protección

1. Estructura src - importar el paquete desde src/ y no desde la raíz del repositorio en sys.path.
2. Sin secretos en pyproject - tokens solo en secretos de CI.
3. Fijar el backend de compilación - hatchling o setuptools explícitamente.
4. Entrada en CHANGELOG por cada lanzamiento - formato Keep a Changelog.
5. Etiqueta vX.Y.Z activa la publicación - no cada commit principal.
6. Probar en TestPyPI antes del índice de producción por primera vez.

Receta

uv sync --all-extras
uv run ruff check .
uv run pytest -q
uv build
uv run twine check dist/*
# CI: publicar en etiqueta después de la autenticación del editor confiable

Ejemplo de Trabajo (fragmento de pyproject)

[project]
name = "acme-utils"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = []
 
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
 
[tool.hatch.build.targets.wheel]
packages = ["src/acme_utils"]

Preguntas Frecuentes

Relacionado

• Empaquetado y Publicación - guía humana
• pyproject.toml Explicado - metadatos
• uv - La Cadena de Herramientas Rápida - herramientas
• Habilidad de Mejores Prácticas de Python - calidad del código

Versiones de Stack: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), 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+.