Buenas Prácticas Fundamentales de Python

Hábitos centrales que mantienen el código Python legible, correcto y mantenible antes de recurrir a frameworks o herramientas de datos. Trata esto como una lista de verificación de incorporación para cada nuevo módulo o repositorio.

Cómo Usar Esta Lista

• Revísala al iniciar un nuevo paquete o al incorporar a un compañero de equipo.
• Aplícala durante la revisión de código para archivos que toquen fundamentos (E/S, importaciones, funciones).
• Vuelve a visitarla después de incidentes relacionados con la mutabilidad, la codificación o la deriva del entorno.
• Combínala con CI de ruff/mypy para que las reglas se vuelvan automáticas, no aspiracionales.

A - Entorno y Herramientas

• Crea un entorno virtual antes de instalar paquetes de terceros. Nunca contamines el Python del sistema (PEP 668).
• Fija las dependencias con pyproject.toml y un archivo de bloqueo (uv.lock). CI y clones reproducibles.
• Dirígete a características de Python 3.14+ solo cuando la versión del runtime lo permita. Documenta requires-python en pyproject.toml.
• Ejecuta ruff check y ruff format en cada PR. Retroalimentación rápida de estilo y linting.
• Habilita mypy o pyright incrementalmente en módulos nuevos. Los tipos se amortizan en los límites de la API.

B - Estilo de Código y Legibilidad

• Sigue la nomenclatura PEP 8: funciones snake_case, clases PascalCase, constantes UPPER.
• Prefiere f-strings sobre el formateo % y format() para código nuevo. Más claro y rápido.
• Usa pathlib.Path en lugar de la manipulación de cadenas de os.path. Uniones seguras multiplataforma.
• Mantén las funciones cortas con una responsabilidad clara. Extrae cuando el anidamiento exceda dos niveles.
• Escribe docstrings en módulos, clases y funciones públicas. Resumen de una línea más parámetros cuando no son obvios.

C - Datos y Corrección

• Nunca uses argumentos predeterminados mutables (def f(x=[])). Usa None y asigna en el interior.
• Usa Decimal para dinero, no float binario. Evita sorpresas de 0.1 + 0.2 en facturación.
• Especifica encoding="utf-8" en toda la E/S de archivos de texto. Previene errores predeterminados de la plataforma.
• Copia estructuras anidadas con copy.deepcopy cuando la independencia importa. Las copias superficiales comparten listas internas.
• Usa isinstance para comprobaciones de tipo, no type(x) is Cls en subclases. Amigable con el polimorfismo.

D - Flujo de Control y APIs

• Prefiere comprensiones o generadores sobre bucles append manuales al transformar secuencias. Legible y a menudo más rápido.
• Usa match/case para ramificación estructural en diccionarios y dataclasses. Más limpio que cadenas if profundas.
• Expón opciones solo por palabra clave después de * en APIs públicas. Previene sitios de llamada ambiguos.
• Protege scripts con if __name__ == "__main__":. Módulos importables sin efectos secundarios.
• Ejecuta paquetes con python -m package.module. Importaciones relativas y __package__ correctos.

E - Importaciones y Diseño

• Usa importaciones absolutas en código de aplicación (from myapp.utils import x). Más claro que las relativas en árboles grandes.
• Rompe importaciones circulares con importaciones perezosas o módulos types compartidos. Falla rápido en tiempo de diseño cuando sea posible.
• Evita sombrear nombres de módulos de la biblioteca estándar (json.py, types.py). Rompe importaciones misteriosamente.
• Adopta el diseño src/ para paquetes instalables. Previene importaciones accidentales desde la raíz del repositorio.
• Mantén los efectos secundarios en tiempo de importación al mínimo. Sin red ni base de datos al cargar módulos en bibliotecas.

Preguntas Frecuentes

Relacionados

• Fundamentos de Python - recorrido introductorio ejecutable
• Variables, Tipos y Tipado Dinámico - semántica de referencia
• Inicio Rápido de Entornos Virtuales - flujo de trabajo de uv
• Fundamentos de Anotaciones de Tipo - introducción al tipado estático

Versiones de la Pila: 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+.