Closures and decorators

How names are resolved

Python looks names up in four places, innermost first: the local scope, any enclosing function scopes, the module's globals, and the built-ins. Which scope a name belongs to is decided when the function is compiled: if a function assigns to a name anywhere in its body, that name is local everywhere in the function. That is why this fails:

1x = 102def f():3    print(x)4    x = 25 6f()   # UnboundLocalError: cannot access local variable 'x' where it is not associated with a value

To assign to an outer variable, declare it: global x for a module variable, nonlocal x for one in an enclosing function.

Closures

1def make_counter():2    count = 03    def increment():4        nonlocal count5        count += 16        return count7    return increment8 9tick = make_counter()10tick(); tick()11print(tick())                              # 312print(tick.__closure__[0].cell_contents)   # 3

count outlives make_counter because increment holds a reference to it through a cell object, which you can see in __closure__. The closure stores the variable, not a snapshot of its value, which produces the late-binding surprise:

1fns = [lambda: i for i in range(3)]2print([f() for f in fns])                  # [2, 2, 2]3fns = [lambda i=i: i for i in range(3)]4print([f() for f in fns])                  # [0, 1, 2]

Default values are evaluated when the lambda is created, so i=i captures each value.

Decorators

@timed written above a def is shorthand for slow_square = timed(slow_square), applied immediately after the function is created:

1import functools2import time3 4def timed(fn):5    @functools.wraps(fn)6    def wrapper(*args, **kwargs):7        start = time.perf_counter()8        try:9            return fn(*args, **kwargs)10        finally:11            print(f"{fn.__name__} took {time.perf_counter() - start:.3f}s")12    return wrapper13 14@timed15def slow_square(n):16    """Square n, slowly."""17    time.sleep(0.1)18    return n * n19 20print(slow_square(4))   # prints "slow_square took 0.10…s", then 1621print(slow_square.__name__, slow_square.__doc__)   # slow_square Square n, slowly.

wrapper is a closure over fn. *args, **kwargs forwards any arguments, and try/finally reports the time even when fn raises. Without functools.wraps the decorated function would report its name as wrapper and lose its docstring, which confuses logs, debuggers and frameworks that inspect signatures.

Decorators with arguments

@retry(times=3) has one more layer: retry(times=3) is called first and returns the real decorator. So a configurable decorator is a function that returns a function that returns a function:

1def retry(times):2    def decorator(fn):3        @functools.wraps(fn)4        def wrapper(*args, **kwargs):5            for attempt in range(1, times + 1):6                try:7                    return fn(*args, **kwargs)8                except ConnectionError:9                    print("attempt", attempt, "failed")10            raise ConnectionError(f"gave up after {times} attempts")11        return wrapper12    return decorator

The standard library ships several decorators built this way, including functools.cache, functools.lru_cache, contextlib.contextmanager, property, staticmethod and dataclasses.dataclass. Class decorators work the same way, receiving the class instead of a function.