@saulwade/swl-ses 1.4.1 → 1.5.0

package/habilidades/patrones-python/SKILL.md

@@ -1,229 +1,229 @@
----
-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.3.1"
-evolved: true
-evolved-from: "1.3.0"
-evolved-at: "2026-05-04"
-evolved-by: "aprender"
-evolved-note: "+1 gotcha: assert se elimina con PYTHONOPTIMIZE=1 — usar if/raise para invariantes (sync desde global tras sesión SIGM Fase 5b)"
-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`.
-
----
-
-## 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.
+---
+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.3.1"
+evolved: true
+evolved-from: "1.3.0"
+evolved-at: "2026-05-04"
+evolved-by: "aprender"
+evolved-note: "+1 gotcha: assert se elimina con PYTHONOPTIMIZE=1 — usar if/raise para invariantes (sync desde global tras sesión SIGM Fase 5b)"
+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`.
+
+---
+
+## 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.