Exceptions, Tracebacks, Custom Errors & Error Boundaries

Error handling in Python relies on a zero-cost exception handling table (CPython 3.11+), traceback objects (PyTracebackObject), and explicit exception chaining. Writing enterprise-grade Python software requires understanding how CPython propagates exceptions up the call stack, how exception chaining (from e vs from None) works, and how to structure custom domain exception hierarchies.

This chapter details CPython 3.11+ zero-cost exception tables, traceback frame objects, exception cause/context chaining, and custom exception boundaries.

1. CPython 3.11+ Zero-Cost Exception Handling Tables

Prior to Python 3.11, entering a try/except block executed SETUP_FINALLY opcodes that dynamically pushed exception handlers onto the frame stack, incurring a small runtime overhead on every try block entry.

CPython 3.11 introduced Zero-Cost Exceptions (PEP 657):

• Zero Overhead on Happy Path: Entering a try block executes zero extra opcodes.
• Exception Table Lookup: When an exception is raised, CPython looks up the instruction pointer offset in a static compiler-generated Exception Table mapping bytecode offset ranges to exception handler offsets.

CPython Zero-Cost Exception Table:

Bytecode Range        Handler Offset        Type
------------------------------------------------------
[ 10 .. 42 ]   -->    Offset 44             catch (ValueError)
[ 44 .. 80 ]   -->    Offset 82             finally

This makes try blocks in Python 3.11+ completely free of CPU overhead until an actual exception is raised!

2. Exception Objects & Traceback Frames (PyTracebackObject)

When an exception is raised (raise ValueError("invalid")), CPython instantiates a subclass of BaseException and attaches three critical attributes:

1. __traceback__: A linked list of PyTracebackObject frames recording tb_frame (stack frame), tb_lineno (line number), and tb_next (next frame in call stack).
2. __cause__: Explicit cause established via raise NewException() from original_exc.
3. __context__: Implicit context established automatically when an exception occurs inside an existing except or finally block.

3. Exception Chaining: from e vs. from None

When wrapping infrastructure or database errors inside domain-specific exceptions, explicit exception chaining controls traceback output:

# 1. EXPLICIT CHAINING (from original_error): Preserves full root-cause traceback
try:
    db.connect()
except OperationalError as e:
    raise DatabaseConnectionError("Failed to connect to primary DB") from e

# 2. SUPPRESSING CAUSE (from None): Hides internal implementation details
try:
    vault.get_secret()
except SecretNotFoundError as e:
    raise UnauthorizedError("Access Denied") from None

Exception Traceback Output:

'raise NewException() from e':
 -> Displays: "The above exception was the direct cause of the following exception:"

'raise NewException() from None':
 -> Suppresses inner traceback; displays ONLY the top-level domain exception!

4. Production Exception Hierarchy Architecture

Always create a single base domain exception for your application/library, inheriting from Exception (never BaseException):

# Base Domain Exception for the App
class ApplicationError(Exception):
    """Base exception for all application domain errors."""

class ValidationError(ApplicationError):
    """Raised when domain validation fails."""

class PaymentGatewayError(ApplicationError):
    """Raised when external payment provider fails."""

This allows API consumers to catch except ApplicationError: to handle all domain-level exceptions while allowing system signals (KeyboardInterrupt, SystemExit) to pass through.