Herramientas de depuración

Python incluye breakpoint() y pdb, se integra con REPLs más completos como ipdb, admite depuradores de conexión remota y se basa en el registro estructurado para producción. Elija la herramienta adecuada para la reproducción local frente a la observación de sistemas en vivo.

Referencia de herramientas de depuración

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

def charge(amount: int) -> int:
    breakpoint()  # Python 3.14: respeta PYTHONBREAKPOINT
    if amount < 0:
        raise ValueError("negativo")
    return amount * 100
 
# post-mortem en pytest: pytest --pdb
# registro:
import logging
log = logging.getLogger(__name__)
log.exception("falló el cargo", extra={"amount": amount})

Cuándo usar esto:

• Reproducir un error lógico con variables locales intactas
• Inspeccionar la pila después de una excepción en CI
• Conectarse a un pod de staging sin editar código
• Correlacionar informes de usuarios con registros de solicitudes en producción

Ejemplo de trabajo

import logging
import sys
from contextlib import contextmanager
 
# --- configuración de registro estructurado ---
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(name)s %(message)s",
)
log = logging.getLogger("billing")
 
@contextmanager
def request_context(request_id: str):
    old = logging.LoggerAdapter(log, {"request_id": request_id})
    try:
        yield old
    finally:
        pass
 
# --- comandos de sesión de pdb (referencia comentada para lectores) ---
# p variable     -> imprimir
# n              -> siguiente línea
# s              -> entrar en paso
# w              -> dónde está la pila
# l              -> listar código fuente
# c              -> continuar
 
def apply_discount(total_cents: int, pct: int) -> int:
    if pct < 0 or pct > 100:
        log.error("pct inválido", extra={"pct": pct})
        raise ValueError("pct fuera de rango")
    discounted = total_cents * (100 - pct) // 100
    log.info("descontado", extra={"before": total_cents, "after": discounted})
    return discounted
 
def debug_example() -> None:
    # punto de interrupción condicional solo en desarrollo
    if sys.flags.debug_mode:  # o os.getenv("DEBUG_PDB") == "1"
        breakpoint()
    print(apply_discount(10_00, 10))
 
# --- utilidad post-mortem ---
def run_with_pm(fn):
    try:
        return fn()
    except Exception:
        import pdb
        pdb.post_mortem()
        raise
 
# --- faulthandler para bloqueos ---
import faulthandler
faulthandler.enable()

# pytest con pdb en caso de fallo
uv run pytest tests/test_billing.py --pdb -x
 
# depuración remota (debugpy) - iniciar listener al inicio de la aplicación cuando DEBUG_ATTACH=1
# VS Code se conecta al puerto 5678

Lo que esto demuestra:

• logging registra valores de negocio sin detener los hilos de servicio
• breakpoint() se detiene localmente; proteger con una bandera de entorno en rutas de código compartidas
• pytest --pdb entra en modo post-mortem en fallos de aserción
• faulthandler ayuda cuando los procesos se bloquean sin lanzar excepciones

Inmersión profunda

Cómo funciona

• breakpoint() consulta PYTHONBREAKPOINT (por defecto pdb.set_trace)
• Los depuradores se ejecutan en el mismo proceso; los puntos de interrupción bloquean ese hilo o proceso
• debugpy escucha en un puerto; el IDE inyecta puntos de interrupción sin volver a desplegar
• El registro debe ser estructurado en producción; pdb es para la reproducción en desarrollo/staging

Lista corta de comandos de pdb

Notas de Python

# deshabilitar puntos de interrupción en el punto de entrada de producción
import os
if os.getenv("ENVIRONMENT") == "production":
    os.environ["PYTHONBREAKPOINT"] = "0"

Trampas comunes

• Dejar breakpoint() en el código principal - detiene los trabajadores de producción. Solución: protección por variable de entorno; ruff puede marcar sentencias de depuración.
• Imprimir secretos en pdb - el historial de la sesión registra datos sensibles. Solución: redactar; usar registro con filtros.
• Depuración remota abierta en 0.0.0.0 en producción - riesgo de RCE. Solución: solo en staging, túnel SSH, autenticación.
• Depuración con print en bucles intensivos - I/O más lento que el error. Solución: registro muestreado en INFO/WARN.
• pytest --pdb en ejecución paralela con xdist - los trabajadores se conectan de forma confusa. Solución: -n0 al depurar.
• Optimización de variables bajo -O - assert y algunas rutas de depuración se eliminan. Solución: no confiar en assert para validación en producción.

Alternativas

Preguntas frecuentes

Relacionados

• Errores de argumentos predeterminados mutables - inspeccionar con pdb
• Interbloqueos de asyncio y bloqueo del bucle - modo de depuración de asyncio
• Escenarios de fugas de memoria - compañero de tracemalloc
• Conflictos de dependencias y entorno - verificar intérprete en pdb
• Fragmentos de refactorización de depuración - correcciones después de encontrar la causa raíz

Versiones de la pila: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.