theus-cli 0.2.83 → 0.2.84

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

@@ -1,750 +0,0 @@
----
-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.