Saltar a contenido

0001. Stack, dependencias y herramientas de calidad

Estado: Propuesto Fecha: 2026-09-24 Autor: Duval Alcivar Módulo(s) afectado(s): pyproject.toml, poetry.lock, app/

Contexto

Todos los servicios de la plataforma comparten el mismo stack para que un desarrollador pueda moverse entre ellos sin reaprender nada. Hay que fijar qué gestor de dependencias, qué versión de Python, qué librerías y qué herramientas de calidad usa cada servicio nuevo.

La documentación transversal deja una contradicción abierta: su ejemplo de pyproject.toml (ADR 0005 transversal) declara psycopg2-binary, un driver síncrono, mientras la estructura exige un engine asíncrono.

Decisión

  • Python >=3.14,<4.0 y Poetry como gestor de dependencias, con el pyproject.toml en formato PEP 621 ([project]) y las dependencias de desarrollo en [dependency-groups] (PEP 735).
  • Se versiona poetry.lock. La instalación es poetry install; nunca un pip install suelto ni un requirements.txt sin pinear (ADR 0005 transversal).
  • Dependencias de ejecución: fastapi, uvicorn[standard], sqlalchemy, asyncpg, alembic, pydantic, pydantic-settings, python-jose[cryptography] y argon2-cffi.
  • Dependencias de desarrollo: pytest, pytest-asyncio, pytest-cov, httpx2, ruff y mypy.
  • El driver de PostgreSQL es asyncpg, no psycopg2-binary: el servicio usa SQLAlchemy 2 asíncrono y asyncpg es su driver para PostgreSQL.
  • Herramientas de calidad: ruff para lint y formato (ruff check + ruff format), mypy en modo strict y pytest. No se usa black: ruff format cumple la misma función y el ADR 0005 transversal ya define el toolchain sin él.
  • El cliente HTTP de las pruebas es httpx2: starlette.testclient deprecó httpx y emite un aviso en cada corrida si no se reemplaza.
  • El entorno virtual vive dentro del proyecto, en .venv/: poetry.toml declara virtualenvs.in-project = true. Git ya ignora .venv/, y así cada servicio tiene el suyo sin depender de una configuración global de la máquina.
  • Los paquetes app/ y sus subpaquetes llevan __init__.py, para que mypy resuelva un único nombre de módulo por archivo.

Alternativas descartadas

  • requirements.txt — no fija las dependencias transitivas; el ADR 0005 transversal exige instalación reproducible entre dev, staging y producción.
  • psycopg2-binary (el driver del ejemplo del ADR 0005 transversal) — es síncrono y bloquearía el event loop de FastAPI.
  • [tool.poetry.group.dev.dependencies] (el formato que muestra el ADR 0005 transversal) — descartado: Poetry 2.x escribe [dependency-groups] (PEP 735), que es el estándar vigente.
  • Mantener black junto a ruff — dos formateadores con reglas distintas generan ruido en los diffs.
  • httpx como cliente de pruebas — su uso con starlette.testclient está deprecado.
  • No versionar poetry.lock — sin lockfile cada developer y cada pipeline resuelven versiones distintas.

Consecuencias

  • La instalación es reproducible y las herramientas de calidad pasan en verde desde el primer commit del servicio.
  • Las versiones quedan fijadas por poetry.lock; para actualizarlas se ejecuta poetry update y se revisa el diff del lock, no se edita el pyproject.toml a mano.
  • Costo: asyncpg no funciona con SQLAlchemy síncrono, así que cualquier dependencia que exija un driver síncrono necesita una decisión nueva.
  • Costo: cambiar de versión mayor de Python obliga a revisar el lock y el requires-python de todos los servicios a la vez.

Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.