Habilidad: Mejores Prácticas de Python
Refactorizaciones y auditorías idiomáticas - una Habilidad de Agente para la calidad de código de Python 3.14.
Qué Hace Esta Habilidad
Audita un paquete para encontrar modismos de Python: correcciones de lint/formato de ruff, pathlib sobre os.path, dataclasses vs dict, encadenamiento de excepciones, logging sobre print, olores de seguridad (eval, pickle, f-strings SQL), y produce un plan de refactorización en PR con niveles de riesgo.
Cuándo Invocar
- Módulo heredado antes de extraer a una biblioteca
- Pase de seguridad pre-lanzamiento
- Sprint de limpieza de incorporación en rutas críticas
- El PR se siente "Java-ish" o no idiomático
Entradas
| Entrada | Por qué |
|---|---|
| Ruta de destino | Alcance de src/billing/ |
| Tolerancia al riesgo | corrección automática segura vs revisión manual |
| Presencia de pruebas | requerida antes de refactorizaciones que cambian el comportamiento |
| Configuración de estilo | sección ruff.toml / pyproject de herramientas |
| Reglas del equipo | enlace a ADRs de la sección python-rules |
Salidas
- Resumen del diff de
ruff check --fixyruff format - Auditoría en Markdown: hallazgos críticos / mayores / menores
- ADR sugerido para patrones (Tipo de resultado, DI, etc.)
- Lista de brechas de pruebas si falta cobertura en módulos modificados
- Bloque de comando de verificación
Barreras de Protección
- Pruebas en verde antes y después - sin cambios de comportamiento imprevistos.
- Sin renombrado masivo sin advertencia - semver de API pública.
- Usar
raise ... from exc- preservar tracebacks. - Reemplazar argumentos predeterminados mutables - usar centinela
None. - Solo f-strings - no
%ni.formaten nuevas ediciones. - Alinear con 50 Reglas de Python cuando la organización las adopte.
Receta
uv run ruff check src/ --fix
uv run ruff format src/
uv run pytest -q
uv run mypy src/ # puerta opcionalEjemplo de Trabajo (corregir valor predeterminado mutable)
# antes
def add_item(item, bucket=[]):
bucket.append(item)
return bucket
# después
def add_item(item, bucket=None):
if bucket is None:
bucket = []
bucket.append(item)
return bucketPreguntas Frecuentes
¿Aplicar automáticamente todas las correcciones de ruff?
Solo correcciones seguras en el primer PR - las reglas inseguras requieren revisión humana por archivo.
¿Sigue siendo necesario Black?
ruff format reemplaza a Black cuando está habilitado - un formateador por repositorio.
Relacionado
- 50 Reglas de Python que Todo Especialista Debería Seguir - reglas
- Referencia de PEP 8 y Estilo - estilo
- Linting y Formateo - configuración de ruff
- Decisiones de Refactorización - cuándo refactorizar
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+.