50 Reglas de Python que Todo Especialista Debería Seguir

Una lista de verificación maestra de hábitos que separan el Python de producción del código de tutorial. Agrupadas por dominio; cada regla es accionable y aplicable con herramientas donde se indica.

Receta

Escanee esta lista trimestralmente. Habilite las reglas de ruff/mypy que automaticen cada elemento "aplicable".

Cuándo recurrir a esto:

• Incorporación de desarrolladores Python senior
• Revisiones de arquitectura y bases para auditorías de código
• Configuración de políticas de linting y CI para el equipo

Referencia de Reglas de Python

Análisis Profundo

Estilo y Legibilidad (1-10)

1. Siga PEP 8 - Líneas de 88 caracteres con ruff format; sin debates manuales de estilo.
2. Use nombres descriptivos - total_factura, no x o tmp.
3. Prefiera f-strings - f"{nombre}" en lugar de "{}".format() y formato %.
4. Orden de importación: stdlib, terceros, propios - deje que ruff isort lo aplique.
5. Una declaración por línea - sin cadenas de punto y coma ni if foo: bar() compuestos.
6. Lo explícito es mejor que lo implícito - sin números mágicos; use constantes con nombre.
7. Lo plano es mejor que lo anidado - retornos tempranos en lugar de indentación de 5 niveles.
8. Use pathlib.Path - no os.path.join para código nuevo.
9. Use enum.Enum - para conjuntos fijos de constantes, no literales de cadena.
10. Docstrings en APIs públicas - estilo Google o NumPy; mínimo de una línea.

Tipos y Contratos (11-20)

11. Tipifique todas las funciones públicas - parámetros y tipos de retorno.
12. Ejecute mypy o pyright en CI - los tipos son contratos, no sugerencias.
13. Use X | None, no Optional[X] - sintaxis de unión de Python 3.14.
14. Prefiera list[str] sobre List[str] - genéricos incorporados (PEP 585).
15. Use TypedDict o Pydantic - para diccionarios estructurados, no dict sin más.
16. Estreche tipos con isinstance - no comprobaciones type() sin más.
17. Use Protocol para duck typing - subtipado estructural sobre ABCs cuando sea apropiado.
18. Marque any intencional con comentarios - # type: ignore necesita una razón.
19. Dataclasses para contenedores de datos - frozen=True cuando sea inmutable.
20. Pydantic 2 para límites de validación - entrada HTTP, configuración, datos externos.

Estructura y Módulos (21-30)

21. Diseño src/ - paquete instalable y testeable como lo ven los consumidores.
22. Una responsabilidad por módulo - archivos de menos de 300 líneas; dividir cuando sean más grandes.
23. Sin importaciones circulares - reestructure o use importaciones perezosas TYPE_CHECKING.
24. Importaciones absolutas - from myapp.services import billing, no cadenas de puntos relativas en bibliotecas.
25. __all__ explícito - para la superficie de API pública del paquete.
26. Sin lógica en __init__.py - solo reexportaciones; manténgalo delgado.
27. Inyección de dependencias sobre globales - pase dependencias como parámetros o fixtures.
28. Configuración a través de entorno + pydantic-settings - no secretos o rutas codificadas.
29. Separe el dominio de la E/S - funciones puras testeables sin mocks.
30. Use pyproject.toml - configuración única para dependencias, herramientas y compilación.

Errores y Pruebas (31-40)

31. Excepciones específicas - raise ValueError("pct debe ser 0-100"), no raise Exception sin más.
32. Nunca oculte excepciones - except: pass es casi siempre incorrecto.
33. Use encadenamiento de excepciones - raise NewError(...) from original.
34. Gestores de contexto para recursos - with open(...) y @contextmanager.
35. pytest para todas las pruebas - sin código repetitivo de unittest para código nuevo.
36. Un comportamiento por prueba - nombres descriptivos: test_discount_over_100_raises.
37. Mock en los límites - HTTP, DB, sistema de archivos; no lógica interna.
38. Suelo de cobertura del 80% - cobertura de ramas en módulos críticos.
39. Sin print en bibliotecas - use logging con un logger a nivel de módulo.
40. Logging estructurado en producción - logs JSON con IDs de correlación.

Seguridad y Operaciones (41-50)

41. Nunca confirme secretos - variables de entorno, gestores de secretos, .env gitignoreado.
42. Fije las dependencias - lockfile confirmado; uv sync --frozen en CI.
43. Valide toda la entrada externa - Pydantic en los límites de la API.
44. Use el módulo secrets - no random para tokens y contraseñas.
45. SQL parametrizado - nunca haga f-string a consultas SQL.
46. Mantenga Python actualizado - parches de seguridad dentro de los 30 días posteriores al lanzamiento.
47. Ejecute pip-audit en CI - escaneo semanal de vulnerabilidades de dependencias.
48. Mínimo privilegio - permisos mínimos de IAM, DB y acceso a archivos.
49. Apagado elegante - maneje SIGTERM; vacíe logs y cierre conexiones.
50. Mida antes de optimizar - perfile primero; legibilidad por defecto sobre velocidad.

Trampas Comunes

• Tratar las reglas como dogma - el contexto importa; documente excepciones en ADRs. Solución: las reglas guían los valores predeterminados, no los absolutos.
• Habilitar todas las reglas de ruff desde el primer día - fatiga de alertas. Solución: adopte incrementalmente por grupo arriba.
• Tipos sin pruebas - mypy en verde pero comportamiento incorrecto. Solución: combine tipos con cobertura de pytest.
• 50 reglas, cero automatización - las reglas decaen sin CI. Solución: mapee reglas a puertas de ruff/mypy/pre-commit.
• Aplicar reglas de biblioteca a scripts - los scripts únicos pueden relajar las reglas de estructura. Solución: escale las reglas por tipo de paquete.

Alternativas

Preguntas Frecuentes

Relacionados

• Referencia de PEP 8 y Estilo - detalles de estilo
• 30 Reglas de Seguridad para Python - análisis profundo de seguridad
• Decisiones de Arquitectura Python - decisiones estructurales
• Mejores Prácticas de Linting y Formateo - aplicación de herramientas

Versiones de Stack: Esta página fue escrita para Python 3.14.0, 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+.