A decorator is a function that takes a function and returns a function. That is the whole idea, and once you see it as an ordinary call instead of as new syntax, the @ symbol stops being magic. What follows builds one from a single def, and then fixes the two problems that appear along the way.
The previous lesson in this module covered "Closures: Functions That Remember", and the next lesson in this module is about "Generators and the Iterator Protocol".
What is a decorator, really?
Write the decoration out in longhand and the syntax disappears. In the example below, shout is a plain function, announce is a decorator, and the line add = announce(add) is exactly what the @ symbol expands to.
def announce(func):
"""Print a message before and after calling func."""
def wrapper(*args, **kwargs):
print('calling ' + func.__name__)
result = func(*args, **kwargs)
print('returned ' + str(result))
return result
return wrapper
def add(a, b):
"""Add two numbers."""
return a + b
add = announce(add)
print(add(2, 3))
Three details do all of the work here. The inner function accepts *args and **kwargs, so the wrapper works with any signature. The result of the inner call is returned, so the decorated function still behaves like the original one. And the wrapper closes over func, which makes it a closure, and that is the subject of the previous lesson.
With the syntax written out, the decorator reads as what it really is.
def announce(func):
"""Print a message before and after calling func."""
def wrapper(*args, **kwargs):
print('calling ' + func.__name__)
result = func(*args, **kwargs)
print('returned ' + str(result))
return result
return wrapper
@announce
def add(a, b):
"""Add two numbers."""
return a + b
print(add(2, 3))
Why does functools.wraps matter?
The wrapper replaces the original function, and the replacement carries none of its identity. Its name becomes wrapper, its docstring disappears, and its signature becomes (*args, **kwargs). Any tool that inspects functions, such as your debugger, help(), a test runner, or a documentation generator, now sees the wrapper instead of your function.
from functools import wraps
def announce(func):
"""Print a message before and after calling func."""
@wraps(func)
def wrapper(*args, **kwargs):
print('calling ' + func.__name__)
result = func(*args, **kwargs)
print('returned ' + str(result))
return result
return wrapper
@announce
def add(a, b):
"""Add two numbers."""
return a + b
print(add.__name__)
print(add.__doc__)
@wraps(func) copies __name__, __doc__, __module__, __qualname__, and the signature metadata onto the wrapper. It also sets __wrapped__, so that inspect.signature reports the original signature. Without it, add.__name__ is wrapper and add.__doc__ is None.
Use @wraps on every decorator that you write, without exception. It costs one import and one line, and it is the difference between a decorator that hides your function and one that preserves it.
How do you write a decorator that takes arguments?
A decorator that is configured, such as "repeat three times", "retry five times", or "log to this logger", needs one extra layer. The outer function is called with the configuration, and it has to return the real decorator.
from functools import wraps
def repeat(times):
"""Return a decorator that runs the decorated function several times."""
def decorator(func):
@wraps(func)
def wrapper(*args, **kwargs):
result = None
for _ in range(times):
result = func(*args, **kwargs)
return result
return wrapper
return decorator
@repeat(3)
def greet(name):
"""Return a greeting."""
return 'Hello, ' + name
print(greet('Ada'))
There are three nested functions, and each one has a single job. repeat captures the configuration, decorator captures the function, and wrapper does the work. This shape, which is a factory that returns a decorator that returns a wrapper, is the pattern behind most decorator libraries, including the pytest fixtures and the Flask route decorators.
The same three-layer shape works for a decorator that changes the return value instead of the call. A cache, a retry loop, and a validator can all be written in the same way. Call the function, and then decide what to do with the result and with any exception.
Which decorators are worth knowing by heart?
Besides the ones that you write yourself, a short list covers most of what you will meet in real code.
from functools import lru_cache, wraps
from time import perf_counter
def timed(func):
"""Print how long the decorated call took."""
@wraps(func)
def wrapper(*args, **kwargs):
start = perf_counter()
result = func(*args, **kwargs)
elapsed = perf_counter() - start
print(func.__name__ + ' took ' + str(round(elapsed, 6)) + 's')
return result
return wrapper
@timed
def sum_of_squares(n):
"""Return the sum of the first n squares."""
total = 0
for number in range(n):
total += number * number
return total
@lru_cache(maxsize=128)
def square(n):
"""Return n squared, remembering the previous answers."""
return n * n
print(sum_of_squares(100000))
print(square(12), square(12))
print(square.cache_info())
functools.lru_cache is a decorator that you will use constantly, because it remembers the arguments and their results, so a repeated call returns straight away. The cache_info() output shows the hits and the misses, and that is the quickest way to tell whether a cache is worth keeping at all.
The trio from the object-oriented lessons, which are @property, @classmethod, and @staticmethod, are decorators as well, and they follow exactly this pattern. They receive a function and they return a different kind of object. @property turns a method into a computed attribute, while @classmethod and @staticmethod change the way that the method receives its arguments.
One trap catches people who write their very first decorator, and that is forgetting to return the result. If the wrapper calls the function but does not return its value, then the decorated function quietly returns None every single time. The same applies to the wrapper itself, because a decorator has to return the wrapper. If it does not, the decorated name ends up bound to None, and every later call fails with the message "NoneType is not callable".
Decorators also work on classes and on methods, but there is a subtlety with inheritance. Decorating a method means that the wrapper replaces the function on the class, so self arrives as the first positional argument inside the wrapper. That is why wrappers take *args instead of a named first parameter, because the decorator does not need to know anything about the signature that it wraps.
How do stacked decorators run?
When you stack decorators, they are applied from the bottom up, and the resulting functions run from the top down. The decorator that is closest to the function wraps it first.
from functools import wraps
def trace(label):
"""Return a decorator that prints a trace line."""
def decorator(func):
@wraps(func)
def wrapper(*args, **kwargs):
print('[' + label + '] entering')
result = func(*args, **kwargs)
print('[' + label + '] leaving')
return result
return wrapper
return decorator
@trace('outer')
@trace('inner')
def work():
"""Do some work."""
return 'done'
print(work())
The order of the output is outer entering, inner entering, inner leaving, and outer leaving. The inner decorator is applied first, so it wraps the raw function, and the outer decorator then wraps that wrapper. Every layer adds a little behaviour and passes the result along to the next layer.
Reading stacked decorators from the bottom up tells you the order in which the behaviour is nested. Reading from the top down tells you the order in which a reader meets it, which is why the top decorator should be the one that describes the outermost concern, such as authentication around a route, and not a low-level detail such as logging.
Key takeaways
- A decorator is a function that takes a function and returns a function, and that is all it is.
- Always use
@functools.wrapsso that the decorated function keeps its name, its docstring, and its signature. - A configurable decorator needs three layers, which are the factory, the decorator, and the wrapper.
- Stacking applies the decorators bottom-up and runs them top-down, and the order of the output matches that.
- Write your own decorator only after checking whether
lru_cache,property, or the standard library already does the job.
Try it yourself: Write a @log_calls decorator that prints the function name and its arguments before each call. Then add an optional prefix as an argument, with @log_calls(prefix="app"), which means that you need the three-layer version. Stack it with the @trace decorator from this page and confirm that the order of the printed lines matches the explanation above. Finally, decorate a function with @lru_cache as well and check with cache_info() that the hits counter climbs.