Closures and decorators

Decorators with arguments

@app.route("/deals") passes an argument to the decorator. That takes one more layer: a function that takes the arguments and returns a decorator.

import functools

def require_role(role):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(user, *args, **kwargs):
            if role not in user.get("roles", []):
                raise PermissionError(f"{user['name']} needs the {role!r} role for {func.__name__}")
            return func(user, *args, **kwargs)
        return wrapper
    return decorator

@require_role("admin")
def delete_product(user, sku):
    return f"{sku} deleted by {user['name']}"

print(delete_product({"name": "Ada", "roles": ["admin"]}, "TE-106"))
try:
    delete_product({"name": "Ben", "roles": ["staff"]}, "TE-106")
except PermissionError as e:
    print("refused:", e)

Read it from the outside in, one layer per call: require_role("admin") runs first and returns decorator; then decorator receives delete_product and returns wrapper. Three nested functions look intimidating, but each layer has one job: hold the argument, hold the function, run the check.

import functools

def retry(times):
    pass


attempts = []

@retry(3)
def fetch_prices():
    attempts.append(1)
    if len(attempts) < 3:
        raise ConnectionError("network blip")
    return {"TE-101": 200}

print(fetch_prices(), len(attempts), fetch_prices.__name__)

Stacking, and caching

Several decorators can sit on one function. They apply from the bottom up: the one nearest the def wraps the function first, and the top one wraps the result. When the function is called, they run from the top down, like layers of an onion.

@log_calls          # 2nd: wraps the checked function, so it logs even refused calls
@require_role("admin")   # 1st: wraps delete_product
def delete_product(user, sku): ...

The standard library has decorators you'll use constantly. functools.cache remembers every result by its arguments, so repeated calls are instant; functools.lru_cache(maxsize=...) keeps only the most recent ones:

import functools

@functools.cache
def ways_to_climb(steps):
    if steps <= 1:
        return 1
    return ways_to_climb(steps - 1) + ways_to_climb(steps - 2)

print(ways_to_climb(80))
print(ways_to_climb.cache_info())

Without the cache, this recursion would make about 10^16 calls; with it, 81. Caching is only safe for pure functions, whose results depend on nothing but their arguments. Never cache something that reads the clock, a file or a database.

Decorators you'll meet

Most decorators you use will come from libraries. Knowing how they work tells you what they do:

• @app.route("/deals") in Flask and @app.get("/deals") in FastAPI take arguments, so they're the three-layer kind. Their main job is to register your function in a table of URLs, then return it.
• @pytest.fixture and @pytest.mark.parametrize(...) mark functions so pytest knows how to call them.
• @property, @classmethod and @staticmethod change how a method is looked up and called.
• @functools.cache and @functools.lru_cache remember results.
• @dataclass decorates a class: it reads the class's fields and writes methods into it.

Decorators work on methods too. The wrapper's *args simply receives self as its first argument and passes it along, so @log_calls above a method needs no changes. And because a decorator only has to be something callable that returns a function, a class with a __call__ method can be one as well, which is handy when the decorator needs to keep a lot of state.

A decorator runs once, when the def is executed, which is usually at import time. That's why a route decorator can register URLs before any request arrives. It's also why a decorator that does slow work when it runs slows down every import of that module. Keep that first step light, and do the real work in the wrapper.

When a decorated function misbehaves, remember you're calling the wrapper. Its __wrapped__ attribute (added by functools.wraps) gives you the original to test on its own, without logging, caching or access checks getting in the way.

import functools
import time

def timed(clock=time.perf_counter, store=None):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            start = clock()
            try:
                return func(*args, **kwargs)
            finally:
                elapsed = clock() - start
                if store is not None:
                    store.setdefault(func.__name__, []).append(elapsed)
        return wrapper
    return decorator

timings = {}
fake_now = iter([0.0, 1.5, 10.0, 10.2])

@timed(clock=lambda: next(fake_now), store=timings)
def build_report(rows):
    return len(rows)

build_report([1, 2, 3])
build_report([])
print(timings)

@timed(store=timings)
def real_work():
    return sum(range(100_000))

real_work()
print(sorted(timings), timings["real_work"][0] > 0)