What Does functools.wraps Fix?

A decorator replaces a function with a wrapper. Unless you say otherwise, that wrapper is a completely different function object with a different name, no docstring, and a catch-all signature, so the identity of the original function is lost. functools.wraps puts that identity back by copying the metadata of the original function onto the wrapper.

The attributes that it copies are __module__, __name__, __qualname__, __doc__, __annotations__, __dict__, and __wrapped__. The first five are the ones that you notice in everyday work. They are the module the function came from, its name, its qualified name including the class, its docstring, and its type hints. The __dict__ is copied too, so any custom attributes that you set on the function survive the decoration.

__wrapped__ is the one with a special purpose. It is a direct reference to the original function before it was decorated, and the inspect module in the standard library follows it. That is why inspect.signature on a decorated function reports the original parameters instead of the catch-all signature of the wrapper.

The real effect is on everything that reads a function's metadata, such as tracebacks, help(), documentation generators, type checkers, mocking libraries, and test frameworks that look functions up by name. A decorator without wraps makes all of those see a function called wrapper with no docstring, which is why the convention in the Python community is that every decorator uses it. The earlier questions in this topic covered how decorators work, and this answer focuses on the one line that keeps them honest.

The metadata is copied at the moment of decoration, and __wrapped__ keeps a pointer to the original function.

import functools
import inspect


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


@logged
def add(a: int, b: int = 2) -> int:
    """Add two numbers."""
    return a + b


print(add.__name__)              # add
print(add.__doc__)               # Add two numbers.
print(add.__wrapped__)           # the original function
print(inspect.signature(add))    # (a: int, b: int = 2) -> int
print(add(1))                    # 3

The signature line is the most useful of all of them. The wrapper's own signature is (*args, **kwargs), but inspect.signature follows the __wrapped__ attribute and reports the original signature instead. Any tool that looks inside a function, such as a web framework that checks a request, a documentation generator, or a mocking library, now sees the real parameters.

__wrapped__ is also what makes a decorated function keep working with tools like inspect.getsource and unittest.mock.patch, because both of them need to reach the function underneath the wrapper.

There are two things that wraps does not do. It does not change how the function behaves, so a decorator that swallows an exception or returns the wrong type will still do exactly that. And it does not wrap the return value in anything, because it copies attributes and it does not change behaviour.

Without wraps, a decorated function loses its identity. With wraps, the identity is kept.

import functools


def plain_decorator(func):
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper


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


@plain_decorator
def plain():
    """Plain docstring."""


@good_decorator
def good():
    """Good docstring."""


print(plain.__name__)      # wrapper
print(plain.__doc__)       # None
print(good.__name__)       # good
print(good.__doc__)        # Good docstring.

The plain version reports its name as wrapper and has no docstring at all, because the wrapper function has neither of those things. The good version reports the original name and the original docstring, because wraps copied them across.

This is not only a matter of appearance. The name shows up in tracebacks, so a stack trace full of wrapper lines tells you nothing about which function actually failed. The docstring shows up in help() and in generated documentation, so a library whose public functions all describe themselves as wrapper is effectively undocumented. The name is also what tools use to find a function, so tests that look functions up by name stop working altogether.

The rule to give in an interview is short. Put @functools.wraps(func) on the wrapper of every decorator that you write, with no exceptions. The only time you would leave it out is if you deliberately wanted the wrapper to be visible to the reader.