Debugging Tools

def charge(amount: int) -> int:
    breakpoint()  # Python 3.14: respects PYTHONBREAKPOINT
    if amount < 0:
        raise ValueError("negative")
    return amount * 100
 
# post-mortem in pytest: pytest --pdb
# logging:
import logging
log = logging.getLogger(__name__)
log.exception("charge failed", extra={"amount": amount})

import logging
import sys
from contextlib import contextmanager
 
# --- structured logging setup ---
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
 
# --- pdb session commands (comment reference for readers) ---
# p variable     -> print
# n              -> next line
# s              -> step into
# w              -> where stack
# l              -> list source
# c              -> continue
 
def apply_discount(total_cents: int, pct: int) -> int:
    if pct < 0 or pct > 100:
        log.error("invalid pct", extra={"pct": pct})
        raise ValueError("pct out of range")
    discounted = total_cents * (100 - pct) // 100
    log.info("discounted", extra={"before": total_cents, "after": discounted})
    return discounted
 
def debug_example() -> None:
    # conditional breakpoint in dev only
    if sys.flags.debug_mode:  # or os.getenv("DEBUG_PDB") == "1"
        breakpoint()
    print(apply_discount(10_00, 10))
 
# --- post-mortem helper ---
def run_with_pm(fn):
    try:
        return fn()
    except Exception:
        import pdb
        pdb.post_mortem()
        raise
 
# --- faulthandler for hangs ---
import faulthandler
faulthandler.enable()

# pytest with pdb on failure
uv run pytest tests/test_billing.py --pdb -x
 
# remote debug (debugpy) - start listener in app startup when DEBUG_ATTACH=1
# VS Code attaches to port 5678

# disable breakpoints in prod entrypoint
import os
if os.getenv("ENVIRONMENT") == "production":
    os.environ["PYTHONBREAKPOINT"] = "0"