In the previous lesson the signatures of warehouse.py got their annotations, and while writing them a new need appeared: Ana wants to know how long close_till() takes with a year's worth of sales, and she wants every call to sell() audited in papyrus.log. You could open each function and add the stopwatch and the logging inside... but that mixes business logic with plumbing, and you'd have to repeat it in every function. Decorators solve this: they wrap a function with extra behavior without touching its code. You've been using them since module 5 (@property, @dataclass) without knowing how they work inside; today we take them apart piece by piece.

1. Functions as first-class objects
2. Closures: functions that remember
3. A decorator from scratch, without syntactic sugar
4. The @ syntax
5. *args and **kwargs: wrapping any signature
6. functools.wraps: keeping the identity
7. Decorators for Papyrus: @timed and @log_call
8. Decorators with arguments: @retry(times=3)
9. The decorators you already knew, in a new light
10. Don't over-decorate

Everything that follows rests on a fact you already brushed against in M3 with sorted(key=...) and lambdas: in Python, a function is an object like any other. It can be assigned, passed as an argument and returned:

The crucial distinction is greet (the function object) versus greet() (the result of calling it). The whole decorator mechanism revolves around that difference.

Functions can also be defined and returned inside other functions:

Notice something surprising in the previous example: when make_greeting("Papyrus") finishes, its local variable shop should disappear... and yet greet_papyrus keeps using it. An inner function that captures variables from the function that created it is called a closure. Step by step:

1. You call make_greeting("Papyrus") → shop = "Papyrus" is created.
2. greeting is defined and mentions shop — Python notes that it needs it.
3. make_greeting returns greeting and finishes, but shop is not destroyed: it travels tucked away inside the returned function.
4. Every later call to greet_papyrus(...) finds shop intact.

Closures are the memory of decorators: that's how the wrapper function "remembers" which function it wraps.

A decorator is simply a function that takes a function and returns another one that wraps it. Without @, by hand:

The key line is open_shop = announce(open_shop): the name open_shop stops pointing to the original function and starts pointing to the wrapper, which keeps the original in its closure. Nobody touched the body of open_shop; it just got a layer wrapped around it.

Because that reassignment pattern is so common, Python gives it syntactic sugar:

@announce right above the def means exactly open_shop = announce(open_shop) executed after defining the function. There's no more magic than that: if you understand the reassignment, you understand the @.

The wrapper() above takes no arguments, so it can't wrap sell(catalog, title, units). The solution is the M3 duo *args/**kwargs, which finds its star role here — collecting whatever comes in and passing it along untouched:

With this, the decorator is universal: it works for functions with zero, three or twenty parameters, positional or keyword. It's the standard signature of every wrapper.

There's a subtle side effect. After decorating, sell.__name__ is no longer "sell" but "wrapper", and its docstring — the contract we took such care of in 08-01 — vanishes. For the logger.exception() calls from M7, which record function names, this is a real problem. functools.wraps copies the original's identity onto the wrapper:

Rule with no exceptions: every decorator carries @functools.wraps.

After running the close, this shows up in data/papyrus.log with the M7 format:

The try/finally guarantees the measurement even if close_till raises: the same cleanup discipline from 07-02.

Ana wants to be able to reconstruct what was sold and what failed. Instead of putting logging inside sell(), we wrap it:

A sale of Hamlet x2 leaves ok: sell → 20.7; an attempt to sell 9 copies of The Odyssey with 4 in stock leaves the full InsufficientStockError traceback. And pay attention to the bare raise: the decorator observes and re-raises. Catching and silencing here would violate the three-rings rule of 07-04 — the decision about the exception belongs to the counter or to the boundary, not to the wrapper.

What if saving the catalog fails sporadically (network drive, antivirus) and you want to retry? We'd like to write @retry(times=3). But that means retry(times=3) is called first and must return a decorator: it's a decorator factory. Three levels:

Read the chain: @retry(times=3) → retry(times=3) runs → returns decorator → decorator(save_catalog) → returns wrapper → save_catalog = wrapper. Each level is a closure: wrapper remembers function, times and pause all at once. Note the choice of except OSError: you retry what's transient; a TypeError is a bug and should blow up on the first try (07-04).

None of them was magic: they're all "function (or class) in, wrapped or transformed version out".

A warning before you decorate the whole shop: every decorator adds a layer to dig through when debugging. If sell carries @timed, @log_call and @retry, an error traceback shows three wrappers before reaching the real code, and the stacking order starts to matter (they apply bottom-up). Practical criterion: decorate when the behavior is cross-cutting and repeated (logging, timing, retries); don't decorate for single-function business logic — that goes inside the function, where it can be seen.

• Decorating with one set of parentheses too many or too few: @timed() fails if timed is a plain decorator, and @retry (without parentheses) fails if it's a factory. Rule: factory → always with parentheses, even when using the defaults (@retry()).
• Forgetting return function(...) in the wrapper: the decorated function silently starts returning None. If the decorated sell stops returning the amount, check the wrapper before the function.
• Forgetting @functools.wraps: the 07-05 logs start saying wrapper instead of sell and debugging becomes a maze.
• Swallowing exceptions in the decorator: an except Exception: pass in a wrapper is the "silence" that 07-04 banned, now in disguise. Observe, log with logger.exception, and re-raise.
• Tip: write the decorator without @ first, with the explicit reassignment, until the flow feels obvious. The @ comes on its own.
• Tip: wrappers benefit from the type hints of 08-01 — def wrapper(*args, **kwargs) -> ... can be annotated precisely with typing.Callable; keep it as optional reading, you don't need it yet.

1. Write @members_only, a decorator for functions whose first argument is a member code ("LUIS-001", "MARTA-002", "PAU-003"). If the code isn't in the set of valid members, it must raise InvalidMemberError(code) without calling the function; if it's valid, it calls it normally. Don't forget functools.wraps.
2. Without using the @ syntax, decorate close_till with the lesson's timed via explicit reassignment, and explain in a comment why close_till.__name__ is still "close_till".
3. Turn @timed into a factory @timed(threshold=1.0) that only writes to the log if the function took more than threshold seconds (to avoid filling papyrus.log with fast closes).

1. import functools
   from errors import InvalidMemberError
   
   VALID_MEMBERS: set[str] = {"LUIS-001", "MARTA-002", "PAU-003"}
   
   def members_only(function):
       @functools.wraps(function)
       def wrapper(code, *args, **kwargs):
           if code not in VALID_MEMBERS:
               raise InvalidMemberError(code)   # the 07-03 guard clause, now reusable
           return function(code, *args, **kwargs)
       return wrapper
   

   The wrapper names code explicitly (it needs it to validate) and forwards the rest with *args, **kwargs.

2. close_till = timed(close_till)
   # __name__ is still "close_till" because the wrapper carries
   # @functools.wraps(function), which copies __name__ and the docstring
   # of the original function onto the wrapper before returning it.
   

3. def timed(threshold: float = 0.0):
       def decorator(function):
           @functools.wraps(function)
           def wrapper(*args, **kwargs):
               start = time.perf_counter()
               try:
                   return function(*args, **kwargs)
               finally:
                   duration = time.perf_counter() - start
                   if duration > threshold:
                       logger.info("%s took %.3f s", function.__name__, duration)
           return wrapper
       return decorator
   
   @timed(threshold=1.0)
   def close_till(sales_path): ...
   

   threshold travels in the closure through all three levels. Common mistake here: leaving @timed without parentheses — it's a factory now and must always be called.

There's nothing magical about a decorator: functions that are objects, closures that remember, and a reassignment that the @ abbreviates. With @timed, @log_call and @retry(times=3), Papyrus adds timing, auditing and resilience without cluttering sell() or close_till() — and along the way, @property and @dataclass stopped being incantations. Timing the close is precisely what raises the next question: close_till() reads the entire sales.csv to add it up, and the file grows every day. Do you really need to load a year of sales into memory to sum today's? No: rows can be produced and consumed on demand, one at a time. That's the territory of generators and yield, the next lesson.