🐍 Basada en PEP 8
Guía de Estilos Python
Convenciones de nomenclatura, estructura e imports para un código limpio y consistente
Referencia Rápida
Variables / Funciones
snake_case
Clases / Excepciones
CamelCase
Métodos Privados
_snake_case
Constantes
UPPER_CASE
Ficheros / Módulos
minusculas
Imports
① Estándar
import os import sys from datetime import datetime
② Terceros
import requests from flask import Flask
③ Locales
from resources.utils.fecha import ...
Importar módulos completos, no funciones sueltas cuando sea posible
Usar alias (
as) solo si el nombre es largo o hay conflicto Evitar
from module import * — causa conflictos y reduce legibilidad No agrupar imports en una línea:
import os, sys
Nomenclatura
Variables nombre_variable snake_case
Funciones calcular_total() snake_case
Privados _metodo_interno() _snake_case
Clases UsuarioAdmin CamelCase
Excepciones MiExcepcionError CamelCase + Error
Constantes TASA_INTERES_ANUAL UPPER_CASE
Módulos utils.py db_connection.py
# ❌ Incorrecto NombreVariable = "x" | nombreVariable = "x" def CalcularArea(r): pass class clase_de_ejemplo: pass
# ✅ Correcto nombre_variable = "x" def calcular_area(r): pass class ClaseDeEjemplo: pass
# ✅ Correcto nombre_variable = "x" def calcular_area(r): pass class ClaseDeEjemplo: pass
Tipado
Atributos de clase atributo: bool | None
Parámetros def fn(a: bool, b: str)
Retorno def fn(...) -> str:
# ❌ Incorrecto def funcion(atr1, atr2): return "Hola" if atr1 else atr2
# ✅ Correcto def funcion(atr1: bool, atr2: str) -> str: return "Hola" if atr1 else atr2
# Clase tipada
# ✅ Correcto def funcion(atr1: bool, atr2: str) -> str: return "Hola" if atr1 else atr2
# Clase tipada
class Ejemplo:
activo: bool | None nombre: str = "default"
Constantes y Enum
❌ Incorrecto
tasa_interes = 0.05
class EstadoPedidoInt(Enum):
pendiente = 1 en_proceso = 2 ✅ Correcto
TASA_INTERES = 0.05
class EstadoPedidoInt(IntEnum):
PENDIENTE = 1 EN_PROCESO = 2 class EstadoPedidoStr(StrEnum):
PENDIENTE = "Solicitado" EN_PROCESO = "En preparacion" Usar
IntEnum / StrEnum en lugar de (int, Enum) para evitar el uso excesivo de .value Miembros del Enum siempre en MAYÚSCULAS, la clase en CamelCase
Estructura de Ficheros y Carpetas
- mi_servicio/
- main.py# Punto de entrada
- Dockerfile
- resources/
- models/# Modelos y parseadores
- transaction.py
- request.py
- exceptions/# Excepciones personalizadas
- constants/# Constantes y Enums
- repositories/# Interfaces e implementaciones
- utils/# Utilidades del micro
-
- routes/
- router.py
- services/
- service.py
- tests/
- unit/
- integration/
Carpetas y ficheros en minúsculas, sin espacios. Guiones bajos si es necesario.
Módulos con nombres cortos:
utils.py, helpers.py. Evitar guiones bajos si es posible. Prefijo de fichero indica su tipo:
excep_, const_, interface_ Tests en carpeta
tests/ con subcarpetas unit/ e integration/. Cada microservicio tiene su propia estructura independiente. No compartir carpetas entre servicios.
Documentación — Docstrings Google Style
Módulo / Script
""" Descripción breve del módulo.
Descripción más detallada si es necesario. """
Descripción más detallada si es necesario. """
Clase
class MiClase:
"""Descripción de la clase. Attributes: atributo: Descripción. """
Función / Método
def mi_funcion(x: int) -> str:
"""Descripción breve. Args: x (int): Descripción del param.
Returns: str: Descripción del retorno.
Raises: ValueError: Si x es negativo. """
Usar
"""docstring""" en clases, métodos y scripts para documentar su propósito Seguir el formato Google: secciones con nombre seguido de dos puntos (
Args:, Returns:, Raises:, Attributes:) con contenido indentado 4 espacios Documentar qué hace, no cómo lo hace. El código debe ser autoexplicativo