Appearance
3.13.5 — Decorators In Depth
The payments team wants every call to the card gateway timed and logged. There are forty functions that call the gateway. You could paste the same five lines of timing code into all forty, and then fix the same bug forty times next month. Or you could write the timing code once and attach it to each function with one line: @timed. That line is a decorator. Decorators look like special syntax, but they are built entirely from two things you already know from 3.13.4: functions are objects, and closures remember variables. This page builds every kind of decorator by hand, then opens up the special decorators in the standard library, so that @app.get("/orders") in FastAPI reads as ordinary Python.
1. What the @ symbol really does
A decorator is a function that takes a function and returns a function, usually a new one that wraps the original. The @ line is only a shortcut. These two pieces of code do exactly the same thing.
python
def charge_card(order_id, amount):
...
charge_card = timed(charge_card) # (1) the long waypython
@timed # (2) the shortcut
def charge_card(order_id, amount):
...(1)Define the function, pass it totimed, and re-bind the namecharge_cardto whatevertimedreturns.(2)The@timedline means exactly that. Python creates the function object, callstimedwith it, and binds the result to the name.
That is the entire feature. Everything else on this page is a consequence of it.
Building the first decorator
Here is timed, written out in full.
python
import time
def timed(func): # (1)
def wrapper(*args, **kwargs): # (2)
start = time.perf_counter()
result = func(*args, **kwargs) # (3)
elapsed_ms = (time.perf_counter() - start) * 1000
print(f"{func.__name__} took {elapsed_ms:.0f} ms")
return result # (4)
return wrapper # (5)
@timed
def charge_card(order_id, amount):
"""Charge the customer's card."""
time.sleep(0.12) # pretend to call the gateway
return f"charged {amount} for {order_id}"
print(charge_card("ORD-7", 499))text
charge_card took 120 ms
charged 499 for ORD-7(1)timedreceives the original function asfunc.(2)It defines a new inner function.*args, **kwargsaccepts any arguments, so this one wrapper works for every function, whatever its signature.(3)The wrapper calls the original, forwarding every argument unchanged.funcis a closure variable. The wrapper remembers it in a cell, exactly like the counter in 3.13.4.(4)It returns the original's result, so callers see no difference.(5)timedreturns the wrapper, and that is what the namecharge_cardnow points to.
Figure 1 shows the names and objects after the @timed line has run.
Every caller who writes charge_card(...) now runs the wrapper first. The original is still there, reachable only through the wrapper's closure. That is why decorators are such a good fit for cross-cutting concerns. These are jobs like timing, logging, retries, caching and permission checks, which many unrelated functions need and which have nothing to do with what each function is for.
When decorators run
The decorator itself runs once, when the def statement runs, which is usually at import time. The wrapper runs on every call. Two print statements make the difference visible, and also show the order of stacked decorators.
python
def bold(func):
print("applying bold") # (1)
def wrapper():
return "<b>" + func() + "</b>"
return wrapper
def italic(func):
print("applying italic")
def wrapper():
return "<i>" + func() + "</i>"
return wrapper
@bold
@italic
def greeting():
return "Thanks for your order"
print(greeting()) # (2)text
applying italic
applying bold
<b><i>Thanks for your order</i></b>(1)These prints happen while the module loads, beforegreetingis ever called.(2)Only this line runs the wrappers.
Stacked decorators are applied from the bottom up. The line @bold @italic def greeting means greeting = bold(italic(greeting)). So italic wraps first and sits closest to the function, and bold wraps the result. When you call the function, the outermost wrapper runs first. Think of it as wrapping a parcel: the first layer of paper you put on is the last one the customer tears off.
This order matters in real code. Put @retry outside @timed and you log each attempt separately. Put it inside and you log the total time across all attempts. Put an authentication check outside a cache, never inside, or one user's cached answer could be served to another user.
2. functools.wraps: keeping the function's identity
Our first timed has a hidden problem. Ask the decorated function its name.
python
print(charge_card.__name__, charge_card.__doc__)text
wrapper NoneThe name charge_card now points to wrapper, so the function reports the wrapper's name and the wrapper's missing docstring. Logs, error tracebacks, documentation tools and debuggers all show wrapper for every decorated function, which is useless. And frameworks that inspect a function's signature, such as FastAPI, see (*args, **kwargs) instead of the real parameters.
The fix is one line, the decorator functools.wraps.
python
import functools
import inspect
def timed(func):
@functools.wraps(func) # (1)
def wrapper(*args, **kwargs):
return func(*args, **kwargs)
return wrapper
@timed
def charge_card(order_id, amount):
"""Charge the customer's card."""
print(charge_card.__name__, "|", charge_card.__doc__) # (2)
print(inspect.signature(charge_card)) # (3)
print(charge_card.__wrapped__) # (4)text
charge_card | Charge the customer's card.
(order_id, amount)
<function charge_card at 0x000001A3C846D430>(1)wraps(func)is itself a decorator, applied towrapper.(2)The wrapper now reports the original's name and docstring.(3)inspect.signaturereports the original's real parameters.(4)wrapsalso stores the original function as__wrapped__. That is howinspect.signaturefound the real parameters: it follows__wrapped__down to the original.
What wraps actually does is short. It copies a fixed list of attributes from the original onto the wrapper: __module__, __name__, __qualname__, __doc__, the type-hint attributes, and __type_params__. It merges the original's __dict__ into the wrapper's. Then it sets __wrapped__. You can see the lists in functools.WRAPPER_ASSIGNMENTS and functools.WRAPPER_UPDATES.
Rule: every decorator that returns a wrapper function should use @functools.wraps. Skipping it is the most common decorator bug in code reviews.
3. Decorators that take arguments
Now the team wants retries, but different functions need different retry counts: @retry(times=3). Notice that retry(times=3) is a call. It runs first, and whatever it returns is then used as the decorator. So retry must be a function that returns a decorator. That gives three layers of functions.
python
import functools
import time
def retry(times, delay=0.0): # (1)
def decorator(func): # (2)
@functools.wraps(func)
def wrapper(*args, **kwargs): # (3)
for attempt in range(1, times + 1):
try:
return func(*args, **kwargs)
except ConnectionError as error: # (4)
print(f"attempt {attempt} failed: {error}")
if attempt == times:
raise # (5)
time.sleep(delay)
return wrapper
return decorator
calls = 0
@retry(times=3)
def fetch_exchange_rate(currency):
global calls
calls += 1
if calls < 3:
raise ConnectionError("gateway timeout") # fail twice, then succeed
return 83.2
print(fetch_exchange_rate("USD"))text
attempt 1 failed: gateway timeout
attempt 2 failed: gateway timeout
83.2(1)The outer layer receives the settings,timesanddelay, and returns a decorator.(2)The middle layer is an ordinary decorator. It receives the function.(3)The inner layer is the wrapper that runs on each call. It can seetimes,delayandfunc, all through closures.(4)OnlyConnectionErroris retried. Retrying every exception would also retry bugs such as aTypeError, which will fail the same way every time.(5)A bareraisere-raises the current exception with its original traceback, so the caller sees the real failure after the last attempt.
Read @retry(times=3) in two steps: decorator = retry(times=3), then fetch_exchange_rate = decorator(fetch_exchange_rate).
One warning before you retry in production. Only retry operations that are safe to repeat. An operation that is safe to repeat, with the same result each time, is called idempotent. Fetching an exchange rate is idempotent. Charging a card is not, unless the payment gateway supports an idempotency key, a unique ID sent with each request so that a repeated charge is recognised and ignored. Part 10 covers this properly.
4. Class-based decorators
A decorator only has to be something you can call with a function. A class is callable: calling it creates an instance. And an instance is callable too, if its class defines __call__. That gives a second way to write decorators, which is natural when the decorator needs to keep state you want to read later.
python
import functools
class CountCalls:
def __init__(self, func): # (1)
functools.update_wrapper(self, func) # (2)
self.func = func
self.calls = 0
def __call__(self, *args, **kwargs): # (3)
self.calls += 1
return self.func(*args, **kwargs)
@CountCalls
def send_receipt(email):
return f"sent to {email}"
send_receipt("asha@example.com")
send_receipt("ravi@example.com")
print(send_receipt.calls, send_receipt.__name__) # (4)text
2 send_receipt(1)@CountCallsmeanssend_receipt = CountCalls(send_receipt), so__init__receives the function.(2)update_wrapperis what@wrapscalls internally. Here we call it directly, because we are wrapping an object, not defining a wrapper function.(3)Callingsend_receipt(...)now calls the instance, which runs__call__.(4)The count is a plain attribute, easy to read.
There is one catch. A class-based decorator applied to a method breaks, because an instance of CountCalls does not turn into a bound method the way a function does. The fix needs the descriptor protocol from 3.13.7. For that reason, function-based decorators are the safer default.
5. Decorating methods
A function-based decorator works on methods with no extra effort. The first positional argument is simply self, and the wrapper forwards it like any other argument.
python
import functools
def log_calls(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
print(f"calling {func.__qualname__} args={args[1:]}") # (1)
return func(*args, **kwargs)
return wrapper
class Cart:
def __init__(self):
self.items = []
@log_calls
def add(self, sku, qty=1):
self.items.append((sku, qty))
return len(self.items)
cart = Cart()
print(cart.add("mug", 2))text
calling Cart.add args=('mug', 2)
1(1)args[0]is the cart itself, so we skip it when logging.__qualname__, the qualified name, includes the class, which makes logs clearer than__name__.
6. Async functions need async wrappers
FastAPI services are full of async def functions (3.13.15). A plain wrapper around an async function returns the coroutine object without awaiting it. The timer would then measure almost nothing, and any try/except in the wrapper would never see the real errors. A decorator that must support both kinds checks which kind it received.
python
import asyncio
import functools
import inspect
import time
def timed(func):
if inspect.iscoroutinefunction(func): # (1)
@functools.wraps(func)
async def async_wrapper(*args, **kwargs):
start = time.perf_counter()
try:
return await func(*args, **kwargs) # (2)
finally:
print(f"{func.__name__} took {(time.perf_counter() - start) * 1000:.0f} ms")
return async_wrapper
@functools.wraps(func)
def wrapper(*args, **kwargs):
start = time.perf_counter()
try:
return func(*args, **kwargs)
finally: # (3)
print(f"{func.__name__} took {(time.perf_counter() - start) * 1000:.0f} ms")
return wrapper
@timed
async def fetch_stock(sku):
await asyncio.sleep(0.05)
return 12
print(asyncio.run(fetch_stock("mug")))text
fetch_stock took 51 ms
12(1)inspect.iscoroutinefunctiontells you whetherfuncwas written withasync def.(2)The async wrapper awaits the original, so the timer covers the real work.(3)finallyruns whether the function returns or raises, so failed calls are timed too.
7. Registration decorators: how @app.get works
Not every decorator wraps. Some just record the function somewhere and return it unchanged. This is how web frameworks connect URLs to your code. Here is a complete tiny router.
python
ROUTES = {}
def route(path): # (1)
def register(func):
ROUTES[path] = func # (2)
return func # (3)
return register
@route("/orders")
def list_orders():
return ["ORD-1", "ORD-2"]
@route("/health")
def health():
return "ok"
print(list(ROUTES))
print(ROUTES["/orders"]()) # (4)
print(list_orders()) # (5)text
['/orders', '/health']
['ORD-1', 'ORD-2']
['ORD-1', 'ORD-2'](1)A decorator with an argument, so three layers as in section 3. Here only two layers are needed, because nothing wraps.(2)At import time, the function is stored in the routing table under its path.(3)The function itself is returned unchanged, so you can still call it directly.(4)When a request for/ordersarrives, the server looks up the table and calls the function.(5)The original name still works normally.
FastAPI's @app.get("/orders") is this idea plus much more. When it registers your function, it also reads the function's signature and type hints with inspect, the same way section 2 did. From those it builds a plan for turning each incoming request into arguments. Chapter 3.14 opens that machinery up. Flask's @app.route, pytest's plugins and Click's command-line commands all use the same registration pattern.
8. Class decorators
A decorator can also receive a class, because a class is an object too. It can modify the class and return it, or return something new. This one adds a readable __repr__ to any class.
python
def add_repr(cls):
def __repr__(self):
fields = ", ".join(f"{name}={value!r}" for name, value in vars(self).items())
return f"{cls.__name__}({fields})"
cls.__repr__ = __repr__ # (1)
return cls # (2)
@add_repr
class Shipment:
def __init__(self, order_id, carrier):
self.order_id = order_id
self.carrier = carrier
print(Shipment("ORD-7", "dhl"))text
Shipment(order_id='ORD-7', carrier='dhl')(1)The decorator attaches a new method to the class.(2)It returns the same class, now improved.
The standard library's @dataclass is a much bigger version of exactly this. It reads the class's annotated fields and writes __init__, __repr__, __eq__ and more, then attaches them. 3.13.8 shows what it generates.
9. The special decorators in the standard library
Python ships with decorators that solve common problems. Here are the ones built on what this page covered. The rest each have a home page later in this chapter.
@functools.lru_cache and @functools.cache
A cache stores results so repeated work is skipped. lru_cache stores the results of a function, keyed by its arguments. "LRU" stands for least recently used: when the cache is full, the entry that was used longest ago is thrown away.
python
import functools
@functools.lru_cache(maxsize=128)
def shipping_quote(pincode, weight_kg):
print(f" computing quote for {pincode}") # (1)
return 40 + weight_kg * 12
print(shipping_quote("560001", 2))
print(shipping_quote("560001", 2)) # (2)
print(shipping_quote("110001", 1))
print(shipping_quote.cache_info()) # (3)text
computing quote for 560001
64
64
computing quote for 110001
52
CacheInfo(hits=1, misses=2, maxsize=128, currsize=2)(1)The print shows when the real work happens.(2)The second identical call returns instantly from the cache. No print.(3)cache_info()reports hits, misses and size, which helps when tuningmaxsize.
How does it work behind the scenes? The wrapper, written in C for speed, builds a key from the arguments and looks it up in a dict. That is why every argument must be hashable. Calling shipping_quote("560001", [2]) raises TypeError: unhashable type: 'list'. To know which entry was used longest ago, it also keeps the entries in a doubly linked list, where each entry points to the one before and the one after. On every hit, the entry is moved to the front. When the cache is full, the entry at the back is removed. Both steps are O(1).
@functools.cache, added in 3.9, is lru_cache(maxsize=None): unlimited, with no eviction. It is perfect for recursive problems such as Fibonacci or the dynamic-programming problems in Part 4.
python
import functools
@functools.cache
def fib(n):
return n if n < 2 else fib(n - 1) + fib(n - 2)
print(fib(90))text
2880067194370816120Without the cache, fib(90) would make more calls than there are atoms in a mountain. With it, each value is computed once.
Two production warnings. First, an unlimited cache on a function called with ever-changing arguments, such as user IDs, is a memory leak: memory that keeps growing and is never freed. Always set maxsize for those. Second, putting @lru_cache on a method stores self in every cache key. The cache then keeps every instance alive forever, even after the rest of the program has dropped it. Linters such as Ruff flag this as rule B019.
@functools.cached_property
This caches a computed attribute on one instance. It runs the method once, on first access, and stores the answer in the instance's own __dict__.
python
import functools
class Product:
def __init__(self, price):
self.price = price
@functools.cached_property
def price_with_tax(self):
print(" computing tax")
return round(self.price * 1.18, 2)
product = Product(100)
print(product.price_with_tax)
print(product.price_with_tax) # (1)
print(vars(product)) # (2)text
computing tax
118.0
118.0
{'price': 100, 'price_with_tax': 118.0}(1)The second access does not recompute.(2)The answer was stored as a normal instance attribute. Attribute lookup now finds it in the instance first and never calls the method again. 3.13.7 explains exactly why that works.
Unlike lru_cache on a method, this does not leak. The value lives on the instance and disappears with it. The catch: if price changes later, the cached value is now wrong. Use it only for values that depend on data that does not change.
@functools.singledispatch
This turns one function into several, chosen by the type of the first argument. It is a clean replacement for a long chain of if isinstance(...) checks.
python
from decimal import Decimal
from functools import singledispatch
@singledispatch
def format_amount(value): # (1)
raise TypeError(f"cannot format {type(value).__name__}")
@format_amount.register
def _(value: int): # (2)
return f"₹{value:,}"
@format_amount.register
def _(value: Decimal):
return f"₹{value:,.2f}"
@format_amount.register(float) # (3)
def _(value):
return f"₹{value:,.2f} (approx)"
print(format_amount(1500000), format_amount(Decimal("1999.5")), format_amount(12.5))text
₹1,500,000 ₹1,999.50 ₹12.50 (approx)(1)The base function handles any type with no registered version.(2)registerreads the type hint on the first parameter to decide which type this version handles. The name_is a convention meaning "the name does not matter".(3)You can also pass the type explicitly.
Behind the scenes, format_amount.registry is a dict from type to function. On each call, it looks up the argument's type, walking up the class's parents if needed, so a subclass of int uses the int version. The lookup result is cached per type. For methods there is functools.singledispatchmethod, which dispatches on the first argument after self.
@functools.total_ordering
Defining all six comparison methods (<, <=, >, >=, ==, !=) by hand is tedious. Define __eq__ and one ordering method, and this class decorator writes the other three ordering methods for you. (!= already comes free from __eq__.)
python
from functools import total_ordering
@total_ordering
class Money:
def __init__(self, paise):
self.paise = paise
def __eq__(self, other):
return self.paise == other.paise
def __lt__(self, other):
return self.paise < other.paise
print(Money(500) >= Money(300), Money(100) > Money(300), Money(5) <= Money(5))text
True False TrueIt derives the missing ones from the two you gave. For example, a >= b becomes not a < b. The generated methods are a little slower than hand-written ones, which only matters in very hot code. A dataclass with order=True (3.13.8) is often an even simpler choice.
Where the other special decorators are explained
Some built-in decorators only make sense once you know the machinery they use. Each one has a home later in this chapter.
| Decorator | What it does | Explained in |
|---|---|---|
@property | method read like an attribute | 3.13.6 |
@classmethod, @staticmethod | methods without a normal self | 3.13.6 |
@abc.abstractmethod | must be overridden | 3.13.6 |
| How all three work inside | descriptors | 3.13.7 |
@dataclasses.dataclass | writes __init__ and friends | 3.13.8 |
@contextlib.contextmanager | generator becomes a with block | 3.13.9 |
@typing.overload, @typing.override | hints for type checkers | 3.13.12 |
@app.get, @app.middleware | FastAPI registration | Chapter 3.14 |
10. Typing a decorator properly
A type checker such as mypy needs to know that @timed returns a function with the same parameters as the one it received. Python 3.12's generics syntax expresses that directly. 3.13.12 explains the pieces. Here is the finished pattern to copy.
python
import functools
import time
from collections.abc import Callable
def timed[**P, R](func: Callable[P, R]) -> Callable[P, R]: # (1)
@functools.wraps(func)
def wrapper(*args: P.args, **kwargs: P.kwargs) -> R: # (2)
start = time.perf_counter()
try:
return func(*args, **kwargs)
finally:
print(f"{func.__name__} took {(time.perf_counter() - start) * 1000:.0f} ms")
return wrapper
@timed
def apply_coupon(total: float, code: str) -> float:
return total * 0.9 if code == "SAVE10" else total
print(apply_coupon(500.0, "SAVE10"))text
apply_coupon took 0 ms
450.0(1)**Pis a ParamSpec, a placeholder for a whole parameter list.Rstands for the return type. Read the line as: "given a function taking parametersPand returningR, I return a function taking the samePand returning the sameR".(2)P.argsandP.kwargstie the wrapper's*argsand**kwargsto that same parameter list.
With this, an editor still autocompletes apply_coupon(total=..., code=...) and flags apply_coupon("500") as an error, even though the name now points to the wrapper.
What the interviewer will push on
"What does @decorator do, exactly?" They want the desugaring: f = decorator(f), run once at definition time. The tell of understanding is mentioning that it is ordinary function application, so any callable that accepts a function works, including a class.
"Write a decorator that takes arguments." Three layers: settings, then function, then call. Use @functools.wraps. Strong candidates explain why there are three layers: @retry(3) calls retry(3) first, and the result must itself be a decorator.
"Why use functools.wraps?" Without it, the decorated function reports the wrapper's name, docstring and signature, which breaks logs, debugging, documentation and frameworks that inspect signatures. Mention __wrapped__ and that inspect.signature follows it.
"In what order are stacked decorators applied?" Bottom-up when decorating, so the decorator nearest the def wraps first. Top-down when called, so the top wrapper runs first. Give a real consequence, such as an auth check needing to sit outside a cache.
"How does lru_cache work, and when is it dangerous?" A dict keyed by the arguments plus a doubly linked list for recency, so arguments must be hashable. The dangers are unbounded growth with maxsize=None on high-variety inputs, and keeping instances alive when used on methods.
Something to volunteer that nobody asks for: decorating an async def with a plain synchronous wrapper silently breaks timing and error handling, because the wrapper only receives an un-awaited coroutine. Check inspect.iscoroutinefunction and return an async wrapper. This is a real bug in FastAPI codebases, and naming it shows production experience.
Recall
- A decorator is a callable that takes a function and returns a replacement.
@dabovedef fmeansf = d(f), run once at definition time. The wrapper runs on every call. - The wrapper takes
*args, **kwargs, calls the original through a closure, and returns its result. Use@functools.wraps(func)to copy the name, docstring and hints and to set__wrapped__. - Stacked decorators wrap bottom-up and run top-down.
- A decorator with arguments has three layers: settings → decorator → wrapper. Retry only idempotent operations.
- A class with
__call__can be a decorator, and is handy for state. Async functions need an async wrapper that awaits. - Registration decorators store the function and return it unchanged. That is how
@app.getand@routework. Class decorators such as@dataclassmodify and return a class. lru_cacheis a dict plus a doubly linked list. Its arguments must be hashable, and on methods it keeps instances alive.cachehas no limit.cached_propertystores the result on the instance.singledispatchchooses by the first argument's type.total_orderingfills in comparisons.
Self-test: Rewrite @a @b def f without the @ symbol. What breaks if you forget wraps? Why does @retry(times=3) need three nested functions? Why does @lru_cache on a method keep objects alive? What does a registration decorator return?
Quiz Bank
FoundationalWhen does the code inside a decorator run, and when does the code inside its wrapper run?
The decorator function runs once, when the decorated def statement executes. For a module-level function, that is import time. It receives the function and returns the replacement. The wrapper's body runs every time the decorated function is called. That is why a decorator can do one-time work, such as registering a route or validating configuration, separately from per-call work, such as timing or logging.
AppliedA teammate writes @timed on an async FastAPI endpoint and every request logs 0 ms. What is wrong?
timed has a normal synchronous wrapper. Calling an async def function does not run its body. It only creates a coroutine object. The wrapper measures the time to create that object, which is almost zero, and returns the un-awaited coroutine. The framework then awaits it later, outside the timer. Exceptions are also raised outside the wrapper's try. The fix is to detect inspect.iscoroutinefunction(func) and return an async def wrapper that does return await func(*args, **kwargs) inside the timing code.
InterviewImplement a decorator that caches results for a limited time, for example 60 seconds.
python
import functools
import time
def ttl_cache(seconds):
def decorator(func):
store = {}
@functools.wraps(func)
def wrapper(*args):
now = time.monotonic()
hit = store.get(args)
if hit and now - hit[1] < seconds:
return hit[0]
value = func(*args)
store[args] = (value, now)
return value
return wrapper
return decoratorIt needs three layers because it takes a setting. The cache dict lives in the middle layer's closure, so each decorated function gets its own. It uses time.monotonic, which never jumps backwards when the system clock is changed. The key is the argument tuple, so arguments must be hashable. A production version would also limit the size, or evict expired entries, to avoid growing without limit, and would use a lock if called from several threads.
StaffYour team wants a @require_role('admin') decorator on FastAPI endpoints. What are the pitfalls, and what would you recommend instead?
A hand-written decorator has three pitfalls. It must use functools.wraps, because FastAPI reads the signature to build request parsing, and a *args, **kwargs wrapper would hide every parameter. It must be async-aware for async def endpoints. And it has no clean way to get the current user, because the request is not one of the endpoint's parameters unless you add it. FastAPI's own answer is dependency injection: a Depends(require_role("admin")) dependency that receives the authenticated user from another dependency and raises a 403 error if the role is missing. It composes with other dependencies, appears in the generated API documentation, and can be swapped per environment. 3.14.4 builds it. So use decorators for cross-cutting concerns that do not need request data, and dependencies for anything that does.
Next: decorators changed functions. 3.13.6 turns to classes: what the class statement really runs, why self is written out, and the double-underscore methods that let your objects work with +, len(), for and with.