Convenciones y Guía de Estilo
Modismos de Python acordados para el equipo - formato, nombres, tipado, errores y commits - aplicados por ruff en CI y documentados aquí para que las revisiones se centren en el diseño, no en el gusto.
//
Busca en todas las páginas de la documentación
Modismos de Python acordados para el equipo - formato, nombres, tipado, errores y commits - aplicados por ruff en CI y documentados aquí para que las revisiones se centren en el diseño, no en el gusto.
from __future__ import annotations
from pathlib import Path
DATA_DIR = Path(__file__).resolve().parent / "data"
def load_config(path: Path) -> dict[str, str]:
try:
text = path.read_text(encoding="utf-8")
except OSError as exc:
raise ConfigError(f"no se puede leer {path}") from exc
return parse_env(text)Cuándo usar esto:
# modules/billing/services/tax.py
from decimal import Decimal
from billing.domain.models import LineItem
from billing.settings import Settings
class TaxService:
def __init__(self, settings: Settings) -> None:
self._rate = Decimal(settings.vat_rate)
def compute(self, items: list[LineItem]) -> Decimal:
subtotal = sum((i.unit_price * i.quantity for i in items), start=Decimal("0"))
return (subtotal * self._rate).quantize(Decimal("0.01"))Mensaje de commit:
feat(billing): aplicar IVA a los artículos de línea de la UE [BILL-91]
Usa Decimal para cálculos monetarios. Añade una prueba de regresión para líneas con cantidad cero.Lo que esto demuestra:
from __future__ import annotations para referencias futurasDecimal para moneda - no float_rate; métodos públicos tipadospyproject.toml.snake_case, clases PascalCase, constantes SCREAMING_SNAKE.from module import * comodín.| Tema | Convención |
|---|---|
| Cadenas | Se prefieren f-strings |
| Rutas | pathlib.Path no os.path.join |
| Excepciones | Tipos específicos; raise ... from exc |
| Logging | logging.getLogger(__name__) no print |
| Async | No IO bloqueante en rutas async def |
| Dinero | Decimal o centavos enteros |
# Extracto de pyproject.toml
[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM"]
ignore = ["E501"] # si el formateador maneja la longitud de líneauv sync fija las versiones de las herramientas.# type: ignore[arg-type] # BILL-99.0.1 + 0.2. Solución: Decimal o centavos enteros.except: vacío - Enmascara KeyboardInterrupt. Solución: capturar mínimo Exception, preferiblemente tipos específicos.| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
| Documento de reglas de python para toda la organización | Estándares entre equipos | Se necesitan anulaciones específicas del servicio |
| Ruff automatizado solamente | Equipo pequeño | La incorporación necesita ejemplos de texto |
| Guía de estilo de Python de Google | Referencia externa | Conflictos con la configuración de ruff |
| Sin guía de estilo | Nunca | Las revisiones discuten detalles triviales para siempre |
ruff format cuando ruff sea adoptado - una sola herramienta; no ejecutar ambas.
El formateador de ruff elige consistentemente - no pelear manualmente en la revisión.
API pública y locales no obvias - no name = "ada" en funciones pequeñas.
Sí, para módulos/clases/funciones públicas - estilo Google o numpy según README.
Elige una en pyproject.toml - cumple con las expectativas del formateador y revisores.
Absolutas from billing.domain import models en aplicaciones - relativas solo dentro de paquetes pequeños según ADR.
StrEnum o Literal para conjuntos pequeños y cerrados - documentar en la sección de type-hints.
test_<comportamiento>_cuando_<condición> - salida de fallo legible.
feat, fix, chore, docs, refactor, test - coincide con la automatización del changelog si la hay.
ADR o comentario en línea con la razón - no una única vez en silencio en un solo PR.
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+.
Revisado por Chris St. John·Última actualización: 16 jul 2026