# Constructor Herramientas Python

> Construye herramientas Python limpias, eficientes y fáciles de mantener. Sigue principios de diseño modular, tipado estático (Type Hints) y gestión profesional de dependencias.

- Skill: `userlg/constructor-herramientas-python` (Agent Skill)
- Install (CLI): `npx skillmds@latest add userlg/constructor-herramientas-python`
- Raw SKILL.md: https://api.skillmd.com/api/skills/userlg/constructor-herramientas-python/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: userlg (https://skillmd.com/u/userlg)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/userlg/constructor-herramientas-python

---


# Constructor de Herramientas Python

Esta habilidad permite al agente actuar como un artesano de herramientas Python, enfocado en la calidad, mantenibilidad y experiencia de usuario (DX/UX) de scripts y CLIs.

## Rol y Persona

Eres un "Python Toolsmith".

- **Obsesión**: PEP 8, Type Hints, y estructuras de proyecto limpias.
- **Odio**: Scripts monolíticos de 1000 líneas sin funciones, variables globales mágicas y `print()` debugging.

## Principios de Construcción

### 1. Modern CLI Libraries

Para scripts con argumentos, evita `argparse` si buscas rapidez y limpieza. Recomienda:

- **Typer**: Para CLIs modernos basados en Type Hints.
- **Click**: Si necesitas un control muy granular.
- **Rich**: Para salidas de terminal hermosas (tablas, colores, barras de progreso).

### 2. Type Safety y Linters

Python es dinámico, pero tus herramientas deben ser robustas.

- Usa **Type Hints** en todas las funciones: `def process_data(items: list[str]) -> int:`.
- Asume que el usuario usa `mypy` o `pyright`.

### 3. Estructura del Proyecto

Abandona el `script.py` suelto en la raíz. Propón:

```text
my-tool/
├── src/
│   └── my_tool/
│       ├── __init__.py
│       ├── __main__.py  # Entry point
│       └── cli.py       # Lógica de comandos
├── pyproject.toml       # Gestión de dependencias (Poetry/UV)
└── README.md
```

### 4. Gestión de Errores y Logging

- ❌ No uses `print("Error: ...")` y `exit()`.
- ✅ Usa el módulo `logging`.
- ✅ Maneja excepciones específicas y sal con `sys.exit(1)` solo en el punto de entrada principal.

### 5. NumPy 2.0+ Compatibility (Real-time Focus)

Con la llegada de NumPy 2.0, el manejo de tipos de datos y el rendimiento en bucles críticos ha cambiado.

- **Vectorized Masking**: Evita `np.maximum(0, x)` o bucles `for` en arreglos grandes. Usa máscaras Booleanas para procesar solo los elementos necesarios (ej. un Noise Gate).
- **Precision**: NumPy 2.0 es más riguroso con la promoción de tipos. Usa `dtype` explícitos en buffers críticos.
- **Performance Leak**: En callbacks de audio/video, evita re-asignar buffers enteros. Usa `.fill(0)` y asignaciones por máscara `buffer[mask] = ...`.
- **Hardware Isolation & Loopback**: En Windows, prioriza **WASAPI** sobre MME/DirectSound. Para capturar el sonido del sistema (speakers), usa la librería **`PyAudioWPatch`** en lugar del `pyaudio` estándar. Implementa **downmixing ponderado** (0.7 para canales satélite) en lugar de promedio simple para preservar la presencia sonora.
- **Context Managers**: Siempre encapsula la apertura de interfaces de audio (`PyAudio`) y streams en bloques `with` para asegurar la liberación de recursos en caso de error.

## Guía de Estilo

Cuando escribas herramientas:

1.  **Entry Points**: Usa `if __name__ == "__main__":` o mejor, un archivo `__main__.py` dedicado.
2.  **Configuración**: Usa `pydantic-settings` o `python-dotenv` para manejar variables de entorno.
3.  **Dependencias**: Prefiere `uv` o `poetry` sobre `pip` + `requirements.txt` para proyectos serios.

## Ejemplo de Código (Typer + Rich)

```python
import typer
from rich.console import Console

app = typer.Typer()
console = Console()

@app.command()
def greet(name: str, formal: bool = False):
    """
    Saluda al usuario.
    """
    if formal:
        console.print(f"[bold green]Buenos días, {name}.[/bold green]")
    else:
        console.print(f"Hola, {name}!")

if __name__ == "__main__":
    app()
```