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.0y Poetry como gestor de dependencias, con elpyproject.tomlen formato PEP 621 ([project]) y las dependencias de desarrollo en[dependency-groups](PEP 735). - Se versiona
poetry.lock. La instalación espoetry install; nunca unpip installsuelto ni unrequirements.txtsin pinear (ADR 0005 transversal). - Dependencias de ejecución:
fastapi,uvicorn[standard],sqlalchemy,asyncpg,alembic,pydantic,pydantic-settings,python-jose[cryptography]yargon2-cffi. - Dependencias de desarrollo:
pytest,pytest-asyncio,pytest-cov,httpx2,ruffymypy. - El driver de PostgreSQL es
asyncpg, nopsycopg2-binary: el servicio usa SQLAlchemy 2 asíncrono yasyncpges su driver para PostgreSQL. - Herramientas de calidad:
ruffpara lint y formato (ruff check+ruff format),mypyen modostrictypytest. No se usablack:ruff formatcumple la misma función y el ADR 0005 transversal ya define el toolchain sin él. - El cliente HTTP de las pruebas es
httpx2:starlette.testclientdeprecóhttpxy emite un aviso en cada corrida si no se reemplaza. - El entorno virtual vive dentro del proyecto, en
.venv/:poetry.tomldeclaravirtualenvs.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 quemypyresuelva 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
blackjunto aruff— dos formateadores con reglas distintas generan ruido en los diffs. httpxcomo cliente de pruebas — su uso constarlette.testclientestá 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 ejecutapoetry updatey se revisa el diff del lock, no se edita elpyproject.tomla mano. - Costo:
asyncpgno 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-pythonde 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.