theus-cli-darwin-x64 0.2.84

package/vendor/theus-arsenal/skills/patrones-python/SKILL.md

@@ -0,0 +1,750 @@
+---
+name: patrones-python
+description: Idiomas pythónicos, estándares PEP 8, type hints y mejores prácticas para construir aplicaciones Python robustas, eficientes y mantenibles.
+version: "1.0.0"
+---
+
+# Patrones de desarrollo en Python
+
+Patrones idiomáticos de Python y mejores prácticas para construir aplicaciones robustas, eficientes y mantenibles.
+
+## Cuándo activar
+
+- Al escribir código Python nuevo
+- Al revisar código Python
+- Al refactorizar código Python existente
+- Al diseñar paquetes/módulos de Python
+
+## Principios centrales
+
+### 1. La legibilidad cuenta
+
+Python prioriza la legibilidad. El código debe ser obvio y fácil de entender.
+
+```python
+# Bien: claro y legible
+def get_active_users(users: list[User]) -> list[User]:
+    """Devuelve solo los usuarios activos de la lista proporcionada."""
+    return [user for user in users if user.is_active]
+
+
+# Mal: ingenioso pero confuso
+def get_active_users(u):
+    return [x for x in u if x.a]
+```
+
+### 2. Explícito es mejor que implícito
+
+Evita la magia; sé claro sobre lo que hace tu código.
+
+```python
+# Bien: configuración explícita
+import logging
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+
+# Mal: efectos secundarios ocultos
+import some_module
+some_module.setup()  # ¿Qué hace esto?
+```
+
+### 3. EAFP — es más fácil pedir perdón que permiso
+
+Python prefiere el manejo de excepciones sobre la comprobación de condiciones.
+
+```python
+# Bien: estilo EAFP
+def get_value(dictionary: dict, key: str, default_value: Any = None) -> Any:
+    try:
+        return dictionary[key]
+    except KeyError:
+        return default_value
+
+# Mal: estilo LBYL (Look Before You Leap)
+def get_value(dictionary: dict, key: str, default_value: Any = None) -> Any:
+    if key in dictionary:
+        return dictionary[key]
+    else:
+        return default_value
+```
+
+## Type hints
+
+### Anotaciones de tipo básicas
+
+```python
+from typing import Optional, List, Dict, Any
+
+def process_user(
+    user_id: str,
+    data: Dict[str, Any],
+    active: bool = True
+) -> Optional[User]:
+    """Procesa un usuario y devuelve el User actualizado o None."""
+    if not active:
+        return None
+    return User(user_id, data)
+```
+
+### Type hints modernos (Python 3.9+)
+
+```python
+# Python 3.9+ — usa los tipos integrados
+def process_items(items: list[str]) -> dict[str, int]:
+    return {item: len(item) for item in items}
+
+# Python 3.8 y anteriores — usa el módulo typing
+from typing import List, Dict
+
+def process_items(items: List[str]) -> Dict[str, int]:
+    return {item: len(item) for item in items}
+```
+
+### Alias de tipos y TypeVar
+
+```python
+from typing import TypeVar, Union
+
+# Alias de tipo para tipos complejos
+JSON = Union[dict[str, Any], list[Any], str, int, float, bool, None]
+
+def parse_json(data: str) -> JSON:
+    return json.loads(data)
+
+# Tipos genéricos
+T = TypeVar('T')
+
+def first(items: list[T]) -> T | None:
+    """Devuelve el primer elemento o None si la lista está vacía."""
+    return items[0] if items else None
+```
+
+### Duck typing basado en Protocol
+
+```python
+from typing import Protocol
+
+class Renderable(Protocol):
+    def render(self) -> str:
+        """Renderiza el objeto a un string."""
+
+def render_all(items: list[Renderable]) -> str:
+    """Renderiza todos los elementos que implementan el protocolo Renderable."""
+    return "\n".join(item.render() for item in items)
+```
+
+## Patrones de manejo de errores
+
+### Manejo de excepciones específicas
+
+```python
+# Bien: captura excepciones específicas
+def load_config(path: str) -> Config:
+    try:
+        with open(path) as f:
+            return Config.from_json(f.read())
+    except FileNotFoundError as e:
+        raise ConfigError(f"Archivo de configuración no encontrado: {path}") from e
+    except json.JSONDecodeError as e:
+        raise ConfigError(f"JSON inválido en la configuración: {path}") from e
+
+# Mal: except desnudo
+def load_config(path: str) -> Config:
+    try:
+        with open(path) as f:
+            return Config.from_json(f.read())
+    except:
+        return None  # ¡Fallo silencioso!
+```
+
+### Encadenamiento de excepciones
+
+```python
+def process_data(data: str) -> Result:
+    try:
+        parsed = json.loads(data)
+    except json.JSONDecodeError as e:
+        # Encadena las excepciones para preservar el traceback
+        raise ValueError(f"No se pudieron parsear los datos: {data}") from e
+```
+
+### Jerarquía de excepciones personalizadas
+
+```python
+class AppError(Exception):
+    """Excepción base para todos los errores de la aplicación."""
+    pass
+
+class ValidationError(AppError):
+    """Se lanza cuando falla la validación de la entrada."""
+    pass
+
+class NotFoundError(AppError):
+    """Se lanza cuando no se encuentra un recurso solicitado."""
+    pass
+
+# Uso
+def get_user(user_id: str) -> User:
+    user = db.find_user(user_id)
+    if not user:
+        raise NotFoundError(f"Usuario no encontrado: {user_id}")
+    return user
+```
+
+## Context managers
+
+### Gestión de recursos
+
+```python
+# Bien: usando context managers
+def process_file(path: str) -> str:
+    with open(path, 'r') as f:
+        return f.read()
+
+# Mal: gestión manual de recursos
+def process_file(path: str) -> str:
+    f = open(path, 'r')
+    try:
+        return f.read()
+    finally:
+        f.close()
+```
+
+### Context managers personalizados
+
+```python
+from contextlib import contextmanager
+
+@contextmanager
+def timer(name: str):
+    """Context manager para cronometrar un bloque de código."""
+    start = time.perf_counter()
+    yield
+    elapsed = time.perf_counter() - start
+    print(f"{name} tardó {elapsed:.4f} segundos")
+
+# Uso
+with timer("procesamiento de datos"):
+    process_large_dataset()
+```
+
+### Clases como context managers
+
+```python
+class DatabaseTransaction:
+    def __init__(self, connection):
+        self.connection = connection
+
+    def __enter__(self):
+        self.connection.begin_transaction()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if exc_type is None:
+            self.connection.commit()
+        else:
+            self.connection.rollback()
+        return False  # No suprimir excepciones
+
+# Uso
+with DatabaseTransaction(conn):
+    user = conn.create_user(user_data)
+    conn.create_profile(user.id, profile_data)
+```
+
+## Comprehensions y generadores
+
+### List comprehensions
+
+```python
+# Bien: list comprehension para transformaciones simples
+names = [user.name for user in users if user.is_active]
+
+# Mal: bucle manual
+names = []
+for user in users:
+    if user.is_active:
+        names.append(user.name)
+
+# Las comprehensions complejas deben expandirse
+# Mal: demasiado complejo
+result = [x * 2 for x in items if x > 0 if x % 2 == 0]
+
+# Bien: usa una función generadora
+def filter_and_transform(items: Iterable[int]) -> list[int]:
+    result = []
+    for x in items:
+        if x > 0 and x % 2 == 0:
+            result.append(x * 2)
+    return result
+```
+
+### Expresiones generadoras
+
+```python
+# Bien: generador para evaluación perezosa
+total = sum(x * x for x in range(1_000_000))
+
+# Mal: crea una lista intermedia grande
+total = sum([x * x for x in range(1_000_000)])
+```
+
+### Funciones generadoras
+
+```python
+def read_large_file(path: str) -> Iterator[str]:
+    """Lee un archivo grande línea por línea."""
+    with open(path) as f:
+        for line in f:
+            yield line.strip()
+
+# Uso
+for line in read_large_file("huge.txt"):
+    process(line)
+```
+
+## Data classes y named tuples
+
+### Data classes
+
+```python
+from dataclasses import dataclass, field
+from datetime import datetime
+
+@dataclass
+class User:
+    """Entidad User con __init__, __repr__ y __eq__ automáticos."""
+    id: str
+    name: str
+    email: str
+    created_at: datetime = field(default_factory=datetime.now)
+    is_active: bool = True
+
+# Uso
+user = User(
+    id="123",
+    name="Alice",
+    email="alice@example.com"
+)
+```
+
+### Data classes con validación
+
+```python
+@dataclass
+class User:
+    email: str
+    age: int
+
+    def __post_init__(self):
+        # Valida el formato del email
+        if "@" not in self.email:
+            raise ValueError(f"Email inválido: {self.email}")
+        # Valida el rango de edad
+        if self.age < 0 or self.age > 150:
+            raise ValueError(f"Edad inválida: {self.age}")
+```
+
+### Named tuples
+
+```python
+from typing import NamedTuple
+
+class Point(NamedTuple):
+    """Punto 2D inmutable."""
+    x: float
+    y: float
+
+    def distance(self, other: 'Point') -> float:
+        return ((self.x - other.x) ** 2 + (self.y - other.y) ** 2) ** 0.5
+
+# Uso
+p1 = Point(0, 0)
+p2 = Point(3, 4)
+print(p1.distance(p2))  # 5.0
+```
+
+## Decoradores
+
+### Decoradores de función
+
+```python
+import functools
+import time
+
+def timer(func: Callable) -> Callable:
+    """Decorador para cronometrar la ejecución de una función."""
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        start = time.perf_counter()
+        result = func(*args, **kwargs)
+        elapsed = time.perf_counter() - start
+        print(f"{func.__name__} tardó {elapsed:.4f}s")
+        return result
+    return wrapper
+
+@timer
+def slow_function():
+    time.sleep(1)
+
+# slow_function() imprime: slow_function tardó 1.0012s
+```
+
+### Decoradores parametrizados
+
+```python
+def repeat(times: int):
+    """Decorador para repetir una función varias veces."""
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            results = []
+            for _ in range(times):
+                results.append(func(*args, **kwargs))
+            return results
+        return wrapper
+    return decorator
+
+@repeat(times=3)
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+# greet("Alice") devuelve ["Hello, Alice!", "Hello, Alice!", "Hello, Alice!"]
+```
+
+### Decoradores basados en clases
+
+```python
+class CountCalls:
+    """Decorador que cuenta cuántas veces se llama a una función."""
+    def __init__(self, func: Callable):
+        functools.update_wrapper(self, func)
+        self.func = func
+        self.count = 0
+
+    def __call__(self, *args, **kwargs):
+        self.count += 1
+        print(f"{self.func.__name__} ha sido llamada {self.count} veces")
+        return self.func(*args, **kwargs)
+
+@CountCalls
+def process():
+    pass
+
+# Cada llamada a process() imprime el conteo de llamadas
+```
+
+## Patrones de concurrencia
+
+### Threading para tareas limitadas por I/O
+
+```python
+import concurrent.futures
+import threading
+
+def fetch_url(url: str) -> str:
+    """Descarga una URL (operación limitada por I/O)."""
+    import urllib.request
+    with urllib.request.urlopen(url) as response:
+        return response.read().decode()
+
+def fetch_all_urls(urls: list[str]) -> dict[str, str]:
+    """Descarga varias URLs concurrentemente usando threads."""
+    with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
+        future_to_url = {executor.submit(fetch_url, url): url for url in urls}
+        results = {}
+        for future in concurrent.futures.as_completed(future_to_url):
+            url = future_to_url[future]
+            try:
+                results[url] = future.result()
+            except Exception as e:
+                results[url] = f"Error: {e}"
+    return results
+```
+
+### Multiprocessing para tareas limitadas por CPU
+
+```python
+def process_data(data: list[int]) -> int:
+    """Cómputo intensivo en CPU."""
+    return sum(x ** 2 for x in data)
+
+def process_all(datasets: list[list[int]]) -> list[int]:
+    """Procesa varios datasets usando múltiples procesos."""
+    with concurrent.futures.ProcessPoolExecutor() as executor:
+        results = list(executor.map(process_data, datasets))
+    return results
+```
+
+### Async/await para I/O concurrente
+
+```python
+import asyncio
+
+async def fetch_async(url: str) -> str:
+    """Descarga una URL de forma asíncrona."""
+    import aiohttp
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url) as response:
+            return await response.text()
+
+async def fetch_all(urls: list[str]) -> dict[str, str]:
+    """Descarga varias URLs concurrentemente."""
+    tasks = [fetch_async(url) for url in urls]
+    results = await asyncio.gather(*tasks, return_exceptions=True)
+    return dict(zip(urls, results))
+```
+
+## Organización de paquetes
+
+### Estructura estándar de proyecto
+
+```
+myproject/
+├── src/
+│   └── mypackage/
+│       ├── __init__.py
+│       ├── main.py
+│       ├── api/
+│       │   ├── __init__.py
+│       │   └── routes.py
+│       ├── models/
+│       │   ├── __init__.py
+│       │   └── user.py
+│       └── utils/
+│           ├── __init__.py
+│           └── helpers.py
+├── tests/
+│   ├── __init__.py
+│   ├── conftest.py
+│   ├── test_api.py
+│   └── test_models.py
+├── pyproject.toml
+├── README.md
+└── .gitignore
+```
+
+### Convenciones de imports
+
+```python
+# Bien: orden de imports — stdlib, terceros, local
+import os
+import sys
+from pathlib import Path
+
+import requests
+from fastapi import FastAPI
+
+from mypackage.models import User
+from mypackage.utils import format_name
+
+# Bien: usa isort para ordenar imports automáticamente
+# pip install isort
+```
+
+### __init__.py para exportaciones del paquete
+
+```python
+# mypackage/__init__.py
+"""mypackage — Un paquete Python de ejemplo."""
+
+__version__ = "1.0.0"
+
+# Exporta las clases/funciones principales a nivel de paquete
+from mypackage.models import User, Post
+from mypackage.utils import format_name
+
+__all__ = ["User", "Post", "format_name"]
+```
+
+## Memoria y rendimiento
+
+### Uso de __slots__ para eficiencia de memoria
+
+```python
+# Mal: una clase normal usa __dict__ (más memoria)
+class Point:
+    def __init__(self, x: float, y: float):
+        self.x = x
+        self.y = y
+
+# Bien: __slots__ reduce el uso de memoria
+class Point:
+    __slots__ = ['x', 'y']
+
+    def __init__(self, x: float, y: float):
+        self.x = x
+        self.y = y
+```
+
+### Generadores para datos grandes
+
+```python
+# Mal: devuelve la lista completa en memoria
+def read_lines(path: str) -> list[str]:
+    with open(path) as f:
+        return [line.strip() for line in f]
+
+# Bien: produce las líneas de una en una
+def read_lines(path: str) -> Iterator[str]:
+    with open(path) as f:
+        for line in f:
+            yield line.strip()
+```
+
+### Evita la concatenación de strings en bucles
+
+```python
+# Mal: O(n²) por la inmutabilidad de los strings
+result = ""
+for item in items:
+    result += str(item)
+
+# Bien: O(n) usando join
+result = "".join(str(item) for item in items)
+
+# Bien: usando StringIO para construir
+from io import StringIO
+
+buffer = StringIO()
+for item in items:
+    buffer.write(str(item))
+result = buffer.getvalue()
+```
+
+## Integración con el tooling de Python
+
+### Comandos esenciales
+
+```bash
+# Formateo de código
+black .
+isort .
+
+# Linting
+ruff check .
+pylint mypackage/
+
+# Verificación de tipos
+mypy .
+
+# Testing
+pytest --cov=mypackage --cov-report=html
+
+# Escaneo de seguridad
+bandit -r .
+
+# Gestión de dependencias
+pip-audit
+safety check
+```
+
+### Configuración de pyproject.toml
+
+```toml
+[project]
+name = "mypackage"
+version = "1.0.0"
+requires-python = ">=3.9"
+dependencies = [
+    "requests>=2.31.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+    "black>=23.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.5.0",
+]
+
+[tool.black]
+line-length = 88
+target-version = ['py39']
+
+[tool.ruff]
+line-length = 88
+select = ["E", "F", "I", "N", "W"]
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=mypackage --cov-report=term-missing"
+```
+
+## Referencia rápida: idiomas de Python
+
+| Idioma | Descripción |
+|-------|-------------|
+| EAFP | Es más fácil pedir perdón que permiso |
+| Context managers | Usa `with` para la gestión de recursos |
+| List comprehensions | Para transformaciones simples |
+| Generadores | Para evaluación perezosa y datasets grandes |
+| Type hints | Anota las firmas de las funciones |
+| Dataclasses | Para contenedores de datos con métodos autogenerados |
+| `__slots__` | Para optimización de memoria |
+| f-strings | Para formateo de strings (Python 3.6+) |
+| `pathlib.Path` | Para operaciones con rutas (Python 3.4+) |
+| `enumerate` | Para pares índice-elemento en bucles |
+
+## Anti-patrones a evitar
+
+```python
+# Mal: argumentos por defecto mutables
+def append_to(item, items=[]):
+    items.append(item)
+    return items
+
+# Bien: usa None y crea una lista nueva
+def append_to(item, items=None):
+    if items is None:
+        items = []
+    items.append(item)
+    return items
+
+# Mal: comprobar el tipo con type()
+if type(obj) == list:
+    process(obj)
+
+# Bien: usa isinstance
+if isinstance(obj, list):
+    process(obj)
+
+# Mal: comparar con None usando ==
+if value == None:
+    process()
+
+# Bien: usa is
+if value is None:
+    process()
+
+# Mal: from module import *
+from os.path import *
+
+# Bien: imports explícitos
+from os.path import join, exists
+
+# Mal: except desnudo
+try:
+    risky_operation()
+except:
+    pass
+
+# Bien: excepción específica
+try:
+    risky_operation()
+except SpecificError as e:
+    logger.error(f"La operación falló: {e}")
+```
+
+__Recuerda__: el código Python debe ser legible, explícito y seguir el principio de la mínima sorpresa. Ante la duda, prioriza la claridad sobre la astucia.