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

Salidas

• Resumen del diff de ruff check --fix y ruff 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

1. Pruebas en verde antes y después - sin cambios de comportamiento imprevistos.
2. Sin renombrado masivo sin advertencia - semver de API pública.
3. Usar raise ... from exc - preservar tracebacks.
4. Reemplazar argumentos predeterminados mutables - usar centinela None.
5. Solo f-strings - no % ni .format en nuevas ediciones.
6. 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 opcional

Ejemplo 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 bucket

Preguntas Frecuentes

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+.