Publicación de paquetes Python con UV y TestPyPI

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.

uv build

¿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:

make publish

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.