What Are Decorators in Python?

A decorator is a function that takes another function and gives you back a new one. The @ symbol is only a short way of writing that reassignment by hand, so putting @logged above a function definition does exactly the same thing as writing logged above it and then adding func = logged(func) on the next line.

The usual shape of a decorator has three parts. The outer function receives the function that is being decorated. Inside it sits a nested function that does the real work, which means calling the original function and then adding whatever the decorator is for, such as logging, timing, or a permission check. That nested function is then returned, so it takes the place of the original in the namespace.

Two details make this pattern work in real code. The wrapper is written with *args and **kwargs so that it accepts any call signature and passes everything through to the original function, because a decorator that hard-codes the parameters only works on functions that have exactly that shape. The wrapper is also normally marked with @functools.wraps(func), which copies the name, the docstring, and the type hints of the original function onto the wrapper so that the decorated function still looks like itself.

The earlier questions in this topic covered functions and their arguments, and this answer builds on them. You will meet decorators constantly in real work. Logging and timing wrappers, caching with functools.cache, route handlers inside web frameworks, and the retry logic inside software kits are all built this way. Understanding the pattern is what lets you read any of them without being afraid of them.

The clearest way to show a decorator is to write one that changes what the function gives back.

def double(func):
    def wrapper():
        return func() * 2
    return wrapper


@double
def five():
    return 5


print(five())          # 10
print(five.__name__)   # wrapper

After the decoration happens, five is no longer the original function. It is the wrapper function. Calling five() runs the wrapper, and the wrapper calls the original five, doubles the result, and gives back 10.

The last line shows the cost of leaving out functools.wraps. The name is wrapper rather than five, because the wrapper is a brand new function object and the original name was replaced by it. The same thing happens to the docstring, to the signature that help() and inspect report, and to anything else that depends on the identity of the function.

Notice also that this decorator takes no arguments. It only works for functions that are called with no arguments, because the wrapper has no parameters of its own. A general decorator accepts *args and **kwargs and forwards them along, and that is why almost every real decorator is written that way. The next question shows what happens when the decorator also needs to keep the original name.

functools.wraps is the standard way to keep the identity of a function, and it should be on every decorator that you write.

import functools


def timed(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper


@timed
def greet(name: str) -> str:
    """Return a greeting for the given name."""
    return 'Hello, ' + name


print(greet.__name__)      # greet
print(greet.__doc__)       # Return a greeting for the given name.
print(greet('Ada'))        # Hello, Ada

Without wraps, all of those lookups would report the name of the wrapper, the docstring of the wrapper, which is None, and the qualified name of the wrapper. With wraps, the decorated function looks exactly like the original to any tool that inspects it.

There is a specific list of things that wraps copies. It copies __module__, __name__, __qualname__, __doc__, __annotations__, __dict__, and __wrapped__. The last one is worth knowing about. __wrapped__ points at the original function before it was decorated, and inspect.signature follows it, so the decorated function still reports the original list of parameters instead of the catch-all signature of the wrapper.

That is what makes a decorator written with wraps a better citizen. Documentation generators, test frameworks, debuggers, and the standard library's own inspect module all treat it as the function that it wraps. Writing your own decorators without it is the most common decorator mistake, and it is the one that an interviewer will notice straight away. The question after this one looks closely at what wraps copies and why.