Python Patterns

Python Patterns Skill

Cuándo usar esta skill

• Al escribir nuevo código Python.
• Al revisar código existente.
• Cuando necesites decidir patrones de diseño.
• Al estructurar módulos y clases.

Patrones Core del Proyecto

1. Estructura de Módulos

"""
Descripción breve del módulo.

Descripción más detallada si es necesario.
"""

# 1. Imports de stdlib primero
from datetime import datetime
from pathlib import Path
from typing import Optional, Tuple, Dict, List

# 2. Imports de terceros
from fastmcp import FastMCP
from pydantic import BaseModel

# 3. Imports locales (relativos)
from ..config import get_vault_path
from ..utils import get_logger

# 4. Logger al inicio
logger = get_logger(__name__)


# 5. Funciones helper (privadas) primero
def _helper_function(data: str) -> str:
    """Helper interno del módulo."""
    return data.strip()


# 6. Funciones/clases públicas después
def public_function(param: str) -> str:
    """
    Función pública del módulo.

    Args:
        param: Descripción del parámetro.

    Returns:
        Descripción del retorno.
    """
    return _helper_function(param)

2. Type Hints (Obligatorio)

# ✅ CORRECTO: Todo tipado
def process_note(
    path: Path,
    options: Optional[Dict[str, Any]] = None,
) -> Tuple[bool, str]:
    ...

# ❌ INCORRECTO: Sin tipos
def process_note(path, options=None):
    ...

Tipos comunes en el proyecto:

from pathlib import Path
from typing import Optional, Tuple, Dict, List, Any, Literal

# Para retornos con error
def operation() -> Tuple[bool, str]:
    """Retorna (success, message)."""
    if error:
        return False, "Error message"
    return True, "Success"

# Para configuración opcional
TransportType = Literal["stdio", "http", "sse"]

3. Patrón de Resultado (Success/Error)

# Patrón estándar del proyecto para operaciones
def operation(param: str) -> str:
    """
    Realiza operación.

    Returns:
        Mensaje con emoji indicando resultado.
    """
    try:
        # Validación temprana
        if not param:
            return "❌ Error: Parámetro requerido"

        vault_path = get_vault_path()
        if not vault_path:
            return "❌ Error: La ruta del vault no está configurada."

        # Lógica principal
        result = do_something(param)

        # Éxito
        return f"✅ Operación completada: {result}"

    except SpecificError as e:
        return f"❌ Error específico: {e}"
    except Exception as e:
        return f"❌ Error inesperado: {e}"