Orientación de la Base de Código

Cómo leer un repositorio de servicios Python: estructura de carpetas, propiedad, convenciones y el camino más rápido desde la clonación hasta la navegación segura.

Receta

service/
├── src/billing/          # paquete de la aplicación
├── tests/                # refleja la estructura de src
├── alembic/              # migraciones de DB (si se usa SQLAlchemy)
├── pyproject.toml        # deps, configuración de ruff, pytest
├── uv.lock               # resolución reproducible
├── docs/                 # ADRs, onboarding, runbooks
└── .github/workflows/    # fuente de verdad de CI

Cuándo recurrir a esto:

• Primera semana en un nuevo equipo o servicio
• Regreso después de una larga ausencia o reorganización
• Planificación de una refactorización entre módulos
• Revisión de una PR grande fuera de tu área habitual

Ejemplo de Trabajo

# Script de sesión de orientación (30-60 min autoguiado)
tree -L 2 src/ tests/
rg -l "router|Blueprint|urlpatterns" src/   # encontrar puntos de entrada HTTP
cat pyproject.toml | rg "name|requires-python|scripts"
cat docs/adr/0001-*.md 2>/dev/null || ls docs/
gh api repos/:owner/:repo/contents/CODEOWNERS 2>/dev/null || cat CODEOWNERS
uv run pytest --collect-only -q | head   # ver módulos de prueba

Rastrea una historia de usuario:

1. Encuentra el manejador de ruta (src/billing/api/routes/orders.py).
2. Sigue la capa de servicio (services/order_service.py).
3. Encuentra el repositorio/ORM (repositories/order_repo.py).
4. Anota la migración que afecta a la misma tabla (alembic/versions/).

Lo que esto demuestra:

• La estructura src/ separa el paquete importable de la raíz del repositorio.
• La búsqueda por palabras clave del framework localiza rápidamente la superficie HTTP.
• Las ADR y CODEOWNERS responden a "quién decide" y "por qué".
• La recolección de pruebas mapea módulos a contratos de comportamiento.

Inmersión Profunda

Cómo Funciona

• Estructura src - El paquete bajo src/<nombre>/ evita importaciones accidentales desde la raíz del repositorio en PYTHONPATH.
• pyproject.toml - Manifiesto único para metadatos, dependencias, configuración de herramientas (ruff, pytest, mypy).
• Las pruebas reflejan src - tests/billing/api/test_orders.py se mapea a src/billing/api/orders.py.
• Propiedad - CODEOWNERS solicita automáticamente a los expertos del dominio en las PRs.

Qué Leer Primero

Notas de Python

# Descubre la versión del paquete y los puntos de entrada programáticamente
import importlib.metadata as m
m.version("billing")
# console_scripts de pyproject [project.scripts]

Trampas

• Asumir Django cuando es FastAPI - Patrones de middleware y configuración incorrectos. Solución: leer ADR o la lista de frameworks en pyproject.
• Ignorar rutas de monorepo - Editar la copia incorrecta del servicio. Solución: confirmar la URL remota y el nombre del directorio.
• Variables de entorno no documentadas - .env.example obsoleto. Solución: documentar el error en el primer clave faltante.
• Omitir pruebas como especificación - Las pruebas muestran contratos reales mejor que la wiki obsoleta. Solución: leer las pruebas del módulo que tocas.
• Lectura del directorio "big bang" - Abrumador. Solución: rastrear una única "slice" vertical.
• Solo conocimiento tribal - Compañero no disponible más tarde. Solución: capturar respuestas en docs/onboarding.md.

Alternativas

Preguntas Frecuentes

Relacionado

• Checklist de Onboarding de Desarrolladores - cronograma
• Guía de Convenciones y Estilo - modismos
• Estructura de Diseño y Paquetes src - arquitectura
• Registros de Decisiones de Arquitectura (ADRs) - proceso de ADRs

Versiones de Stack: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.