Issue 21928: Incorrect reference to partial() in functools.wraps documentation (original) (raw)

functools.wraps docs say "This is a convenience function for invoking partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated) as a function decorator when defining a wrapper function." The referenced function should be update_wrapper(), not partial().

The docstring is correct, as this is how wraps is implemented (see Lib/functools.py#l73). partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated) will return a partial version of update_wrapper() where only the wrapper argument is missing. The missing argument is the function decorated with wraps().

For example, this code:

def my_decorator(f): @wraps(f) def wrapper(*args, **kwds): return f(*args, **kwds) return wrapper

is equivalent to:

def my_decorator(f): def wrapper(*args, **kwds): return f(*args, **kwds) wrapper = wraps(f)(wrapper) return wrapper

Here wraps(f) creates a partial version of update_wrapper, with only the "wrapped" argument (i.e. f) set. When the partial object returned by wrap(f) gets called, the missing "wrapper" argument is received, thus making wraps(f)(wrapper) equivalent to:

def my_decorator(f): def wrapper(*args, **kwds): return f(*args, **kwds) wrapper = update_wrapper(wrapper, f) return wrapper

That said, I agree that the sentence you quoted is not too clear/intuitive, but the following example is quite clear, so I'm not sure it's worth to removing/rephrasing the first part.

Maybe it could say something like "This is a convenience function for invoking update_wrapper() (by using partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated)) as a function decorator when defining a wrapper function." instead?

I would rewrite it as:

This is a convenience function for invoking update_wrapper() as a function decorator when defining a wrapper function. It is equivalent to partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated). For example: