Scope, LEGB Resolution, global & nonlocal

Variable name resolution in Python follows the strict LEGB Rule (Local $\rightarrow$ Enclosing $\rightarrow$ Global $\rightarrow$ Built-in). At compile time, CPython analyzes symbol scopes to emit optimized variable lookup opcodes.

This chapter details the LEGB resolution sequence, LOAD_FAST vs LOAD_GLOBAL vs LOAD_DEREF opcodes, UnboundLocalError mechanics, and the explicit scoping controls global and nonlocal.

1. The LEGB Resolution Rule

When a variable name is evaluated, CPython searches four nested scopes in strict order:

The LEGB Scope Resolution Sequence:

[ L ] Local Scope       --> Names assigned inside current function / comprehension
          |
          v (If not found locally)
[ E ] Enclosing Scope   --> Names in outer enclosing functions (Closures)
          |
          v (If not found in enclosing scope)
[ G ] Global Scope      --> Module-level names in current file (__main__ or module dict)
          |
          v (If not found in module globals)
[ B ] Built-in Scope   --> Pre-loaded built-ins (builtins module: len, range, ValueError)

If the name is not found in any of the four LEGB layers, CPython raises a NameError.

2. Bytecode Opcode Performance: `LOAD_FAST` vs. `LOAD_DEREF`

Scope resolution isn’t determined at runtime via string hashing for every scope layer; CPython’s compiler analyzes scope at compile time:

Local Scope (LOAD_FAST / STORE_FAST): Fast C-array index lookup in f_localsplus. $O(1)$ constant time.
Enclosing Scope (LOAD_DEREF / STORE_DEREF): Accesses PyCellObject pointers shared between enclosing and inner functions.
Global Scope (LOAD_GLOBAL): Dictionary hash lookup in func_globals (globals()).
Built-in Scope (LOAD_GLOBAL fallback): Fallback dictionary hash lookup in builtins.__dict__.

3. The `UnboundLocalError` Trap

A common pitfall occurs when a variable is referenced before assignment inside a function where that same variable name is assigned later in the function body:

x = 10  # Global variable

def process():
    print(x)  # TRAP: UnboundLocalError: local variable 'x' referenced before assignment!
    x = 20    # Compiler sees assignment and marks 'x' as LOCAL for the entire function!

process()

Why it Happens:

CPython’s compiler analyzes the entire function body at compile time. Because x = 20 exists anywhere inside process(), CPython marks x as a Local variable for the entire function and emits LOAD_FAST. At execution time, print(x) attempts to load x from the local array before it has been bound, triggering UnboundLocalError.

4. Scoping Modifiers: `global` vs. `nonlocal`

global x: Instructs the compiler to bypass Local and Enclosing scope bounds, forcing reads and assignments of x to target the module-level Global scope.
nonlocal x: Instructs the compiler to bypass Local scope and target the nearest variable x in an Enclosing function scope (required when mutating closure state).

def outer():
    count = 0  # Enclosing variable

    def inner():
        nonlocal count  # Bypasses local scope, binds to outer's count
        count += 1
        return count

    return inner

⚡

Revision Mode Active Condensed for 5-minute review. Focused on 30-second pitches, mental anchors, and high-frequency interview traps.

⚡ 30-Second Elevator Pitch

“Python name resolution follows LEGB (Local, Enclosing, Global, Built-in). At compile time, CPython optimizes local variable access using LOAD_FAST C-array indexing, while global access uses LOAD_GLOBAL dictionary lookups. Assigning to a name anywhere inside a function marks it as Local for the entire function scope, causing UnboundLocalError if read prior to assignment unless global or nonlocal is declared.”

🧠 Under The Hood & Mental Model

Compile-Time Scope Binding: CPython determines whether a name is local, global, or dereferenced at compile time based on assignment statements in the AST.
LOAD_FAST Array Index: Local variables skip string dictionary lookups entirely, reading directly from an array of PyObject* pointers in the execution frame.
UnboundLocalError Invariant: Occurs because variable scope is static per function, not dynamic per line of code.
PyCellObject (nonlocal): Wraps a pointer to shared variable storage on the heap, enabling inner functions to mutate outer scope variables.

💻 High-Yield Code & Gotcha

# ❌ ANTI-PATTERN: Accidentally Triggering UnboundLocalError
counter = 0

def increment():
    # TRAP: Assignment makes counter LOCAL to increment(), breaking the print!
    counter += 1  # UnboundLocalError: local variable 'counter' referenced before assignment

# ✅ PRODUCTION PATTERN: Explicit Scope Declaration or Return Passing
counter = 0

def increment_global():
    global counter
    counter += 1  # Explicit global modification

# BETTER: Functional state passing (no global mutation)
def increment_pure(val: int) -> int:
    return val + 1

⚠️ GOTCHA: `nonlocal` Searching Boundary

nonlocal only searches Enclosing function scopes. It cannot bind to Global (G) or Built-in (B) scopes. If no matching variable exists in an enclosing function, Python raises a SyntaxError: no binding for nonlocal 'x' found.

⚖️ Trade-Offs & Comparison

+ LOAD_FAST: Local variables execute faster than global or built-in lookups.
- global Mutations: Mutating global variables breaks thread safety and makes code difficult to unit test and reason about.

🌟 My Experience (STAR Anchor)

“A stateful stream aggregator failed in production with UnboundLocalError after a developer added an error counter assignment inside a inner closure handler. I refactored the closure to use nonlocal cell binding and eventual state return, eliminating scope resolution crashes and preserving state integrity.”

Python Interview Handbook

Scope, LEGB Resolution, global & nonlocal

1. The LEGB Resolution Rule

2. Bytecode Opcode Performance: `LOAD_FAST` vs. `LOAD_DEREF`

3. The `UnboundLocalError` Trap

Why it Happens:

4. Scoping Modifiers: `global` vs. `nonlocal`

⚡ 30-Second Elevator Pitch

🧠 Under The Hood & Mental Model

💻 High-Yield Code & Gotcha

⚠️ GOTCHA: `nonlocal` Searching Boundary

⚖️ Trade-Offs & Comparison

🌟 My Experience (STAR Anchor)

Walk through the LEGB rule for Python variable name resolution.

No Interactive Questions Yet

Scope, LEGB Resolution, global & nonlocal

1. The LEGB Resolution Rule

2. Bytecode Opcode Performance: LOAD_FAST vs. LOAD_DEREF

3. The UnboundLocalError Trap

Why it Happens:

4. Scoping Modifiers: global vs. nonlocal

⚡ 30-Second Elevator Pitch

🧠 Under The Hood & Mental Model

💻 High-Yield Code & Gotcha

⚠️ GOTCHA: nonlocal Searching Boundary

⚖️ Trade-Offs & Comparison

🌟 My Experience (STAR Anchor)

Walk through the LEGB rule for Python variable name resolution.

No Interactive Questions Yet

2. Bytecode Opcode Performance: `LOAD_FAST` vs. `LOAD_DEREF`

3. The `UnboundLocalError` Trap

4. Scoping Modifiers: `global` vs. `nonlocal`

⚠️ GOTCHA: `nonlocal` Searching Boundary