Publicación de un Paquete de Python en PyPI con Poetry | Guía

# Publicar un paquete de Python en PyPI: Automatizando el proceso con Poetry

Publicar tu propio paquete de Python en el repositorio PyPI es un paso esencial para los desarrolladores que desean reutilizar su código. La herramienta Poetry simplifica enormemente este proceso al manejar las dependencias y construir los artefactos. Esta guía cubre en detalle la preparación del proyecto, la configuración del entorno y la publicación del paquete, incluyendo el trabajo con tokens API y dependencias opcionales.

Configuración de la cuenta y generación del token API

El primer paso es crear una cuenta en el sitio web oficial de PyPI. Después de registrarte, genera un token API para la autenticación durante la publicación. En el panel de tu cuenta, ve a la sección de tokens API y haz clic en Generar token API. Especifica un nombre para el token y selecciona su ámbito. Para proyectos nuevos, un token a nivel de cuenta (Toda la cuenta) funciona bien, ya que aún no tienes paquetes registrados. Importante: Copia el token generado inmediatamente después de crearlo; no se mostrará de nuevo.

El proceso de generación incluye:

• Iniciar sesión en tu cuenta de PyPI
• Navegar a la sección de gestión de tokens API
• Especificar el nombre del token y su ámbito
• Confirmar la creación y guardar el valor del token

Poetry usará este token para una publicación segura sin requerir tu usuario y contraseña. Almacénalo de forma segura, como si fuera una contraseña.

Inicializar el proyecto con Poetry

Crea el directorio raíz del proyecto y configura un entorno virtual:

python3 -m venv .venv
source .venv/bin/activate

Instala Poetry mediante pip y ejecuta la inicialización:

pip install poetry
poetry init

En modo interactivo, proporciona los parámetros básicos: nombre del paquete, versión, descripción, autor y versión de Python compatible. Los campos principales en el archivo pyproject.toml generado:

• name — nombre único del paquete en PyPI (debe coincidir con el nombre en snake_case del directorio de código)
• version — versión semántica del paquete
• python — rango de versiones del intérprete compatibles
• readme — ruta al archivo de descripción
• packages — puntero al directorio del código fuente

Después de la inicialización, crea un directorio para el código (convierte el name reemplazando guiones con guiones bajos) y agrega la estructura básica de archivos.

Estructura del proyecto y configuración

Una estructura típica del proyecto se ve así:

my-package/
├── LICENSE
├── poetry.lock
├── pyproject.toml
├── README.md
└── my_package/
    ├── __init__.py
    └── core.py

Es fundamental que el nombre del paquete en pyproject.toml coincida exactamente con el nombre del directorio de código. Por ejemplo, para name = "my-package", el directorio debe llamarse my_package. En el archivo __init__.py, se recomienda importar las funciones principales para facilitar su uso.

Ejemplo de implementación en core.py:

PREPEND_STR = 'prepend_'

def modify_str(string: str) -> str:
    return f'{PREPEND_STR}{string}'

Asegúrate de agregar un archivo de licencia (preferiblemente MIT) y un README.md con una descripción de la funcionalidad. Bloquea las dependencias con poetry lock antes de publicar.

Construir y publicar el paquete

Antes de subir al repositorio, construye los artefactos:

poetry build

Este comando genera una distribución fuente (.tar.gz) y un archivo wheel (.whl) en el directorio dist/. A continuación, configura Poetry para usar el token API:

poetry config pypi-token.pypi pypi-XXXXXXXX

Reemplaza pypi-XXXXXXXX con tu token. Ahora publica:

poetry publish

Si tiene éxito, verás la confirmación de la subida a PyPI. Puedes verificar la publicación buscando en el sitio de PyPI o instalando el paquete localmente:

pip install my-package

Trabajar con dependencias opcionales

Para implementar componentes opcionales (instalados mediante pip install package[extra]), configura pyproject.toml así:

[tool.poetry.dependencies]
python = "^3.10"
pydantic = {version=">=1.9", optional = true}

[tool.poetry.extras]
pydantic = ["pydantic"]

Aquí, la dependencia pydantic se marca como opcional con optional = true, y la sección extras crea un grupo pydantic que incluye esta biblioteca. Los usuarios pueden instalar los extras con pip install my-package[pydantic].

Puntos clave

• Coincide estrictamente el nombre del paquete en pyproject.toml con el nombre del directorio de código (guiones → guiones bajos)
• Incluye siempre una licencia y un README.md detallado para generar confianza en los usuarios
• Usa tokens API en lugar de usuario/contraseña para una publicación segura
• Para dependencias opcionales, configura correctamente las secciones dependencies y extras
• Antes de publicar, verifica la construcción con poetry build

— Editorial Team