Decorators — function decorators, @, wraps: Exercises

Before we start, one picture of the machinery so every later reference has a shape to point at.

Figure — Decorators — function decorators, @, wraps

Read the picture left to right: the name f originally points at the original function (cyan box). The decorator deco builds a wrapper (amber box) that holds a reference to the original inside it, and then the name f is rebound to that wrapper. That rebinding is the entire meaning of @deco.

Level 1 — Recognition

You only need to read code and state what it becomes. No execution tricks yet.

Recall Solution L1.1

The rule from the parent note: @deco above def f means f = deco(f). So:

def greet(): return "hi"
greet = shout(greet)

What we did: applied the desugaring rule literally. Why: @ is only sugar for reassigning the name to the decorator's return value.

Worked example L1.2 — Is it a decorator?

For each, answer yes / no: could this be used as a plain @d decorator (takes one callable, returns a callable)?

def d1(f): return f
def d2(f): return 42
def d3(x): return lambda: x
def d4(f):
    def w(): return f()
    return w

Recall Solution L1.2

d1 — yes. Takes a callable, returns a callable (the same one). Legal, though it adds nothing.
d2 — no as a useful decorator: it returns 42, an int, which is not callable. @d2 def f makes f the integer 42, so f() raises TypeError.
d3 — structurally yes (takes one arg, returns a callable), but it ignores the function and always returns lambda: x. It "decorates" but destroys the original — a valid callable-in, callable-out, still legal syntactically.
d4 — yes, the canonical shape: Take, Wrap, Return. Why the distinction: "decorator" is defined by shape (callable → callable), not by usefulness.

Worked example L1.3 — Predict the name

After running, what does greet.__name__ print?

def shout(f):
    def wrapper(): return f().upper()
    return wrapper
@shout
def greet(): return "hi"
print(greet.__name__)

Recall Solution L1.3

wrapper. Why: greet now points at the inner function wrapper; no functools.wraps was used, so the original name label was not copied. This is exactly the __name__-lie problem from the parent note. Prints:

wrapper

Level 2 — Application

Now you write decorators and compute outputs.

Recall Solution L2.1

add(3,4) desugars to double(add)(3,4). Inner call f(3,4) = 7, doubled → 14.

Why *a, **k: so the wrapper forwards (3,4) unchanged to the original — see args and kwargs unpacking.

Worked example L2.2 — Build

announce Write a decorator announce so that this:

@announce
def area(w, h): return w * h
print(area(2, 5))

prints first running area and then 10, and area(2,5) still returns 10.

Recall Solution L2.2

from functools import wraps
def announce(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        print(f"running {func.__name__}")
        result = func(*args, **kwargs)   # capture the value
        return result                    # return it so caller still gets 10
    return wrapper

Output:

running area
10

Why result = ...; return result: if we drop the return, area(2,5) becomes None. Why @wraps: keeps area.__name__ == "area".

Worked example L2.3 — Count calls with a closure

def counter(f):
    count = 0
    def w(*a, **k):
        nonlocal count
        count += 1
        print(f"call #{count}")
        return f(*a, **k)
    return w
@counter
def ping(): return "pong"
ping(); ping(); ping()

What are the three printed lines?

Recall Solution L2.3

call #1
call #2
call #3

Why it remembers: count is a free variable captured by the inner function's closure; nonlocal lets the wrapper rebind it (without nonlocal, count += 1 would raise UnboundLocalError).

Level 3 — Analysis

Trace multi-layer behaviour and explain WHY, not just WHAT.

Worked example L3.1 — Stacking order

def tag(name):
    def deco(f):
        def w(*a, **k):
            return f"<{name}>{f(*a, **k)}</{name}>"
        return w
    return deco
@tag("b")
@tag("i")
def text(): return "hi"
print(text())

What prints, and why that nesting order?

Recall Solution L3.1

Stacking desugars bottom-up: text = tag("b")(tag("i")(text)).

Innermost tag("i") wraps text → produces hi.
Then tag("b") wraps that → produces  + hi + .

<b><i>hi</i></b>

Why bottom-up: @tag("b") sits above the whole result of @tag("i") def text, so tag("i") is applied first and tag("b") last — the outer tag ends up outermost.

Worked example L3.2 — Parametrised layers

How many function-calls happen, and what does each layer capture, when Python evaluates:

@repeat(3)
def hi(): print("hi")

with repeat the three-layer factory from the parent note.

Recall Solution L3.2

Two calls happen at decoration time:

repeat(3) runs → Layer 1 captures n = 3, returns decorator.
decorator(hi) runs → Layer 2 captures func = hi, returns wrapper.
Layer 3 (wrapper) captures nothing new; it uses n and func at call time. So hi = repeat(3)(hi). When you later call hi(), the loop for _ in range(n) runs the original 3 times. Why three layers: each () you write needs its own function to receive its arguments — n from @repeat(3), func from the @, and *args from the eventual call.

Worked example L3.3 — The metadata leak

Given

def deco(f):
    def w(*a, **k): return f(*a, **k)
    return w
@deco
def foo(): "the docstring"

What are foo.__name__ and foo.__doc__? How does adding @wraps(f) change both?

Recall Solution L3.3

Without wraps:

foo.__name__ → 'w'
foo.__doc__ → None The name now points at the inner w, whose own docstring is empty. With @wraps(f) on w (from functools — wraps, lru_cache, partial):
foo.__name__ → 'foo'
foo.__doc__ → 'the docstring' Why: wraps copies __name__, __doc__, __module__, __qualname__, and sets __wrapped__ back to the original.

Level 4 — Synthesis

Combine ideas into a working tool you design yourself.

Worked example L4.1 —

retry(times) factory Write a decorator retry(times) that re-runs the function if it raises, up to times attempts; if all fail, re-raise the last error. It should return the result on the first success. Then predict the printed lines for:

attempts = []
@retry(3)
def flaky():
    attempts.append(1)
    if len(attempts) < 3:
        raise ValueError("nope")
    return "ok"
print(flaky(), len(attempts))

Recall Solution L4.1

from functools import wraps
def retry(times):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            last = None
            for _ in range(times):
                try:
                    return func(*args, **kwargs)   # success exits immediately
                except Exception as e:
                    last = e
            raise last                              # all attempts failed
        return wrapper
    return decorator

Trace: attempt 1 → raises (len=1), attempt 2 → raises (len=2), attempt 3 → len==3, returns "ok". So:

ok 3

Why the factory shape: @retry(3) first calls retry(3), so retry must return a decorator — three layers, as in Higher-order functions.

Worked example L4.2 — Tiny memoiser

Write memo that caches results by their positional-args tuple in a dict, so repeated calls skip recomputation. Then determine how many times slow actually executes its body:

calls = []
@memo
def slow(n):
    calls.append(n)
    return n * n
slow(2); slow(3); slow(2); slow(2); slow(3)
print(len(calls))

Recall Solution L4.2

from functools import wraps
def memo(func):
    cache = {}                     # free variable, lives in the closure
    @wraps(func)
    def wrapper(*args):
        if args not in cache:
            cache[args] = func(*args)   # compute only once per key
        return cache[args]
    return wrapper

Keys computed: (2,) once, (3,) once; the repeats hit the cache. So the body runs 2 times → len(calls) == 2.

Why a closure dict: cache persists across calls because the wrapper holds it — the real functools.lru_cache is this idea, industrial-strength.

Level 5 — Mastery

Edge cases, degenerate inputs, and subtle interactions.

Recall Solution L5.1

range(0) is empty, so the for loop body never runs — func is never called. last stays None, and raise last becomes raise None, which Python turns into TypeError: exceptions must derive from BaseException. Fix / lesson: guard degenerate parameters: times = max(1, times), or handle last is None explicitly. Zero-iteration loops are a classic degenerate case you must cover.

Worked example L5.2 — Stacking

wraps-aware vs not

from functools import wraps
def A(f):
    @wraps(f)
    def w(*a, **k): return f(*a, **k)
    return w
def B(f):
    def w(*a, **k): return f(*a, **k)   # no wraps
    return w
@A
@B
def job(): "does a job"
print(job.__name__)

What is job.__name__? Explain the chain.

Recall Solution L5.2

Bottom-up: job = A(B(job)).

B(job) (no wraps) makes a wrapper whose __name__ is 'w'.
A(...) uses @wraps(f) where f is B's wrapper, so it copies that wrapper's already-broken __name__ == 'w'. Result:

Lesson: wraps only copies from its immediate target. One un-wrapsed layer anywhere in the stack corrupts the name for everyone above it. Fix: put @wraps on every layer.

Worked example L5.3 — Decorating a method (self)

from functools import wraps
def trace(f):
    @wraps(f)
    def w(*a, **k):
        print("called")
        return f(*a, **k)
    return w
class Robot:
    @trace
    def speak(self, msg): return msg.upper()
print(Robot().speak("hi"))

Does self cause trouble? What prints?

Recall Solution L5.3

No trouble — because w(*a, **k) forwards everything, self simply arrives as the first positional in a. So f(self, "hi") runs normally.

called
HI

Why *args saves us: we never named self in the wrapper, so it needs no special handling; it is just another forwarded argument. This is why *args, **kwargs (see args and kwargs unpacking) makes a decorator universal across plain functions and methods. For decorators that need to know they're on a class, see Class decorators and property.

Recall Final self-check

Answer without looking: What does @d above def f do to the name f? ::: Rebinds it: f = d(f). Read @a over @b over def f — which applies first? ::: b (nearest the def); result is a(b(f)). Why does retry(0) blow up? ::: The range(0) loop never runs, so raise last becomes raise None → TypeError. Which layer of @retry(3) captures n? ::: The outermost factory layer retry(n). What corrupts __name__ in a stack? ::: Any single layer missing @wraps; upper layers copy the broken name.

Connections

Parent: Decorators
Closures and free variables
First-class functions
Higher-order functions
functools — wraps, lru_cache, partial
args and kwargs unpacking
Class decorators and property