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.pyapyproject - Revisar una PR que rompe los metadatos sdist/wheel
Entradas
| Entrada | Por qué |
|---|---|
| Nombre del paquete | Disponibilidad del nombre en PyPI |
| Licencia | MIT, Apache-2.0, propietaria |
| Versión mínima de Python | requires-python (3.14 vs 3.13) |
| Extras opcionales | Grupos de dependencias dev, gpu |
| Destino de publicación | PyPI, índice privado, Artifactory |
Salidas
src/<nombre>/__init__.pycon__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
- Estructura
src- importar el paquete desdesrc/y no desde la raíz del repositorio ensys.path. - Sin secretos en
pyproject- tokens solo en secretos de CI. - Fijar el backend de compilación -
hatchlingosetuptoolsexplícitamente. - Entrada en
CHANGELOGpor cada lanzamiento - formato Keep a Changelog. - Etiqueta
vX.Y.Zactiva la publicación - no cada commit principal. - 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 confiableEjemplo 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
¿uv publish o twine?
uv publish cuando esté disponible en uv fijado; de lo contrario, twine upload - la habilidad documenta ambos.
¿Múltiples paquetes en monorepo?
Un pyproject.toml por paquete o configuración uv del espacio de trabajo - documentar la estructura elegida en README.
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+.