Poetry en Python: gestión de dependencias, pyproject.toml y entornos virtuales

Gestionar dependencias con pip y requirements.txt funciona, pero tiene problemas conocidos: no distingue entre dependencias directas y transitivas, no resuelve conflictos de versiones y no aísla el entorno automáticamente. Poetry resuelve todo eso con una sola herramienta que cubre instalación, actualización, virtualenv y publicación en PyPI.

Instalar Poetry y crear un proyecto

# Instalar Poetry (Linux/Mac/WSL)
# curl -sSL https://install.python-poetry.org | python3 -

# Crear proyecto nuevo
# poetry new mi-proyecto
# Estructura:
# mi-proyecto/
# ??? pyproject.toml      — configuración del proyecto y dependencias
# ??? poetry.lock         — versiones exactas para reproducibilidad
# ??? README.md
# ??? mi_proyecto/
#     ??? __init__.py

# O inicializar en directorio existente
# poetry init

pyproject.toml: el corazón del proyecto

# pyproject.toml generado por Poetry
[tool.poetry]
name = "mi-api"
version = "0.1.0"
description = "API REST con FastAPI"
authors = ["Ana García "]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.12"
fastapi = "^0.110.0"
uvicorn = {extras = ["standard"], version = "^0.29.0"}
sqlalchemy = "^2.0.0"
pydantic = "^2.6.0"

[tool.poetry.group.dev.dependencies]
pytest = "^8.0.0"
pytest-asyncio = "^0.23.0"
httpx = "^0.27.0"
mypy = "^1.9.0"
ruff = "^0.3.0"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry-core.masonry.api"

Gestionar dependencias con Poetry

# Añadir una dependencia (actualiza pyproject.toml y poetry.lock)
# poetry add requests

# Añadir dependencia de desarrollo
# poetry add --group dev pytest

# Añadir con restricción de versión
# poetry add "sqlalchemy>=2.0,<3.0"
# poetry add "fastapi^0.110"

# Eliminar dependencia
# poetry remove requests

# Actualizar una dependencia a la última versión compatible
# poetry update fastapi

# Actualizar todas las dependencias
# poetry update

# Ver árbol de dependencias
# poetry show --tree

# Ver dependencias desactualizadas
# poetry show --outdated

Entorno virtual: automático con Poetry

# Poetry crea y gestiona el virtualenv automáticamente

# Activar el entorno
# poetry shell

# Ejecutar un comando dentro del entorno sin activarlo
# poetry run python mi_script.py
# poetry run pytest
# poetry run uvicorn main:app --reload

# Ver dónde está el virtualenv
# poetry env info

# Listar los entornos creados
# poetry env list

# Eliminar el entorno
# poetry env remove python3.12

poetry.lock: reproducibilidad exacta

# poetry.lock registra las versiones EXACTAS de todos los paquetes
# incluyendo las dependencias transitivas

# Instalar exactamente lo que dice el lock file (ideal para CI/CD)
# poetry install --no-root

# Instalar sin dependencias de desarrollo
# poetry install --without dev

# Regenerar el lock file (cuando pyproject.toml ha cambiado)
# poetry lock

# Exportar a requirements.txt (para compatibilidad con herramientas que lo necesitan)
# poetry export -f requirements.txt --output requirements.txt --without-hashes

Scripts personalizados

# pyproject.toml
[tool.poetry.scripts]
iniciar = "mi_api.main:arrancar"
migrar = "mi_api.db:aplicar_migraciones"

# mi_api/main.py
def arrancar():
    import uvicorn
    uvicorn.run("mi_api.app:app", host="0.0.0.0", port=8000, reload=True)

# Ejecutar:
# poetry run iniciar
# poetry run migrar

Publicar en PyPI

# Configurar credenciales de PyPI (una sola vez)
# poetry config pypi-token.pypi tu-token-de-pypi

# Construir los paquetes (sdist + wheel)
# poetry build
# Crea: dist/mi-api-0.1.0.tar.gz y dist/mi-api-0.1.0-py3-none-any.whl

# Publicar en PyPI
# poetry publish

# Publicar en TestPyPI (para probar)
# poetry publish -r testpypi

# Subir versión antes de publicar
# poetry version patch   # 0.1.0 ? 0.1.1
# poetry version minor   # 0.1.0 ? 0.2.0
# poetry version major   # 0.1.0 ? 1.0.0

Configuración extra en pyproject.toml

# pyproject.toml — herramientas de calidad de código
[tool.mypy]
python_version = "3.12"
strict = true

[tool.ruff]
line-length = 88
select = ["E", "F", "I", "UP"]

[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"

[tool.coverage.run]
source = ["mi_api"]
omit = ["tests/*"]

# Ejecutar todas las herramientas
# poetry run mypy mi_api/
# poetry run ruff check .
# poetry run pytest --cov=mi_api

La ventaja clave de Poetry sobre pip+venv+setup.py es que unifica todo: un solo fichero (pyproject.toml) declara el proyecto, sus dependencias y la configuración de herramientas; el lock file garantiza que todos los miembros del equipo y el CI usan exactamente las mismas versiones; y el virtualenv se gestiona automáticamente sin tener que activarlo manualmente en cada terminal.