[issue21928] Incorrect reference to partial() in functools.wraps documentation

[Dustin Oprea]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21928] Incorrect reference to partial() in functools.wraps documentation

[Ezio Melotti]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21928] Incorrect reference to partial() in functools.wraps documentation

[R. David Murray]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21928] Incorrect reference to partial() in functools.wraps documentation

[Roundup Robot]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21928] Incorrect reference to partial() in functools.wraps documentation

[Ezio Melotti]

Changes by Ezio Melotti :


--
assignee: docs@python -> ezio.melotti
resolution:  -> fixed
stage:  -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com