Buenas prácticas de empaquetado
Reglas para paquetes que se instalan limpiamente, versionan de forma predecible y se publican de forma segura.
Cómo usar esta lista
- Aplícala al crear un nuevo paquete o preparar una versión.
- Las bibliotecas siguen reglas más estrictas que las aplicaciones internas.
- Revisa antes de cada publicación en PyPI.
A - Estructura del proyecto
- Diseño
src/. Las pruebas importan el paquete instalado. - Solo
pyproject.toml. No usarsetup.py,setup.cfgorequirements.txtcomo fuente de verdad. - Backend de compilación
hatchling. A menos que las extensiones requieranmaturin/setuptools. - README en PyPI.
readme = "README.md"en[project].
B - Metadatos
- Nombre y descripción claros. Buscables en PyPI.
-
requires-pythonestablecido. Coincide con las versiones soportadas reales. - Licencia declarada. Identificador SPDX en
[project]. - Clasificadores precisos. Etiquetas de versión de Python, SO y framework.
C - Versionado y versiones
- SemVer para bibliotecas. MAYOR para cambios que rompen, MENOR para características, PATCH para correcciones.
-
CHANGELOGactualizado. Cada versión documentada. - Etiqueta Git coincide con la versión. Etiqueta
v1.2.3para la versión1.2.3. - Primero TestPyPI. Verifica la instalación antes de PyPI de producción.
D - Compilación y publicación
- Compilar en CI. Artefactos reproducibles desde un entorno limpio.
- Probar la rueda (wheel).
pip install dist/*.whlen unvenvnuevo antes de subir. - Publicación confiable. Tokens OIDC, no contraseñas en CI.
- Tanto wheel como sdist. Publica ambos formatos.
E - Seguridad
- Sin secretos en el paquete. Tokens, claves y contraseñas nunca en el código fuente ni en los metadatos.
- Dependencias mínimas. Menos dependencias = menor superficie de ataque.
- Eliminar (Yank), no borrar. Versiones incorrectas eliminadas (yanked) en PyPI con explicación.
- 2FA en la cuenta de PyPI. Requerido para todos los publicadores.
Preguntas frecuentes
¿Empaquetado de biblioteca o aplicación?
Bibliotecas: PyPI con semver. Aplicaciones: Docker o pipx.
¿Debo publicar en PyPI?
Si otros equipos o la comunidad lo instalan. Solo para uso interno: índice privado.
¿Cómo elijo un nombre de paquete?
Comprueba pypi.org para ver la disponibilidad. Minúsculas, guiones, sin typosquatting.
¿Qué licencia?
MIT o Apache-2.0 para la mayoría de código abierto. Revisión legal para software propietario.
¿Incluir pruebas en sdist?
Sí para sdist. Las pruebas no se instalan con wheel (excluir mediante configuración).
¿Cómo marco un paquete como obsoleto?
Aviso en README, clasificador PyPI Development Status :: 7 - Inactive, versión final.
¿Publicación en monorepo?
Versiones independientes por paquete. Proyectos PyPI separados.
¿Firmar versiones?
PyPI soporta atestaciones firmadas con PGP. La publicación confiable es la opción moderna por defecto.
¿Con qué frecuencia lanzar?
Cuando se acumulan cambios significativos. Lanzamientos de parche para correcciones de seguridad inmediatamente.
¿Qué pasa con los archivos de datos?
Decláralos en la configuración de compilación. Accede a ellos a través de importlib.resources en tiempo de ejecución.
Relacionado
- Conceptos básicos de empaquetado - primeros pasos
- Publicación en PyPI - flujo de carga
- Versionado y Changelogs - notas de lanzamiento
- Buenas prácticas de entornos - gestión de dependencias
Versiones de pila: Esta página fue escrita 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+.