01-backend-python

🐍 BACKEND PYTHON — ESTÁNDARES DE CALIDAD v3.0

TOOLCHAIN (Gates de CI — código debe pasar todos antes de presentarlo)

• black → formato (línea máx. 100 chars)
• isort → orden de imports (perfil black-compatible)
• ruff → lint exhaustivo
• mypy --strict → tipos estrictos
• bandit → SAST seguridad
• pip-audit → CVEs en dependencias

TIPADO — OBLIGATORIO EN TODO

# ✅ CORRECTO
async def calculate_vpin(
    snapshot: MarketSnapshot,
    bucket_size: int,
) -> float: ...

# ❌ PROHIBIDO — sin tipos
def calculate_vpin(snapshot, bucket_size): ...

# ❌ PROHIBIDO — Any
from typing import Any
def process(data: Any) -> Any: ...

# ✅ CORRECTO — Decimal para precios (nunca float)
price: Decimal = Decimal("100.05")
# ❌ PROHIBIDO
price: float = 100.05

NOMENCLATURA

Tipo	Convención	Ejemplo
Clases	PascalCase	MarketDataHub
Funciones/vars	snake_case	fetch_snapshot
Constantes	UPPER_CASE	MAX_CANDIDATES = 300
Privados	_single_underscore	_circuit_breaker
Variables de 1 letra	PROHIBIDO	Usar ticker, no t
Nombres genéricos	PROHIBIDO	Nunca data, val, obj

FUNCIONES — REGLAS DE DISEÑO

# Máximo 30 líneas. Si supera → refactorizar en subfunciones.

# Google-Style docstring OBLIGATORIO en funciones complejas:
async def fetch_option_chain(
    ticker: str,
    expiration_date: date,
) -> Result[list[OptionContract]]:
    """Descarga y valida la cadena completa de opciones.

    Args:
        ticker         : Símbolo en mayúsculas (e.g., "AAPL").
        expiration_date: Fecha de expiración a descargar.

    Returns:
        Result con lista de OptionContract, o failure si la API no responde.

    Raises:
        ValidationError: Si la respuesta falla validación de esquema.
    """

LOGGING — NO PRINT

import logging
logger = logging.getLogger(__name__)

# ✅ CORRECTO
logger.info("Fase A completa", extra={"count": len(candidates)})
logger.error("Fallo en Hub", extra={"ticker": ticker}, exc_info=True)

# ❌ PROHIBIDO
print(f"Fase A: {len(candidates)}")