Publicar un paquete de Python con UV y Hatchling es rápido y seguro. Aquí verás, paso a paso, cómo configurar el build backend en pyproject.toml, generar artefactos distribuibles y hacer la publicación en TestPyPI con buenas prácticas de seguridad como 2FA y tokens. Ideal para proyectos Python puro y flujos de CI/CD.
¿Cómo elegir y configurar el build backend con uv?
Seleccionar el build backend correcto es clave. Python ofrece varias opciones: SetopToast es flexible pero complejo. Hatchling es moderno, minimalista y veloz. Fleet es extremadamente simple para paquetes puros de Python. Poetry integra backend y gestión de dependencias. UV funciona con cualquiera que declares en pyproject.toml y recomienda Hatchling por defecto para nuevos proyectos.
¿Qué build backends existen y para qué usar Hatchling?
- SetopToast: el más antiguo y tradicional. Muy flexible.
- Hatchling: moderno, minimalista y rápido. Recomendado por UV.
- Fleet: extremadamente simple para Python puro.
- Poetry: backend con gestor de dependencias integrado.
Hatchling destaca por su simplicidad y eficiencia. Perfecto para empezar a distribuir sin fricción.
¿Cómo declarar build_system en pyproject.toml?
Define el backend y sus requisitos en la sección correspondiente. La idea es especificar require y el build backend apuntando a “.build”.
[build_system]
require = ["hatchling"]
build_backend = "hatchling.build"
Guarda y ya podrás construir tu paquete con UV.
¿Cómo construir el paquete y qué archivos genera uv?
Con el proyecto listo y UV configurado, construye los artefactos distribuibles. El comando central es simple y muestra el output con los archivos resultantes.
¿Qué hace el comando uv build?
- Ejecuta el proceso de empaquetado del proyecto.
- Genera dos archivos listos para publicar: el sdist y el wheel.
¿Qué significan sdist tar.gz y wheel whl?
- tar.gz: el source distribution (sdist). Código fuente empaquetado.
- whl: el wheel. Distribución binaria lista para instalar.
Estos son los dos archivos que se suben al manejador de paquetes.
¿Cómo publicar en TestPyPI con seguridad y tokens?
Antes de publicar en PyPI, usa su entorno de pruebas: test.pypi. Así validas que el sistema de build y publicación funciona sin afectar el índice principal.
¿Cómo crear cuenta y activar 2FA en TestPyPI?
- Regístrate y verifica tu correo con el enlace enviado.
- Activa two factor authentication: genera y guarda códigos de recuperación.
- Escanea el QR en tu app de autenticación y valida el código.
Con esto, tu cuenta queda lista y protegida para publicar.
¿Cómo generar y usar un token con uv publish?
- Crea un token con alcance al proyecto que vas a publicar.
- En tu Makefile, define un comando de publicación usando el token y el índice de pruebas.
publish:
uv publish \
--index test-pypi \
--username __token \
--password $(TOKEN)
- Ejecuta el objetivo de Make:
Si aparece un error, probablemente falta registrar el índice en pyproject.toml.
¿Cómo registrar el index en tool.uv.index?
Declara la lista de índices que usarás en UV con nombre, URL, publish URL y explicit true.
[tool.uv.index."test-pypi"]
url = "test.pypi.org"
publish-url = "test.pypi.org"
explicit = true
Ahora vuelve a publicar con UV y revisa el output. Deberías ver que sube los artefactos, incluso menciona que subió dos versiones.
¿Cómo verificar, buscar e instalar el paquete?
- Ve a test.pypi y busca “Platsy News”. Deberías ver la página pública con descripción y README.
- Instala con pip usando la URL del índice de prueba y el nombre del paquete.
pip install -i <URL> Platsy News
Con esto, ya puedes instalar, configurar tu entorno y empezar a usar la librería. Felicidades: lograste publicar tu primer paquete en el manejador de paquetes principal de Python. Inspírate, crea librerías open source, y comparte tu trabajo con la comunidad. Como referencia, Luis Martínez menciona su experiencia con Django, FastAPI y arquitecturas en la nube, e invita a pensar como desarrollador avanzado: código limpio, ideas que escalan y despliegue a producción.
¿Tienes dudas o quieres contar cómo te fue publicando tu paquete? Escribe en los comentarios y comparte tu experiencia.
