S011 · Errors, Exceptions & Debugging with pdb

"""s011_errors.py — exceptions, debugging, and the modern toolkit."""
from __future__ import annotations
from contextlib import contextmanager
from typing import Iterable
import json
import logging
import traceback
 
logging.basicConfig(
    level=logging.INFO,
    format="%(levelname)s [%(name)s] %(message)s",
)
log = logging.getLogger("s011")
 
# =========================
# Part 1 · try / except / else / finally
# =========================
print("--- Part 1 · try/except/else/finally ---")
 
def parse_int_safe(s: str) -> int | None:
    try:
        n = int(s)
    except ValueError:
        log.warning("not an int: %r", s)
        return None
    else:
        log.info("parsed cleanly: %r → %d", s, n)
        return n
    finally:
        log.debug("attempted parse of %r", s)
 
print(parse_int_safe("42"))
print(parse_int_safe("nope"))
 
# =========================
# Part 2 · Custom exceptions with context
# =========================
print("\n--- Part 2 · custom exceptions ---")
 
class DomainError(Exception):
    """Base for all domain errors in this app."""
 
class OrderError(DomainError):
    def __init__(self, order_id: str, reason: str) -> None:
        super().__init__(f"order {order_id!r}: {reason}")
        self.order_id = order_id
        self.reason = reason
 
class OrderNotFound(OrderError):
    def __init__(self, order_id: str) -> None:
        super().__init__(order_id, "not found")
 
try:
    raise OrderNotFound("O-1234")
except OrderError as e:
    log.error("caught %s (id=%s reason=%s)", type(e).__name__, e.order_id, e.reason)
 
# Callers can catch broadly (DomainError) or narrowly (OrderNotFound) as needed.
 
# =========================
# Part 3 · Exception chaining — `raise ... from ...`
# =========================
print("\n--- Part 3 · chaining ---")
 
def load_order(raw: str) -> dict:
    try:
        return json.loads(raw)
    except json.JSONDecodeError as e:
        raise OrderError("<unknown>", "malformed JSON") from e
 
try:
    load_order("{not-json")
except OrderError as e:
    log.error("chained: %s", e)
    log.error("root cause: %s", e.__cause__)   # the original JSONDecodeError
 
# NEVER lose the original traceback. `raise NewError(...) from e` preserves it.
 
# =========================
# Part 4 · Context managers replace try/finally
# =========================
print("\n--- Part 4 · context managers ---")
 
@contextmanager
def open_and_lock(path: str):
    log.info("acquiring %s", path)
    f = open(path, "w")
    try:
        yield f
    finally:
        log.info("releasing %s", path)
        f.close()
 
with open_and_lock("/tmp/s011_demo.txt") as f:
    f.write("hello from context manager\n")
 
# Same guarantee as try/finally, expressed once at the resource layer.
 
# =========================
# Part 5 · What to do with an exception you can't handle
# =========================
print("\n--- Part 5 · logging vs re-raising ---")
 
def process_all(items: Iterable[dict]) -> list[dict]:
    """Log per-item errors but keep processing. Return successes only."""
    out: list[dict] = []
    for i, item in enumerate(items):
        try:
            out.append(process_one(item))
        except DomainError:
            log.exception("skipping item %d", i)   # logs message + traceback
    return out
 
def process_one(item: dict) -> dict:
    if "id" not in item:
        raise OrderError("<missing>", "no id field")
    return {"id": item["id"], "ok": True}
 
print(process_all([{"id": 1}, {"broken": True}, {"id": 3}]))
 
# =========================
# Part 6 · breakpoint() — pdb without the import dance
# =========================
print("\n--- Part 6 · breakpoint() ---")
 
def buggy_average(values: list[float]) -> float:
    total = sum(values)
    # Uncomment the next line to drop into pdb here:
    # breakpoint()
    return total / len(values)   # ZeroDivisionError if values is empty
 
try:
    print(buggy_average([]))
except ZeroDivisionError:
    log.exception("buggy_average failed — traceback:")
    # If you set breakpoint() above, pdb would open here.
    # Try: n (next), p total (print), p values, l (list), q (quit).
 
# =========================
# Part 7 · Reading a traceback like a pro
# =========================
print("\n--- Part 7 · traceback inspection ---")
 
def a(): b()
def b(): c()
def c(): raise ValueError("boom!")
 
try:
    a()
except ValueError:
    print("--- traceback ---")
    traceback.print_exc()
    print("--- summary ---")
    for frame in traceback.extract_tb(traceback.sys.exc_info()[2]):
        print(f"  {frame.filename}:{frame.lineno} in {frame.name}: {frame.line}")
 
# You now know where + how you got there, programmatically.
# `logging.exception` and `logger.error(..., exc_info=True)` capture the same.
 
# =========================
# Part 8 · Modern niceties
# =========================
print("\n--- Part 8 · modern tools ---")
 
# icecream (pip install icecream): print with variable names + source line.
# from icecream import ic
# ic(some_var)   # → "ic| some_var: value"
 
# ipdb (pip install ipdb): pdb with IPython niceties (colors, tab-completion).
# breakpoint() will pick up ipdb if PYTHONBREAKPOINT=ipdb.set_trace
 
# structlog (pip install structlog): structured logging (JSON) instead of f-strings.
# Vital in production so log aggregators can grep by field.
 
log.info("End of session — sample structured line", extra={"session": "s011", "ok": True})