Skip to content

Python Closures, Captured State, and Late Binding

Step 33 of 41

Python Closures: Factories, Free Variables, and nonlocal State

Introduction

Python closures retain bindings from enclosing function calls. A factory can configure a discount function once and return a callable that needs only a price. A stateful closure can also update a counter across calls by rebinding its enclosing variable with nonlocal.

This lesson covers objective 5.3 in PCAP-31-03 Comprehensions, Lambdas, Closures, and I/O (22% of the score, 9 of 40 items). You will trace captured cells, distinguish returning a function from calling it, and separate factory-local state from shared mutable objects.

Learning objectives

After this lesson you can:

  1. Define a nested function and identify its free variables and its enclosing scope.
  2. Explain the difference between returning a function (return inner) and calling it (return inner()).
  3. Build closure factories that produce independent, configured functions.
  4. Explain why captured data survives after the enclosing function has returned.
  5. Use nonlocal to build a closure that updates its own state, and explain why it is needed.
  6. Predict the output of programs that create several closures and call them in turn.
  7. Inspect a closure with __closure__ and __code__.co_freevars to confirm what it captured.

Review Python functions and bound methods if storing a callable is still confused with calling it. For an inner function, the enclosing cells provide the additional state.

Nested functions and free variables

Python lets you define a function inside another function. The inner function is created each time the outer function runs, and it can read names that belong to the outer function.

Python
def make_discount(rate):
    def apply(price):
        return round(price * (1 - rate), 2)
    return apply

ten = make_discount(0.10)
twenty = make_discount(0.20)
print(ten(100), twenty(100), ten(59.9))

Output:

Text
90.0 80.0 53.91

Let us name the parts. make_discount is the enclosing function and apply is the nested function. The name rate is a parameter of make_discount; inside apply it is neither a parameter nor assigned, so it is a free variable: a name used in a function but defined in an enclosing function scope rather than in the function itself. The name price is local to apply.

When Python resolves a name inside a function, it follows the LEGB order: Local, Enclosing function scopes, Global, Built-in. The "E" is what makes closures work: after the local scope of apply fails to provide rate, Python looks in the scope of make_discount.

A closure retains cells for bindings from enclosing function scopes. Global lookups also occur at call time, but they use the function’s global namespace rather than __closure__ cells. ten and twenty are both closures built from the same code, apply, but each one carries its own rate.

A concrete case

An online shop gives partners different discount rates. Instead of writing one function per partner or passing the rate on every call, the shop calls make_discount(0.10) once for a small partner and make_discount(0.20) for a large one. Afterwards the code that applies the discount only needs price: ten(100) gives 90.0. The configuration (the rate) is fixed at creation; the data (the price) arrives later. This is the main use of closures: configure once, call many times.

What does the closure remember?

The surprising point for beginners is that rate still exists after make_discount has returned. Normally the local variables of a function disappear when it finishes. A variable that is used by a nested function is different: Python keeps it alive in a cell that the nested function refers to. You can see it:

Python
print(ten.__code__.co_freevars)
print(ten.__closure__[0].cell_contents, twenty.__closure__[0].cell_contents)
print(ten is twenty)

Output:

Text
('rate',)
0.1 0.2
False

co_freevars lists the names of the free variables, here ('rate',). __closure__ is a tuple of cells, one per free variable, and cell_contents is the value. ten and twenty are two different function objects, with two different cells. A function that has no free variables has __closure__ equal to None.

The important consequence is about lifetime. That invocation of make_discount has finished, while the factory function object remains available for other calls. Its captured binding remains reachable through the returned closure. When ten is deleted and nothing else refers to it, its cell can be freed.

Python
def make_partner_discount(rate, cap):
    def apply(price):
        d = min(price * rate, cap)
        return round(price - d, 2)
    return apply

gold = make_partner_discount(0.15, 20)
del make_partner_discount
print(gold(100))

Output:

Text
85.0

Deleting the factory name does not affect gold: the closure keeps the two values it captured (rate and cap). The calculation is min(15.0, 20) = 15.0, hence 100 - 15.0 = 85.0.

Returning a function versus calling it

Many mistakes come from confusing these two forms.

Python
def outer():
    def inner():
        return "hi"
    return inner

print(outer()())
print(callable(outer()), outer().__name__)
x = outer
print(x()())

Output:

Text
hi
True inner
hi

return inner returns the function object itself, which is then called later with parentheses. return inner() would call it immediately and return the string. In the first line outer() is the call of the factory and the second () is the call of the function it returned. In the last two lines x = outer copies a reference, so x()() has the same effect.

Expression What it is
outer The factory function object
outer() The function inner (a new object each time)
outer()() The string "hi"
inner inside outer A name local to outer; not visible from outside

Each call of outer() creates a new inner function object. In this example, each call executes the nested def and creates a distinct function. A factory call is not a copying operation: separate closure cells can still refer to a shared mutable object passed to both calls.

A lambda can also be a closure. This is equivalent to the nested def pattern and is common in short factories:

Python
def make_prefixer(p):
    return lambda s: p + s

pre = make_prefixer(">> ")
print(pre("ok"))

Output:

Text
>> ok

The lambda has the free variable p, which comes from make_prefixer.

Captured variables, not captured values

A closure captures the variable (the cell), not a snapshot of its value at creation. The value is read when the closure is called. For a parameter that is never reassigned, the two behaviours look the same. They differ when the enclosing variable changes after the closure was built. See late binding and capture timing for callbacks built in a loop. Here a global lookup provides a comparison, not an example of a closure cell.

Python
p = 5
def g():
    return p
p = 6
print(g())

Output:

Text
6

This example uses a global variable, but the principle is the same: the name is looked up at call time. Do not expect g() to give 5.

A factory invocation creates a new enclosing scope, but callbacks from one invocation may share cells. A captured mutable value may also be changed through an outside reference. The introspection attribute cell_contents is writable; it should not be treated as protected storage. This leads us to nonlocal.

Stateful closures and nonlocal

A closure can keep a counter or a running total. To rebind a variable of the enclosing scope, the inner function must declare it with nonlocal.

Python
def counter(start=0):
    count = start
    def step(n=1):
        nonlocal count
        count += n
        return count
    return step

a = counter()
b = counter(10)
print(a(), a(), a(5), b(), a())

Output:

Text
1 2 7 11 8

Trace it. a has its own count, starting at 0: a() gives 1, a() gives 2, a(5) gives 7. b has a different count starting at 10: b() gives 11. The last a() continues with its own value, 7 + 1 = 8. The two counters never interfere.

What if nonlocal is missing? Python decides that a name is local to a function if the function assigns to it anywhere in its body. The statement total = total + n makes total local, and reading it before it has a value fails:

Python
def no_nonlocal():
    total = 0
    def add(n):
        total = total + n
        return total
    return add

try:
    no_nonlocal()(1)
except UnboundLocalError as e:
    print("UnboundLocalError", e)

Output (the message wording depends on the Python version):

Text
UnboundLocalError cannot access local variable 'total' where it is not associated with a value

UnboundLocalError is a subclass of NameError. Adding nonlocal total at the top of add fixes it. Note that nonlocal is only needed for rebinding with = or +=. Calling a method that mutates an object does not rebind the name:

Python
def acc():
    items = []
    def add(x):
        items.append(x)
        return len(items)
    return add

f = acc()
print(f("a"), f("b"))

Output:

Text
1 2

items.append(x) modifies the list in place; the name items is not reassigned, so no nonlocal is needed. The list lives in the cell and is shared by every call of the same closure.

nonlocal differs from global. global x refers to a module-level name; nonlocal x selects the nearest enclosing function scope that already binds x, skipping intervening function scopes without that binding. Without a suitable binding it is a SyntaxError; it does not select a module global.

Several closures made by the same call of the factory can share one variable:

Python
def stats():
    calls = 0
    def use():
        nonlocal calls
        calls += 1
        return calls
    def peek():
        return calls
    return use, peek

use, peek = stats()
use()
use()
print(peek())

Output:

Text
2

use and peek are two functions that refer to the same cell for calls, because they were created in the same call of stats. peek sees what use has changed.

Worked example: a capped partner discount

Statement. A shop defines the factory below. Predict the output of the four calls and explain why gold and silver do not affect one another.

Python
def make_partner_discount(rate, cap):
    def apply(price):
        d = min(price * rate, cap)
        return round(price - d, 2)
    return apply

gold = make_partner_discount(0.15, 20)
silver = make_partner_discount(0.05, 20)
print(gold(100), gold(200), silver(100), silver(1000))

Step 1: identify the free variables. apply uses rate and cap without defining them, so both are free variables. price and d are local.

Step 2: separate the two closures. gold carries rate=0.15, cap=20; silver carries rate=0.05, cap=20. Each call of the factory created a new scope.

Step 3: compute gold(100). 100 * 0.15 = 15.0; min(15.0, 20) = 15.0; 100 - 15.0 = 85.0.

Step 4: compute gold(200). 200 * 0.15 = 30.0; the cap limits the discount: min(30.0, 20) = 20; 200 - 20 = 180, and round(180, 2) stays 180 because the operands are integers.

Step 5: compute silver(100) and silver(1000). 100 * 0.05 = 5.0, so 95.0. For 1000: 1000 * 0.05 = 50.0, capped at 20, so 980.

Text
85.0 180 95.0 980

Why other answers are worse. Answering 180.0 ignores that min returns the integer 20 when the cap wins, so the subtraction is integer. Answering 970 or 950 for the last value applies the uncapped discount. Assuming that gold and silver share rate mixes two scopes: a new enclosing scope exists for every call of make_partner_discount.

Common pitfalls and exam tips

Pitfall What happens Remedy
return inner() instead of return inner The factory returns a result, not a function Return the name without parentheses
Reading a name before a local assignment when an enclosing update was intended UnboundLocalError Use nonlocal for an existing enclosing binding
Using nonlocal for a name at module level SyntaxError (no binding for nonlocal found) Use global, or restructure
Using nonlocal for list.append Not needed, but harmless nonlocal is for rebinding only
Assuming all factory calls share the same cell Fresh invocations have separate local bindings Count invocations and separately inspect shared mutable objects
Believing the captured value is copied at creation The variable is read at call time See lesson 12.2
Expecting __closure__ on every function A function without free variables has None Check co_freevars
Forgetting that default parameters are evaluated once at definition Different mechanism from closures Do not mix the two models

Exam tip. When a program creates several closures, write a small table with one column per closure and one line per call; update the captured variable after each call.

Exam tip. Count parentheses: f is the function, f() is its result, and f()() calls the result. A TypeError: 'int' object is not callable often means one pair too many.

Exam tip. Remember that the inner function can read a free variable freely. nonlocal is needed only when it assigns.

Exam tip. An augmented assignment such as count += 1 is an assignment. In a nested function without nonlocal, it produces UnboundLocalError.

End-of-lesson case study

Situation. A support team wants a function that limits how many API requests a client may make. The limit is a non-negative integer and each request count must be a positive integer; invalid arguments raise ValueError. Predict the output for the valid calls below and explain each result.

Python
def make_limiter(limit):
    if type(limit) is not int or limit < 0:
        raise ValueError("limit must be a non-negative integer")
    used = 0
    def spend(n):
        nonlocal used
        if type(n) is not int or n <= 0:
            raise ValueError("request count must be a positive integer")
        if used + n > limit:
            return False
        used += n
        return True
    return spend

s = make_limiter(10)
print(s(4), s(5), s(2), s(1), s(1))

Solution, commented. limit is fixed at 10 and used starts at 0. s(4): 0 + 4 > 10 is false, so used becomes 4 and the call returns True. s(5): 4 + 5 = 9, not above 10, so used becomes 9 and the result is True. s(2): 9 + 2 = 11 > 10, so the function returns False without changing used, which stays 9. s(1): 9 + 1 = 10, not above 10, so used becomes 10 and the result is True. The last s(1): 10 + 1 = 11 > 10, so False.

Text
True True False True False

Two lessons from this case. First, a rejected request does not consume the quota: the return False happens before the assignment. Second, nonlocal used is required because used += n rebinds the variable; limit is only read and needs no declaration. If the developer removed nonlocal used, the first valid request would raise UnboundLocalError because the augmented assignment makes used local. The argument checks also prevent a negative request from reducing usage and creating extra quota.

Key terms

  • Nested function: a function defined inside another function.
  • Free variable: a name used in a function but defined in an enclosing function scope.
  • Closure: a function object together with the free variables it captured.
  • Cell: the container that holds a captured variable; seen through __closure__.
  • Closure factory: a function whose purpose is to return a configured inner function.
  • nonlocal: selects the nearest enclosing function scope with an existing binding for the declared name.
  • LEGB: the name lookup order: Local, Enclosing, Global, Built-in.

Summary checklist

  • I can identify the free variables of a nested function.
  • I know the difference between return inner and return inner().
  • I distinguish separate factory-local bindings from mutable objects that several calls may share.
  • I know captured data stays alive after the enclosing function returns.
  • I know when nonlocal is required and when it is not.
  • I can predict the output of a stateful counter or limiter.
  • I can distinguish ordinary local shadowing from reading an uninitialized local before assignment.
  • I can use __closure__ and co_freevars to inspect a closure.

Official sources