---
name: patrones-python
description: Idiomas pythonicos, PEP 8, type hints modernos, dataclasses, async/await, context managers, decorators y generators. Patrones de código limpio en Python.
version: "1.4.2"
evolved: true
evolved-from: "1.4.1"
evolved-at: "2026-06-05"
evolved-by: "evolucionar"
evolved-note: "+gotcha PEP 758: except A,B: sin paréntesis es válido en Python >=3.14, no SyntaxError; cubre efecto colateral de ruff format (target py314) reformateando archivo completo. Origen: falso positivo reproducible en sistema-verificacion-oic (requires-python >=3.14)"
herramientasPermitidas: [Read, Glob, Grep]
exclusiones:
  - "No cargar para patrones de un framework específico (FastAPI, Django, Celery) — los idiomas generales de este skill aplican, pero los patrones de framework tienen restricciones adicionales; cargar el skill del framework correspondiente."
  - "No cargar para errores de instalación o dependencias Python — si el problema es pip, virtualenv o incompatibilidad de versiones, cargar `build-errors-python`."
  - "No cargar para patrones de concurrencia avanzados (TaskGroup, semáforos, event loops) — para esos cargar `async-python` que cubre asyncio en profundidad."
  - "No cargar para testing pytest (fixtures, mocking, cobertura) — ese dominio está en `testing-python` que cubre la toolchain completa de tests."
evolvable: true  # default para skill estandar
---
# Patrones Python

## Cuándo NO cargar

- La tarea es específica de FastAPI o Django — cargar el skill del framework que tiene restricciones adicionales a los patrones generales.
- El problema es de instalación de dependencias Python — cargar `build-errors-python`.
- La pregunta es sobre concurrencia avanzada con asyncio — cargar `async-python`.

## PEP 8 — Convenciones de estilo

### Nomenclatura

```python
# Módulos y paquetes: snake_case minúsculas
import mi_modulo

# Clases: PascalCase
class FacturaElectronica:
    pass

# Funciones y variables: snake_case
def calcular_iva(monto: float) -> float:
    tasa_iva = 0.16
    return monto * tasa_iva

# Constantes: UPPER_SNAKE_CASE
MAX_REINTENTOS = 3
URL_BASE_API = "https://api.ejemplo.com/v1"

# Variables privadas de instancia: prefijo _
class Factura:
    def __init__(self):
        self._numero_interno = None  # privado por convención
```

### Longitud de línea y formato

```python
# Máximo 88 caracteres (configuración Black estándar)

# Importaciones agrupadas:
# 1. Stdlib
import os
from pathlib import Path

# 2. Terceros
from fastapi import FastAPI, Depends
from sqlalchemy.orm import Session

# 3. Módulos locales
from app.models.usuario import Usuario
```

---

## Type Hints modernos (Python 3.10+)

```python
# Union con | en vez de Union[X, Y]
def procesar(valor: int | str | None) -> str:
    return str(valor or "")

# list, dict, tuple nativos (no de typing)
def filtrar(items: list[str], lookup: dict[str, int]) -> list[str]:
    return [i for i in items if i in lookup]

# TypeAlias explícito
type JSON = dict[str, "JSON"] | list["JSON"] | str | int | float | bool | None

# ParamSpec para decoradores que preservan firma
from typing import ParamSpec, Callable
P = ParamSpec("P")

def con_log(fn: Callable[P, T]) -> Callable[P, T]:
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
        print(f"Llamando {fn.__name__}")
        return fn(*args, **kwargs)
    return wrapper
```

---

## Dataclasses

```python
from dataclasses import dataclass, field
from datetime import datetime

@dataclass
class Producto:
    id: str
    nombre: str
    precio: float
    activo: bool = True
    etiquetas: list[str] = field(default_factory=list)

    def __post_init__(self) -> None:
        if self.precio < 0:
            raise ValueError(f"Precio no puede ser negativo: {self.precio}")
        self.nombre = self.nombre.strip()

# Dataclass inmutable
@dataclass(frozen=True)
class Coordenada:
    latitud: float
    longitud: float

# Dataclass con slots (Python 3.10+) — ahorra memoria
@dataclass(slots=True)
class EventoAuditoria:
    usuario_id: str
    accion: str
    timestamp: datetime
```

---

## Context Managers

```python
from contextlib import contextmanager, asynccontextmanager

# Context manager con generador
@contextmanager
def medir_tiempo(nombre: str):
    inicio = time.perf_counter()
    try:
        yield
    finally:
        transcurrido = time.perf_counter() - inicio
        print(f"{nombre}: {transcurrido:.4f}s")

# Context manager async
@asynccontextmanager
async def sesion_db(engine):
    async with engine.begin() as conn:
        try:
            yield conn
            await conn.commit()
        except Exception:
            await conn.rollback()
            raise
```

---

## Anti-patrones Python Críticos

```python
# MAL: argumento mutable como default
def agregar(item, lista=[]):   # La lista persiste entre llamadas
    lista.append(item)

# BIEN: usar None como centinela
def agregar(item, lista=None):
    if lista is None:
        lista = []
    lista.append(item)

# MAL: bare except
try:
    operacion_riesgosa()
except:
    pass  # silencia KeyboardInterrupt y SystemExit

# BIEN: excepción específica
try:
    operacion_riesgosa()
except ValueError as e:
    logger.error(f"Valor inválido: {e}")

# MAL: concatenación en loop (O(n²))
resultado = ""
for parte in partes:
    resultado += parte

# BIEN: join (O(n))
resultado = "".join(partes)
```

Para generators, decoradores avanzados, async/await y manejo de errores idiomático,
ver [recursos/referencia-completa.md](recursos/referencia-completa.md).

## Gotchas / Errores comunes no obvios

- **`dataclass` con campo mutable como default (`field: list = []`) produce un objeto compartido entre todas las instancias**: Python reutiliza el objeto por defecto en vez de crear uno nuevo. Causa: los defaults de dataclass se evalúan en tiempo de definición de la clase, no en cada instanciación — una lista mutable como default es el mismo objeto en memoria para todas las instancias. Solución: usar `field(default_factory=list)` para campos mutables: `from dataclasses import field; tags: list = field(default_factory=list)`.
- **Decorator que usa `functools.wraps` pero no preserva type hints si la función decorada tiene anotaciones genéricas**: el `@wraps` copia `__wrapped__`, `__doc__` y `__name__`, pero el tipo de retorno inferido por `mypy` es el del wrapper, no el del wrapped. Causa: `functools.wraps` no puede preservar el tipado estático del wrapped — mypy ve el tipo del wrapper `Callable[..., Any]`. Solución: usar `TypeVar` y tipado genérico en el decorator con `ParamSpec` (Python 3.10+): `P = ParamSpec('P'); T = TypeVar('T')` y tipar el wrapper como `Callable[P, T]`.
- **`__slots__` en clase Python produce `TypeError: multiple bases have instance lay-out conflict`** al heredar de otra clase con `__slots__`: las subclases con `__slots__` requieren que todos los ancestros también tengan `__slots__`, o que el ancestro directo sea `object`. Causa: si `ClaseBase` no tiene `__slots__`, tiene un `__dict__` implícito; si `ClaseHija` tiene `__slots__`, hay conflicto de layout de memoria. Solución: o agregar `__slots__ = ()` vacío a la clase base, o eliminar `__slots__` de la subclase — no mezclar clases con y sin `__slots__` en la misma jerarquía.
- **`property` setter que modifica un campo privado no refleja el cambio en `__repr__` generado por dataclass**: el `@property` en un dataclass crea un campo de clase que conflictúa con el campo de instancia del dataclass. Causa: `@dataclass` genera `__repr__` basado en los campos declarados en `__init__` — si el setter modifica un atributo con nombre diferente (ej: `_valor`), `__repr__` muestra el campo original sin la modificación. Solución: usar `field(init=False, repr=False)` para el campo interno y exponer solo la `property` en la interfaz pública.
- **`assert` no es guard de invariantes en producción con `PYTHONOPTIMIZE=1` o `python -O`**: el bytecode optimizado **elimina** todos los `assert` del módulo, por lo que `assert x is not None; return x` puede retornar `None` violando el contrato `-> dict` en producción aunque pase tests en desarrollo. El test runner por defecto NO usa `-O`, por lo que el bug es invisible hasta que alguien despliega con `PYTHONOPTIMIZE=1` (configuración común para reducir memoria en imágenes Docker production). Causa: `assert` está documentado en Python como herramienta de **debugging**, no de validación. Solución: para invariantes que DEBEN cumplirse en producción, usar guard explícito con raise: `if x is None: raise HTTPException(500, "Invariante violado")` o `if x is None: raise RuntimeError(...)`. Reservar `assert` solo para tests, scripts, o pre-condiciones triviales en código de desarrollo. Regla rápida: si el assert protege un caso que activa una respuesta del usuario o un side-effect, NO es assert — es validación y debe ser `if/raise`.
- **Pasar `None` explícito a un parámetro NO activa su valor por defecto en el callee**: si una función declara `def listar(activa: bool = True)` y el caller hace `listar(activa=valor)` donde `valor` puede ser `None` (típico con parámetros opcionales que viajan entre capas: `activa: bool | None = None`), el callee recibe `None`, NO `True`. Python aplica el default SOLO cuando el argumento se **omite literalmente** en la llamada, no cuando recibe `None` explícito. Causa: el binding del parámetro usa el valor pasado, sea cual sea — el default es fallback de *ausencia*, no de *nulidad*. El bug es silencioso: pasa los tests donde el caller omite el parámetro y falla en producción cuando el cliente omite el valor y una capa intermedia lo traduce a `None` antes de propagarlo. Caso real: un endpoint que documentaba "omitir devuelve solo activos" retornaba inactivos porque el router pasaba `activa=None` al service cuyo default era `True`. Solución: normalizar en la frontera — en el caller (`listar(activa=True if valor is None else valor)`) o tratando `None` como sentinel en el callee (`if activa is None: activa = True`). Regla: cuando un valor opcional cruza de una capa a otra y el callee tiene un default distinto de `None`, convertir `None → default` explícitamente en el punto de cruce.
- **`getattr(obj, "attr", default)` tampoco aplica `default` si el atributo existe con valor `None`**: misma raíz que el gotcha anterior, otra manifestación. `getattr` usa `default` SOLO cuando el atributo **no existe**; si existe con valor `None` (caso típico: campos opcionales de Pydantic/SQLAlchemy inicializados a `None`), devuelve `None`, no `default`. Así `getattr(modelo, "campo_opcional", "X")` retorna `None` cuando `campo_opcional is None`, no `"X"`. Solución sin ambigüedad: `raw = getattr(modelo, "campo_opcional", None); valor = raw if raw is not None else "X"` (el atajo `getattr(...) or "X"` solo sirve si `""` y `0` son aceptables como falsy). Regla unificada para ambos casos: en Python el `default` —de parámetro o de `getattr`— es fallback de **ausencia**, nunca de **nulidad**; si `None` es un valor posible, normalízalo en la frontera.
- **`except A, B:` sin paréntesis es sintaxis válida en Python ≥3.14 (PEP 758), NO un SyntaxError**: desde 3.14 los paréntesis en `except`/`except*` con múltiples tipos son opcionales (`except ValueError, TypeError:` ≡ `except (ValueError, TypeError):`). Bajo intérpretes <3.14 esa forma SÍ es SyntaxError, lo que confunde a herramientas y revisores que juzgan la sintaxis contra su conocimiento general del lenguaje en vez de contra la versión objetivo del proyecto (`requires-python`/`tool.ruff.target-version` en `pyproject.toml`). Causa: la validez de la sintaxis depende de la versión, no es absoluta. Efecto colateral a vigilar: `ruff format` con `target-version = "py314"` **quita** los paréntesis redundantes y, además, reformatea el archivo COMPLETO — puede tocar `except` ajenos a tu cambio (churn no intencional); `ruff check` (lo único que suele correr el CI) conserva la forma que encuentre. Solución: antes de marcar cualquier `except A, B:` como error, leer la versión objetivo del proyecto y verificar con evidencia ejecutable (`python -c "import <módulo>"` + `ruff check`). Si se prefieren los paréntesis por portabilidad/Pyright, restaurarlos a mano y NO correr `ruff format` sobre esas líneas. Caso real (2026-06-05): un proyecto con `requires-python >=3.14` recibió un falso positivo de SyntaxError CRÍTICO por esta forma; refutado con import + ruff + CI verde.

---

## Patrones avanzados (carga bajo demanda)

Los siguientes patrones aparecen al integrar Python con pipelines reales
(conversores de documentos, clientes heterogéneos, cachés determinísticos,
detectores de texto, duplicación deliberada de lógica). El detalle completo
está en [recursos/patrones-avanzados.md](recursos/patrones-avanzados.md).

| # | Patrón | Cargar cuando |
|---|--------|---------------|
| 1 | Normalizadores: colapsar al formato canónico del PROYECTO | escribir `_normalizar(texto)` después de un conversor externo (MarkItDown, Pandoc, mammoth) |
| 2 | kwargs opcionales entre clientes hermanos: try/except TypeError | propagar un kwarg nuevo a clientes con signature heterogénea sin romper la interfaz |
| 3 | Caché content-addressable por SHA256 | función pura costosa (>1 s) que se invoca repetidamente con los mismos inputs |
| 4 | F401 en archivos con soft imports es intencional | módulo importa una dependencia opcional dentro de `try/except ImportError` |
| 5 | Detectores regex multi-pattern: extender scope sin refinar genera FP | un detector con OR de patterns se va a aplicar a un texto más ruidoso que el original |
| 6 | Tracer/replicador paralelo del motor: marca SYNC obligatoria | duplicar lógica del motor para telemetría, explainability o shadow runs |
| 7 | Fixtures con datos pre-procesados NO ejercen el path crudo | el motor prefiere leer un campo crudo opcional sobre uno condensado, y los fixtures son condensados |

Cargar la sección específica del recurso cuando aplique al problema en mano —
no cargar el archivo completo si solo se necesita un patrón.
