Scope, LEGB & closures

When you use a name like total, how does Python know which total you mean? The answer is scope: the region of code where a name is visible. Understanding scope explains a whole class of confusing bugs, and it unlocks closures — the mechanism behind decorators, callbacks and factories you'll use later.

Local and global scope#

A variable assigned inside a function is local to that function. It is created when the function is called and disappears when it returns. Variables assigned at the top level of a file are global to that module.

x = "global x"

def demo():
    x = "local x"          # a NEW local variable; the global is untouched
    y = "only inside"
    print("inside:", x, "/", y)

demo()
print("outside:", x)

inside: local x / only inside
outside: global x

Trying to use y outside the function raises NameError: name 'y' is not defined.

Functions can read global variables without doing anything special:

TAX_RATE = 0.18

def with_tax(amount):
    return amount * (1 + TAX_RATE)   # reads the global

print(with_tax(100))

118.0

Reading module-level constants like this is perfectly normal.

The LEGB rule#

When Python meets a name, it searches four scopes in order and uses the first match:

1. Local — names assigned in the current function.
2. Enclosing — names in any outer function(s), for nested functions.
3. Global — names at the top level of the module.
4. Built-in — Python's predefined names: len, print, range, ValueError…

name = "global"

def outer():
    name = "enclosing"

    def inner():
        name = "local"
        print(name)
    inner()
    print(name)

outer()
print(name)
print(len("abc"))     # len found in built-ins

local
enclosing
global
3

If no scope has the name, you get a NameError. This is also why shadowing built-ins is dangerous: a global named list or sum is found before the built-in.

sum = 10               # shadows the built-in sum()
try:
    print(sum([1, 2, 3]))
except TypeError as e:
    print("Error:", e)
del sum                # remove the global; the built-in is visible again
print(sum([1, 2, 3]))

Error: 'int' object is not callable
6

The UnboundLocalError trap#

Python decides whether a name is local when the function is compiled, not line by line. If a function assigns to a name anywhere in its body, that name is local everywhere in the body:

count = 0

def increment():
    count += 1        # read count (local!) then assign — but it has no value yet
    return count

increment()

UnboundLocalError: cannot access local variable 'count' where it is not associated with a value

Fix 1 (usually best): pass in, return out

def increment(count):
    return count + 1

count = 0
count = increment(count)
count = increment(count)
print(count)

2

Fix 2: the global statement

count = 0

def increment():
    global count      # "count refers to the module-level variable"
    count += 1

increment()
increment()
print(count)

2

global works, but functions that secretly change globals are hard to test and reason about. Reserve it for rare cases like a module-level cache or configuration set once at start-up.

Mutating vs reassigning

You don't need global to mutate a global mutable object — only to reassign the name:

seen = []

def remember(item):
    seen.append(item)     # mutation: no assignment to `seen`, so no problem

remember("a")
remember("b")
print(seen)

['a', 'b']

Nested functions and closures#

Functions can be defined inside other functions. The inner function can see the outer function's variables — and it keeps them alive even after the outer function has returned. That combination is called a closure.

def make_multiplier(factor):
    def multiply(x):
        return x * factor      # `factor` comes from the enclosing scope
    return multiply            # return the function itself, not a call

double = make_multiplier(2)
triple = make_multiplier(3)
print(double(10), triple(10))
print(double.__closure__[0].cell_contents)

20 30
2

Each call to make_multiplier creates a new factor and a new multiply that remembers it. Closures are a lightweight way to create configured functions — a "function factory".

nonlocal: changing enclosing variables

Just like global, reassigning an enclosing variable requires a declaration — nonlocal:

def make_counter():
    count = 0

    def counter():
        nonlocal count
        count += 1
        return count

    return counter

c1 = make_counter()
c2 = make_counter()
print(c1(), c1(), c1())
print(c2())       # independent state

1 2 3
1

Each counter has its own private count that no outside code can touch — a tiny taste of encapsulation without classes.

The late-binding gotcha

Closures capture variables, not values. A closure looks up the variable's value when it's called:

funcs = []
for i in range(3):
    funcs.append(lambda: i)

print([f() for f in funcs])       # all see the final i

fixed = []
for i in range(3):
    fixed.append(lambda i=i: i)   # default arg captures the current value
print([f() for f in fixed])

[2, 2, 2]
[0, 1, 2]

Scope and blocks: a Python quirk#

Unlike C or Java, if, for, while and with blocks don't create a new scope. A variable assigned inside a loop is still available afterwards:

for i in range(3):
    last = i * 10

print(i, last)

2 20

(Comprehensions do have their own scope, so the loop variable of [x for x in data] doesn't leak.)

Inspecting scopes#

locals() and globals() return dictionaries of the names currently in scope — handy for debugging and learning:

def show():
    a, b = 1, 2
    print(sorted(locals()))

show()

['a', 'b']

Worked example: a rate limiter using a closure#

import time

def make_rate_limiter(max_calls, period):
    calls = []

    def allow():
        now = time.monotonic()
        # forget calls older than the period
        while calls and now - calls[0] > period:
            calls.pop(0)
        if len(calls) < max_calls:
            calls.append(now)
            return True
        return False

    return allow

allow = make_rate_limiter(max_calls=3, period=1.0)
print([allow() for _ in range(5)])

[True, True, True, False, False]

The calls list lives in the enclosing scope, shared by every call to allow but hidden from the rest of the program.

Common mistakes#

• UnboundLocalError from assigning to a global inside a function — pass and return values instead.
• Overusing global — it makes code hard to test.
• Shadowing built-ins (list, dict, id, input, sum).
• Late binding in closures created in loops — capture the value with a default argument.

What's next#

That completes the beginner foundations! In the intermediate section we'll make functions more flexible with *args, **kwargs and lambdas.