@saulwade/swl-ses 1.0.0

package/habilidades/async-python/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: async-python
+description: Patrones avanzados de async/await en Python. asyncio, aiohttp, SQLAlchemy async, concurrencia, semáforos, task groups, error handling en async, testing. Anti-patrones comunes de código asíncrono.
+version: "1.0.0"
+herramientasPermitidas: [Read]
+exclusiones:
+  - "No cargar para paralelismo CPU-bound con múltiples núcleos — `asyncio` es monohilo y no aprovecha múltiples CPUs; para paralelismo CPU-bound usar `multiprocessing` o `concurrent.futures.ProcessPoolExecutor`."
+  - "No cargar para scripts Python de una sola ejecución sin I/O concurrente — si el script hace una sola operación I/O secuencial, `requests` síncrono es más simple y correcto que introducir asyncio."
+  - "No cargar cuando el framework ya maneja la concurrencia (FastAPI, Django Channels) y la pregunta es sobre la lógica de endpoints — en ese contexto cargar `fastapi-experto` o `django-experto` que cubren el uso de async en su framework específico."
+  - "No cargar para orquestación de agentes SWL en paralelo — ese patrón tiene semántica diferente (fire-and-forget, corrección mid-task, supervisión); cargar `orquestacion-async`."
+evolvable: true  # default para skill estandar
+---
+# Async Python — Patrones Avanzados
+
+## Cuándo NO cargar
+
+- La tarea es CPU-bound (cálculos numéricos, procesamiento de imágenes) — asyncio no paralela CPU; usar `multiprocessing`.
+- El script hace una sola operación I/O sin concurrencia — `requests` síncrono es más simple y adecuado.
+- La pregunta es sobre endpoints en FastAPI o Django — cargar el skill del framework que ya incorpora el contexto async correcto.
+
+asyncio es el núcleo de I/O asíncrono en Python. Este skill cubre desde patrones básicos
+hasta orquestación avanzada de tareas concurrentes para sistemas de producción.
+
+---
+
+## Reglas Obligatorias
+
+1. **NUNCA bloquear el event loop** con operaciones síncronas (`requests`, `time.sleep`, I/O de disco síncrono). Usar clientes async (`aiohttp`, `httpx`, `asyncio.sleep`).
+2. **SIEMPRE usar `async with` para sesiones HTTP** — nunca dejar sesiones aiohttp sin cerrar (file descriptor leak).
+3. **SIEMPRE usar `expire_on_commit=False`** en `async_sessionmaker` de SQLAlchemy — el default causa `MissingGreenlet` en async.
+4. **SIEMPRE usar `selectinload`** para relaciones ORM accedidas fuera de la sesión activa.
+5. **NUNCA llamar `asyncio.run()` dentro de una coroutine** — causa `RuntimeError: loop anidado`.
+6. **SIEMPRE poner timeout en llamadas HTTP** — sin timeout puede colgar indefinidamente.
+7. **Una sesión SQLAlchemy por request/task** — compartir sesiones entre tasks causa race conditions.
+
+---
+
+## Fundamentos: Event Loop y Coroutines
+
+```python
+# MAL: bloquear el event loop con operaciones síncronas
+async def descargar_archivo_mal(url: str) -> bytes:
+    import requests                      # ¡síncrono! bloquea el loop
+    return requests.get(url).content
+
+# BIEN: usar clientes async
+import aiohttp
+
+async def descargar_archivo(url: str) -> bytes:
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url) as response:
+            response.raise_for_status()
+            return await response.read()
+```
+
+---
+
+## Semáforos — Control de concurrencia máxima
+
+```python
+# MAL: lanzar 1000 requests simultáneos sin límite
+async def fetch_todo_mal(urls: list[str]) -> list[str]:
+    tasks = [fetch_url(url) for url in urls]  # ¡sobrecarga el servidor!
+    return await asyncio.gather(*tasks)
+
+# BIEN: limitar concurrencia con Semaphore
+async def fetch_url_limitado(
+    session: aiohttp.ClientSession, url: str, sem: asyncio.Semaphore,
+) -> str:
+    async with sem:
+        async with session.get(url) as resp:
+            return await resp.text()
+
+async def fetch_todo_con_limite(urls: list[str], max_concurrente: int = 10) -> list[str]:
+    sem = asyncio.Semaphore(max_concurrente)
+    async with aiohttp.ClientSession() as session:
+        tasks = [fetch_url_limitado(session, url, sem) for url in urls]
+        return await asyncio.gather(*tasks, return_exceptions=True)
+```
+
+---
+
+## SQLAlchemy Async — Reglas críticas
+
+```python
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker
+from sqlalchemy.orm import selectinload
+from sqlalchemy import select
+
+engine = create_async_engine(
+    "postgresql+asyncpg://user:pass@localhost/db",
+    pool_size=20, max_overflow=0, pool_pre_ping=True,
+)
+
+AsyncSessionLocal = async_sessionmaker(
+    engine, expire_on_commit=False, class_=AsyncSession,  # CRÍTICO
+)
+
+# REGLA: selectinload SIEMPRE para relaciones accedidas fuera de la sesión
+async def obtener_usuario_con_roles(db: AsyncSession, usuario_id: str) -> Usuario:
+    stmt = (
+        select(Usuario).where(Usuario.id == usuario_id)
+        .options(selectinload(Usuario.roles), selectinload(Usuario.departamento))
+    )
+    result = await db.execute(stmt)
+    return result.scalar_one_or_none()
+```
+
+---
+
+## Timeouts y Cancelación
+
+```python
+# BIEN: timeout en múltiples niveles
+async def llamar_api(url: str, timeout_seg: float = 5.0) -> dict:
+    try:
+        async with asyncio.timeout(timeout_seg):
+            async with aiohttp.ClientSession() as s:
+                async with s.get(url, timeout=aiohttp.ClientTimeout(total=timeout_seg)) as r:
+                    r.raise_for_status()
+                    return await r.json()
+    except asyncio.TimeoutError:
+        raise TimeoutError(f"La API no respondió en {timeout_seg}s: {url}")
+```
+
+---
+
+## Anti-patrones Comunes
+
+| Anti-patrón | Consecuencia | Corrección |
+|-------------|-------------|------------|
+| Llamar función síncrona bloqueante en coroutine | Bloquea event loop completo | `loop.run_in_executor(None, func)` |
+| Crear engine SQLAlchemy dentro de coroutine | Conexiones huérfanas | Engine singleton a nivel de módulo |
+| `await` dentro de list comprehension sin gather | Ejecución secuencial (lenta) | `asyncio.gather(*[coro(x) for x in xs])` |
+| No cerrar sesiones aiohttp | File descriptor leak | Siempre `async with ClientSession()` |
+| `asyncio.run()` dentro de coroutine | RuntimeError: loop anidado | Solo llamar en código síncrono top-level |
+| Compartir objetos de sesión SQLAlchemy entre tasks | Race conditions | Una sesión por request/task |
+| `expire_on_commit=True` (default) con async | Lazy-load fuera de sesión falla | `expire_on_commit=False` en async |
+
+---
+
+Para ejemplos completos de gather, TaskGroup, queues async, context managers, error handling con reintento, testing async y service HTTP con pool de conexiones, ver [recursos/patrones-y-ejemplos-completos.md](recursos/patrones-y-ejemplos-completos.md).
+
+## Gotchas / Errores comunes no obvios
+
+- **`asyncio.gather()` con `return_exceptions=False` (default) cancela silenciosamente tareas exitosas cuando una falla**: si una de las coroutines lanza excepción, `gather` cancela el resto y la excepción se propaga, pero las tareas ya en progreso pueden dejar estado parcial. Causa: `return_exceptions=False` propaga la primera excepción inmediatamente y cancela el `gather`, pero no espera a que las tasks canceladas hagan cleanup. Solución: usar `return_exceptions=True` para obtener todos los resultados/excepciones, o `asyncio.TaskGroup` (Python 3.11+) que garantiza que todas las tasks se completan antes de propagar errores.
+- **`loop.run_in_executor(None, func_sincrona)` bloquea el event loop cuando se llama con alta frecuencia**: el executor por defecto es un `ThreadPoolExecutor` con un número limitado de workers (CPU count × 5). Causa: si se hacen 1000 llamadas simultáneas a `run_in_executor`, las threads se agotan y las nuevas tasks quedan en cola, bloqueando el event loop. Solución: crear un executor explícito con el número de workers apropiado: `executor = ThreadPoolExecutor(max_workers=50)` y pasarlo como primer argumento a `run_in_executor`.
+- **`async with aiohttp.ClientSession()` creado dentro de la coroutine crea y destruye la sesión en cada llamada, anulando los beneficios del pooling**: la sesión aiohttp mantiene un pool de conexiones TCP — si se crea una sesión nueva por cada request, no hay pooling. Causa: la sesión es liviana de crear pero destruye las conexiones keepalive al hacer `await session.close()`. Solución: crear la sesión como singleton a nivel de módulo o en el lifespan de la app (`async with aiohttp.ClientSession() as session:` en el contexto de arranque, no en cada handler).
+- **`await asyncio.sleep(0)` en un bucle no es suficiente para que otras coroutines corran si el bucle hace I/O bloqueante entre los sleeps**: el `sleep(0)` cede el control al event loop pero si la siguiente operación es síncrona/bloqueante, el loop queda bloqueado de nuevo. Causa: `asyncio.sleep(0)` es un yield point que permite al event loop ejecutar callbacks pendientes, pero si la operación siguiente es síncrona, el bloqueo reaparece inmediatamente. Solución: identificar la operación I/O bloqueante con `asyncio.run()` + `--profile` o usar `asyncio.iscoroutinefunction()` para verificar que las funciones llamadas son realmente async.

package/habilidades/async-python/evals/evals.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "../../../schemas/skill-evals.schema.json",
+  "skill_name": "async-python",
+  "artifact_type": "skill",
+  "schema_version": 1,
+  "description": "Evals para async-python — asyncio, patrones correctos de concurrencia, SQLAlchemy async.",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "Ejecutar 3 requests HTTP concurrentemente con httpx async — snippet minimal.",
+      "files": [],
+      "expectations": [
+        "Usa `asyncio.gather(...)` (no secuencial).",
+        "Usa `async with httpx.AsyncClient()` (no sync Client).",
+        "NO mezcla `requests` con async."
+      ],
+      "tags": ["primary-flow", "concurrency"],
+      "weight": 1.5
+    },
+    {
+      "id": "sqlalchemy-relationship",
+      "prompt": "En SQLAlchemy async, tengo `class User: orders = relationship('Order')`. ¿Qué necesito para serializar `user.orders` con Pydantic?",
+      "files": [],
+      "expectations": [
+        "La respuesta menciona `selectinload(User.orders)` en el query.",
+        "La respuesta menciona el error `MissingGreenlet` si no se carga eagerly.",
+        "La respuesta menciona `lazy='selectin'` como alternativa si es relación frecuente."
+      ],
+      "grading_guidance": "Failure si no menciona selectinload o MissingGreenlet.",
+      "tags": ["sqlalchemy", "anti-pattern"],
+      "weight": 2.0
+    },
+    {
+      "id": "anti-pattern-sync-in-async",
+      "prompt": "¿Qué pasa si llamo `time.sleep(5)` dentro de un `async def`?",
+      "files": [],
+      "expectations": [
+        "La respuesta identifica que bloquea el event loop entero.",
+        "La respuesta da la solución: `await asyncio.sleep(5)`.",
+        "La respuesta menciona que cualquier llamada sync bloqueante tiene este problema (open, requests, time.sleep)."
+      ],
+      "grading_guidance": "Failure si sugiere que `time.sleep` funciona en async.",
+      "tags": ["anti-pattern"],
+      "weight": 1.5
+    }
+  ]
+}

package/habilidades/async-python/recursos/patrones-y-ejemplos-completos.md

@@ -0,0 +1,292 @@
+# Async Python — Patrones y Ejemplos Completos
+
+Referencia extendida de la skill `async-python`. Contiene ejemplos de código completos
+y patrones avanzados que complementan las instrucciones principales en SKILL.md.
+
+---
+
+## asyncio.gather — Concurrencia de tareas independientes
+
+```python
+import asyncio
+import aiohttp
+from typing import NamedTuple
+
+class ResultadoAPI(NamedTuple):
+    url: str
+    datos: dict | None
+    error: str | None
+
+async def fetch_json(session: aiohttp.ClientSession, url: str) -> dict:
+    async with session.get(url, timeout=aiohttp.ClientTimeout(total=10)) as resp:
+        resp.raise_for_status()
+        return await resp.json()
+
+async def fetch_multiples(urls: list[str]) -> list[ResultadoAPI]:
+    """Descarga múltiples URLs concurrentemente con manejo de errores individual."""
+    async with aiohttp.ClientSession() as session:
+        tasks = [fetch_json(session, url) for url in urls]
+        # return_exceptions=True evita que un error cancele todas las tareas
+        resultados = await asyncio.gather(*tasks, return_exceptions=True)
+
+    return [
+        ResultadoAPI(
+            url=url,
+            datos=r if not isinstance(r, Exception) else None,
+            error=str(r) if isinstance(r, Exception) else None,
+        )
+        for url, r in zip(urls, resultados)
+    ]
+```
+
+---
+
+## asyncio.TaskGroup — Python 3.11+
+
+```python
+import asyncio
+from contextlib import asynccontextmanager
+
+async def procesar_lote(ids: list[int]) -> list[dict]:
+    """TaskGroup cancela TODAS las tareas si una falla — comportamiento más seguro."""
+    resultados: list[dict] = []
+
+    async with asyncio.TaskGroup() as tg:
+        tasks = [
+            tg.create_task(obtener_registro(id_), name=f"registro-{id_}")
+            for id_ in ids
+        ]
+    return [t.result() for t in tasks]
+
+async def obtener_registro(id_: int) -> dict:
+    await asyncio.sleep(0.1)  # Simular I/O
+    return {"id": id_, "nombre": f"Registro {id_}"}
+```
+
+---
+
+## Context Managers Asíncronos
+
+```python
+from contextlib import asynccontextmanager
+import asyncio
+
+@asynccontextmanager
+async def cronometro(nombre: str):
+    """Context manager async para medir tiempos."""
+    inicio = asyncio.get_event_loop().time()
+    try:
+        yield
+    finally:
+        elapsed = asyncio.get_event_loop().time() - inicio
+        print(f"[{nombre}] tardó {elapsed:.3f}s")
+
+# Uso
+async def proceso_pesado():
+    async with cronometro("importación de nómina"):
+        await importar_nomina()
+
+# Inicialización y cierre de recursos (FastAPI lifespan)
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    await engine.connect()
+    await redis_client.ping()
+    yield
+    # Shutdown
+    await engine.dispose()
+    await redis_client.close()
+```
+
+---
+
+## Queues Async — Productor/Consumidor
+
+```python
+import asyncio
+from dataclasses import dataclass
+from typing import Callable, Awaitable
+
+@dataclass
+class Tarea:
+    id: int
+    payload: dict
+
+async def productor(queue: asyncio.Queue, tareas: list[Tarea]) -> None:
+    for tarea in tareas:
+        await queue.put(tarea)
+    await queue.put(None)
+
+async def consumidor(
+    queue: asyncio.Queue,
+    procesar: Callable[[Tarea], Awaitable[None]],
+    worker_id: int,
+) -> None:
+    while True:
+        tarea = await queue.get()
+        if tarea is None:
+            queue.task_done()
+            break
+        try:
+            await procesar(tarea)
+        except Exception as e:
+            print(f"[Worker {worker_id}] Error en tarea {tarea.id}: {e}")
+        finally:
+            queue.task_done()
+
+async def pipeline_tareas(
+    tareas: list[Tarea],
+    procesar: Callable[[Tarea], Awaitable[None]],
+    num_workers: int = 5,
+    max_queue: int = 100,
+) -> None:
+    queue: asyncio.Queue = asyncio.Queue(maxsize=max_queue)
+
+    async with asyncio.TaskGroup() as tg:
+        tg.create_task(productor(queue, tareas))
+        for i in range(num_workers):
+            tg.create_task(consumidor(queue, procesar, worker_id=i))
+```
+
+---
+
+## Error Handling — Reintento con backoff exponencial
+
+```python
+import asyncio
+import logging
+from typing import TypeVar, Callable, Awaitable
+
+logger = logging.getLogger(__name__)
+T = TypeVar("T")
+
+async def reintentar(
+    func: Callable[[], Awaitable[T]],
+    max_intentos: int = 3,
+    delay_base: float = 1.0,
+    errores_reintentables: tuple[type[Exception], ...] = (Exception,),
+) -> T:
+    ultimo_error: Exception | None = None
+    for intento in range(1, max_intentos + 1):
+        try:
+            return await func()
+        except errores_reintentables as e:
+            ultimo_error = e
+            if intento < max_intentos:
+                delay = delay_base * (2 ** (intento - 1))
+                logger.warning(
+                    "Intento %d/%d falló (%s). Reintentando en %.1fs",
+                    intento, max_intentos, e, delay,
+                )
+                await asyncio.sleep(delay)
+    raise ultimo_error  # type: ignore[misc]
+
+# Uso
+async def obtener_datos_con_reintento(id_: str) -> dict:
+    return await reintentar(
+        lambda: fetch_json(f"/api/datos/{id_}"),
+        max_intentos=3,
+        errores_reintentables=(aiohttp.ClientError, asyncio.TimeoutError),
+    )
+```
+
+---
+
+## Testing de Código Async
+
+```python
+import pytest
+import asyncio
+from unittest.mock import AsyncMock, patch
+
+# pytest-asyncio — configuración en pyproject.toml
+# [tool.pytest.ini_options]
+# asyncio_mode = "auto"
+
+@pytest.fixture
+async def db_session():
+    """Fixture async con rollback automático."""
+    async with TestingSessionLocal() as session:
+        async with session.begin():
+            yield session
+            await session.rollback()  # Siempre limpiar
+
+@pytest.mark.asyncio
+async def test_obtener_usuario_con_roles(db_session):
+    # Arrange
+    usuario = await crear_usuario_fixture(db_session, roles=["ADMIN"])
+
+    # Act
+    resultado = await obtener_usuario_con_roles(db_session, usuario.id)
+
+    # Assert
+    assert resultado.id == usuario.id
+    assert len(resultado.roles) == 1
+    assert resultado.roles[0].nombre == "ADMIN"
+
+# Mock de llamadas HTTP
+@pytest.mark.asyncio
+async def test_fetch_url_reintenta_en_error():
+    llamadas = 0
+
+    async def mock_get(*args, **kwargs):
+        nonlocal llamadas
+        llamadas += 1
+        if llamadas < 3:
+            raise aiohttp.ClientError("Fallo temporal")
+        return MockResponse(status=200, data={"ok": True})
+
+    with patch("aiohttp.ClientSession.get", side_effect=mock_get):
+        resultado = await obtener_datos_con_reintento("123")
+
+    assert resultado == {"ok": True}
+    assert llamadas == 3
+```
+
+---
+
+## Receta: Service HTTP con Pool de Conexiones
+
+```python
+import asyncio
+import aiohttp
+from typing import Any
+
+class ClienteHTTP:
+    """Cliente HTTP reutilizable con pool de conexiones."""
+
+    def __init__(self, base_url: str, max_conexiones: int = 20):
+        self._base_url = base_url.rstrip("/")
+        self._connector = aiohttp.TCPConnector(limit=max_conexiones)
+        self._session: aiohttp.ClientSession | None = None
+
+    async def __aenter__(self) -> "ClienteHTTP":
+        self._session = aiohttp.ClientSession(
+            connector=self._connector,
+            timeout=aiohttp.ClientTimeout(total=30),
+            headers={"Content-Type": "application/json"},
+        )
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        if self._session:
+            await self._session.close()
+        await self._connector.close()
+
+    async def get(self, path: str, **kwargs: Any) -> dict:
+        assert self._session, "Usar dentro de 'async with ClienteHTTP()'"
+        url = f"{self._base_url}/{path.lstrip('/')}"
+        async with self._session.get(url, **kwargs) as resp:
+            resp.raise_for_status()
+            return await resp.json()
+
+# Uso en FastAPI startup
+cliente_sap: ClienteHTTP | None = None
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    global cliente_sap
+    async with ClienteHTTP("https://sap.empresa.com.mx/api") as client:
+        cliente_sap = client
+        yield
+```

package/habilidades/auth-patrones/.evolved.json

@@ -0,0 +1,9 @@
+{
+  "SKILL.md": {
+    "evolved": true,
+    "evolvedFrom": "5.11.1",
+    "evolvedAt": "2026-04-23",
+    "evolvedBy": "aprender",
+    "evolvedNote": "sección nueva: Multitenancy con get_readable_statement (patrón de polar)"
+  }
+}