Closures and decorators in depth

Lesson 2 showed the core idea: @log_calls above a def means add = log_calls(add), run once at definition time. Real decorators need three more pieces — state, metadata, and arguments.

Closures that remember, and nonlocal

A nested function can read variables of the function around it, even after that function has returned. That captured environment is a closure, and it is how a decorator remembers which function it wraps.

Assigning is different. Python decides at compile time that any name assigned inside a function is local to it, so count += 1 inside the inner function refers to a local count that has no value yet, and raises UnboundLocalError. nonlocal count says "the one in the enclosing function"; global does the same for module level.

1def make_ticketer():2    count = 03 4    def next_ticket():5        nonlocal count6        count += 17        return count8 9    return next_ticket10 11 12def make_broken_ticketer():13    count = 014 15    def next_ticket():16        count += 1  # assignment makes count local here17        return count18 19    return next_ticket20 21 22def run():23    a, b = make_ticketer(), make_ticketer()24    calls = [a(), a(), a(), b()]25    try:26        make_broken_ticketer()()27        broken = "worked"28    except UnboundLocalError as e:29        broken = f"UnboundLocalError: {e}"30    return {"calls": calls, "broken": broken}

functools.wraps

A decorator replaces your function with its wrapper, so without help the decorated function reports the wrapper's __name__ and docstring. Anything that reads those attributes — log lines built from fn.__name__, help(), a web framework that names routes after their functions — then sees wrapper everywhere. @functools.wraps(fn) on the wrapper copies the name, qualified name, docstring, module and annotations across, and stores the original in __wrapped__. (A traceback still shows the frame as wrapper: it reads the name of the code object, which wraps does not touch.)

Decorators with arguments

@retry(times=3) is a call first: retry(times=3) runs and must return the actual decorator, which then receives the function. So a configurable decorator is three nested levels — factory, decorator, wrapper:

def tag(label):              # the factory: takes the arguments
    def decorate(fn):        # the decorator: takes the function
        @functools.wraps(fn)
        def wrapper(*args, **kwargs):   # replaces the function
            return f"<{label}>{fn(*args, **kwargs)}</{label}>"
        return wrapper
    return decorate

1import functools2 3 4def tag(label):5    def decorate(fn):6        @functools.wraps(fn)7        def wrapper(*args, **kwargs):8            return f"<{label}>{fn(*args, **kwargs)}</{label}>"9        return wrapper10    return decorate11 12 13def tag_no_wraps(label):14    def decorate(fn):15        def wrapper(*args, **kwargs):16            return f"<{label}>{fn(*args, **kwargs)}</{label}>"17        return wrapper18    return decorate19 20 21@tag("b")22def greet(name):23    """Say hello."""24    return f"hi {name}"25 26 27@tag_no_wraps("b")28def greet_plain(name):29    """Say hello."""30    return f"hi {name}"31 32 33def run():34    return {35        "result": greet("Ana"),36        "name_with_wraps": greet.__name__,37        "doc_with_wraps": greet.__doc__,38        "original_kept": greet.__wrapped__("Ana"),39        "name_without": greet_plain.__name__,40        "doc_without": greet_plain.__doc__,41        "code_name_with_wraps": greet.__code__.co_name,42    }

Stacking, and the decorators you already use

Stacked decorators apply bottom-up: the one nearest the def wraps the function first, and the top one wraps the result. When the function is called, the outermost wrapper runs first. functools.lru_cache (and functools.cache) is a decorator that memoises results by argument — arguments must be hashable — and property, staticmethod and classmethod are decorators too.

1import functools2 3log = []4 5 6def mark(name):7    def decorate(fn):8        log.append(f"apply {name}")9 10        @functools.wraps(fn)11        def wrapper(*args):12            log.append(f"enter {name}")13            return fn(*args)14        return wrapper15    return decorate16 17 18calls = 019 20 21@functools.lru_cache(maxsize=None)22def fib(n):23    global calls24    calls += 125    return n if n < 2 else fib(n - 1) + fib(n - 2)26 27 28def run():29    log.clear()30 31    @mark("top")32    @mark("bottom")33    def work():34        log.append("work")35 36    log.append("--- call")37    work()38    return {"log": log, "fib_30": fib(30), "fib_calls": calls,39            "cache_hits": fib.cache_info().hits}

Common mistakes

• Assigning to a captured variable without nonlocal, and getting UnboundLocalError the first time the inner function runs.
• Leaving out functools.wraps, so every decorated function reports __name__ wrapper and loses its docstring.
• Writing @retry where @retry(3) was meant, or the reverse. The function ends up passed as the times argument, or the decorator receives an integer instead of a function.
• Caching with lru_cache on a function whose result depends on anything other than its arguments, or that takes a list.

What interviewers ask

• What is a closure? A function together with the variables it captured from an enclosing scope, which outlive that scope's call.
• How do you write a decorator that takes arguments? A factory that returns the decorator; three levels, with functools.wraps on the innermost.
• In which order do stacked decorators apply? Nearest the def first at definition time; at call time the outermost wrapper runs first.