[issue21928] Incorrect reference to partial() in functools.wraps documentation
New submission from Dustin Oprea: 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(). ---------- assignee: docs@python components: Documentation messages: 222426 nosy: Dustin.Oprea, docs@python priority: normal severity: normal status: open title: Incorrect reference to partial() in functools.wraps documentation versions: Python 2.7, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21928> _______________________________________
Ezio Melotti added the comment: 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? ---------- nosy: +ezio.melotti, r.david.murray, rhettinger, terry.reedy status: open -> pending type: -> enhancement versions: +Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21928> _______________________________________
R. David Murray added the comment: 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: ---------- status: pending -> open _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21928> _______________________________________
Roundup Robot added the comment: New changeset 9e3c367b45a1 by Ezio Melotti in branch '3.4': #21928: clarify functools.wraps docs. http://hg.python.org/cpython/rev/9e3c367b45a1 New changeset 5a58f6e793cc by Ezio Melotti in branch 'default': #21928: merge with 3.4. http://hg.python.org/cpython/rev/5a58f6e793cc New changeset 6cbd08fbdf77 by Ezio Melotti in branch '2.7': #21928: clarify functools.wraps docs. http://hg.python.org/cpython/rev/6cbd08fbdf77 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21928> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- assignee: docs@python -> ezio.melotti resolution: -> fixed stage: -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21928> _______________________________________
participants (4)
-
Dustin Oprea -
Ezio Melotti
-
R. David Murray
-
Roundup Robot