Python Closures — Late Binding Loop Bug in Rate Limiters

Most Python developers hit a wall around the same time: they understand functions, they understand variables, and then they write slightly more complex code and something weird happens — a function 'remembers' a value it seemingly shouldn't have access to anymore. That moment of confusion is actually you bumping into one of Python's most powerful and elegant features: closures. They're not an advanced academic concept — they're built into how Python evaluates and stores functions, and once you get them, a whole class of real-world problems becomes easy to solve.

The problem closures solve is surprisingly common: how do you give a function some persistent, private state without creating a whole class? Before closures, the only clean answer was to write a class with an __init__ method and self.some_value sprinkled everywhere — a lot of ceremony for something conceptually simple. Closures let you attach state to a function directly, keeping that state private and scoped exactly to where it's needed. They're also the engine under the hood of Python decorators, which means understanding closures is the key to understanding one of Python's most widely-used patterns.

By the end of this article you'll know exactly what makes a closure a closure (it's a specific three-part contract Python enforces), you'll be able to write closures that solve real problems like function factories and stateful callbacks, and you'll know the two gotchas that trip up almost every developer the first time they use closures in a loop. Let's build it up from scratch.

What Python Actually Needs to Form a Closure

A closure isn't magic — it's the result of three specific conditions being true at the same time. First, there must be a nested function (a function defined inside another function). Second, the inner function must reference at least one variable from the outer function's scope — not a global variable, not one of its own local variables, but one that belongs to the enclosing function. Third, the outer function must return the inner function. When all three are true, Python doesn't just return a plain function object. It returns a function object bundled together with a snapshot of the variables it referenced from outside. That bundle is the closure.

You can actually inspect this bundle yourself. Every closure in Python has a __closure__ attribute, which is a tuple of 'cell' objects. Each cell holds one of those remembered variables. If a function has no closure, __closure__ is None. This isn't just trivia — it's confirmation that Python is doing real work to preserve that state for you.

The variable that gets captured is called a 'free variable'. It's free because it isn't local to the inner function and isn't global — it floats between those two worlds, owned by the enclosing scope. Understanding this scoping layer (called the Enclosing scope in Python's LEGB rule) is the key to predicting how closures behave.

# Demonstrates the three conditions that form a closure
# and how to inspect the captured state Python stores.

def make_multiplier(factor):           # Outer function defines 'factor'
    """Returns a function that multiplies any number by 'factor'."""

    def multiply(number):              # Inner function — condition 1: nested function
        return number * factor         # References 'factor' from outer scope — condition 2

    return multiply                    # Returns the inner function — condition 3


# Creating two separate multiplier functions from the same template
double = make_multiplier(2)
triple = make_multiplier(3)

print(double(10))   # 'factor' remembered as 2
print(triple(10))   # 'factor' remembered as 3
print(double(7))    # Each closure has its OWN independent 'factor'

# Inspecting the closure internals Python stores under the hood
print(type(double))                         # It's a regular function object
print(double.__closure__)                   # Tuple of cell objects holding captured vars
print(double.__closure__[0].cell_contents)  # The actual value of 'factor' stored inside
print(double.__code__.co_freevars)          # Name of every free variable this closure captured

LEGB Scope Resolution — Step-by-Step Visual

Python resolves variable names using the LEGB rule: Local, Enclosing, Global, Built-in. Closures rely on the Enclosing (E) scope. When Python executes a nested function, it first looks for a variable in the function's local scope (L). If not found, it inspects the enclosing function's local scope (E) — that's where free variables live. Next comes the global module scope (G), then the built-in namespace (B) for functions like len and print. This chain is evaluated at runtime, which is why closures can see updated values of variables until they are called.

Understanding LEGB is crucial for debugging closures. If a variable unexpectedly resolves to a global instead of an enclosing scope, Python skipped the E because either the variable wasn't captured (not referenced in the inner function) or the inner function wasn't truly a closure (not returned). The diagram below walks through a typical scope chain for a closure.

The 'nonlocal' Keyword — Mutating Enclosed Variables

By default, Python treats any assignment inside a nested function as creating a new local variable. To modify a variable from an enclosing (non-global) scope, you must declare it nonlocal. This keyword tells Python: 'bind this name to the variable in the nearest enclosing scope that is not global.' Without nonlocal, writing count += 1 inside a nested function raises UnboundLocalError because Python sees the assignment and considers count local, but then can't find an initial value before the increment.

nonlocal is commonly used in closures that maintain mutable state: counters, accumulators, caches, and retry trackers. It is different from global: nonlocal climbs up only through function scopes, while global bypasses all function scopes and goes straight to the module level.

A key nuance: nonlocal is only valid at the beginning of a function (before any code that uses the variable), and the variable must already exist in an enclosing function scope. If the variable is not defined in any enclosing function, Python raises a SyntaxError at compile time. This is a safety net — it prevents accidental creation of a new global or outer scope variable.

Below is an example that demonstrates correct nonlocal usage for a closure that accumulates a sum.

# Demonstrates 'nonlocal' for mutating an enclosed variable.

def make_accumulator(initial=0):
    total = initial

    def add(x):
        nonlocal total
        total += x
        return total

    return add

acc = make_accumulator(10)
print(acc(5))   # 15
print(acc(3))   # 18
print(acc(-2))  # 16

# Without nonlocal, this would raise UnboundLocalError

# Another pattern: closure with reset capability
def make_mutable_counter():
    count = 0
    def increment():
        nonlocal count
        count += 1
        return count
    def reset():
        nonlocal count
        count = 0
    return increment, reset

inc, rst = make_mutable_counter()
print(inc())  # 1
print(inc())  # 2
rst()
print(inc())  # 1

Closures With Mutable State — Building a Counter Without a Class

So far the closure variables have been read-only inside the inner function. But what if you need the inner function to update that variable — to keep a running count, for example? This is where Python's nonlocal keyword comes in. Without it, any assignment inside the inner function creates a brand-new local variable and shadows the outer one rather than updating it. Python treats assignment as declaration by default.

nonlocal is your explicit instruction to Python: 'when I assign to this name, go up to the enclosing scope and update the variable there, don't create a new local one.' It's the closure equivalent of the global keyword, but scoped to the enclosing function rather than the module level. You should reach for nonlocal only when you genuinely need mutable state in a closure — if you're using it everywhere, a class is probably the cleaner choice.

The stateful counter pattern is a textbook example, but the real-world version is more interesting: rate limiters, request counters, retry trackers, and progress accumulators all use this exact shape. The closure gives each counter its own private state, completely isolated from any other counter you create from the same factory.

# Simulates an API endpoint call counter with a reset capability.
# Uses 'nonlocal' to mutate state stored in the closure.

def make_request_counter(endpoint_name):
    """Returns a counter function tied to a specific API endpoint."""
    call_count = 0   # This is the state we want to mutate from inside the inner function

    def record_call():
        nonlocal call_count              # Tell Python: update the OUTER 'call_count', don't create a new local one
        call_count += 1
        print(f"[{endpoint_name}] Call #{call_count}")

    def get_count():
        return call_count                # Read-only — no 'nonlocal' needed for reads

    def reset_count():
        nonlocal call_count
        call_count = 0
        print(f"[{endpoint_name}] Counter reset.")

    # Return multiple inner functions as a named tuple for clean access
    # All three share the SAME 'call_count' cell — they're all part of one closure
    return record_call, get_count, reset_count


# Create independent counters for two different endpoints
track_login,  get_login_count,  reset_login  = make_request_counter("/api/login")
track_search, get_search_count, reset_search = make_request_counter("/api/search")

track_login()
track_login()
track_search()
track_login()

print(f"Total login calls:  {get_login_count()}")
print(f"Total search calls: {get_search_count()}")

reset_login()
print(f"Login count after reset: {get_login_count()}")

The Classic Loop-Closure Gotcha (And Two Ways to Fix It)

Here's the trap that catches almost every developer writing closures inside a loop for the first time. You want to create a list of functions, each capturing a different loop variable. You write what looks like perfectly reasonable code, run it, and every single function in the list returns the same value — the last value the loop variable had. This isn't a bug in Python. It's the correct behaviour once you understand what closures actually capture.

A closure captures a variable by reference, not by value. That means all the inner functions point to the same index variable in the enclosing scope. By the time you call any of those functions, the loop has finished and index has settled at its final value. Every function looks up index right then, at call time, and sees the same thing.

There are two clean fixes. The first is to use a default argument in the inner function (def greet(name=name):), which forces the current value to be captured by value at definition time. The second is to wrap the inner function in another function call that immediately captures the current value in its own closure scope. Both work — the default argument approach is slightly more Pythonic for simple cases.

# Demonstrates the classic loop-closure bug and TWO correct fixes.

user_names = ["alice", "bob", "carol"]

# ---- THE BUG ------------------------------------------------
buggy_greeters = []
for name in user_names:
    def greet_buggy():
        return f"Hello, {name}!"   # Captures 'name' BY REFERENCE — looks it up at call time
    buggy_greeters.append(greet_buggy)

# Loop is done, 'name' is now "carol" for everyone
print("Buggy output:")
for greeter in buggy_greeters:
    print(greeter())   # Every function sees the LAST value of 'name'

# ---- FIX 1: Default Argument (captures value at definition time) ----
fixed_greeters_v1 = []
for name in user_names:
    def greet_with_default(captured_name=name):  # Default arg evaluated NOW, not at call time
        return f"Hello, {captured_name}!"
    fixed_greeters_v1.append(greet_with_default)

print("\nFix 1 — Default argument:")
for greeter in fixed_greeters_v1:
    print(greeter())

# ---- FIX 2: Wrapping factory (creates a fresh enclosing scope each iteration) ----
def make_greeter(person_name):          # Each call to make_greeter creates a NEW scope
    def greet():                        # 'person_name' is bound fresh in each scope
        return f"Hello, {person_name}!"
    return greet

fixed_greeters_v2 = [make_greeter(name) for name in user_names]

print("\nFix 2 — Factory function:")
for greeter in fixed_greeters_v2:
    print(greeter())

Closures and Decorators: The Hidden Relationship

Python decorators are the most widespread real-world use of closures. Every time you write @cache or @staticmethod, you're relying on the fact that a function can wrap another function and carry state. The decorator pattern is a closure: the outer function (the decorator) accepts a function, and the inner function (the wrapper) captures that function and adds behaviour before/after calling it.

Understanding this relationship demystifies decorators. When you see @decorator, Python calls decorator(func) and stores the returned closure in place of func. That returned closure references the original function and any configuration passed to the decorator factory. This means you can create parameterised decorators (like @retry(max_attempts=3)) by nesting three levels: outer factory returns a decorator, which returns a wrapper closure.

Be careful with decorator stacking: each decorator adds one layer of closure indirection. Too many layers can hurt readability and performance. Also, functools.wraps is essential to preserve the original function's metadata — without it, the wrapped closure will have the wrong __name__ and __doc__, breaking introspection tools and documentation generators.

# Demonstrates how decorators are closures wrapping the original function.
import functools
import time

def timer_decorator(func):
    """Outer function receives the decorated function. Returns a closure."""
    @functools.wraps(func)  # This copies __name__, __doc__, etc. from func to wrapper
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)      # 'func' is a free variable captured by the closure
        end = time.perf_counter()
        print(f"{func.__name__} took {end - start:.4f}s")
        return result
    return wrapper

@timer_decorator
def slow_add(a, b):
    """Add two numbers after a nap."""
    time.sleep(0.1)
    return a + b

print(slow_add(3, 4))            # Output shows time, then 7
print(f"Name: {slow_add.__name__}")  # Without @wraps, this would be 'wrapper'
print(f"Doc:  {slow_add.__doc__}")   # Without @wraps, this would be None

# To verify this is a closure, inspect:
print("Closure?", slow_add.__closure__ is not None)
print("Free vars:", slow_add.__code__.co_freevars)

Closure vs Class: Memory and Syntax Comparison

When building stateful callables, developers often wonder whether to use a closure or a class. Both can hold state and expose behaviour, but they differ in syntax overhead, memory usage, and capabilities. This section breaks down the practical trade‑offs so you can make an informed decision.

Memory – A closure stores captured variables in cell objects (one cell per free variable). Each cell is approximately 56 bytes on 64‑bit Python, plus the captured object itself. A closure function object adds around 56 bytes of overhead. In contrast, a class instance has an overhead of about 64 bytes plus the instance dictionary (which can be substantial if many attributes are added dynamically). For a single stateful callable with one or two variables, closures are more memory‑efficient.

Syntax – Closures are written as nested functions; the state is implicitly captured. Classes require a class definition, an __init__ method, and explicit self references. For simple cases, closures are far less verbose. However, if you need multiple methods that share state, a closure becomes awkward (you must return a tuple of functions), while a class naturally supports any number of methods.

Introspection – Class attributes are directly accessible via instance.attribute. Closure state is hidden behind __closure__ cells, which makes debugging harder. If you need to inspect or log internal state regularly, a class is clearer.

Inheritance – Closures cannot be subclassed. Classes fully support inheritance, which is essential for polymorphic dispatch.

Pickling – Closures can be pickled only if the outer function is importable and all captured variables are picklable. Class instances are generally easier to pickle.

Below is a comparison table summarising the key differences:

# Example: same functionality — a counter with increment and reset.

# Closure approach
def make_counter_closure(initial=0):
    count = initial
    def increment():
        nonlocal count
        count += 1
        return count
    def reset():
        nonlocal count
        count = initial
    return increment, reset

inc1, reset1 = make_counter_closure(10)
print(inc1())  # 11

# Class approach
class CounterClass:
    def __init__(self, initial=0):
        self.count = initial
    def increment(self):
        self.count += 1
        return self.count
    def reset(self):
        self.count = self.initial  # wait, need to store initial

# But we need to store initial separately:
class CounterClassFixed:
    def __init__(self, initial=0):
        self.initial = initial
        self.count = initial
    def increment(self):
        self.count += 1
        return self.count
    def reset(self):
        self.count = self.initial

c = CounterClassFixed(10)
print(c.increment())  # 11