Add follow_wrapped=True option to help()

[samwyse]

BPO	29940
Nosy	@rhettinger, @taleinat, @eamanu
PRs	bpo-29940: Add follow_wrapped option to help() #12915 bpo-29940: Add follow_wrapped option to help() #22390

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2020-09-26.06:54:20.261>
created_at = <Date 2017-03-29.15:41:05.003>
labels = ['3.8', 'type-feature', 'library']
title = 'Add follow_wrapped=True option to help()'
updated_at = <Date 2020-09-26.06:54:20.260>
user = 'https://bugs.python.org/samwyse'

bugs.python.org fields:

activity = <Date 2020-09-26.06:54:20.260>
actor = 'taleinat'
assignee = 'none'
closed = True
closed_date = <Date 2020-09-26.06:54:20.261>
closer = 'taleinat'
components = ['Library (Lib)']
creation = <Date 2017-03-29.15:41:05.003>
creator = 'samwyse'
dependencies = []
files = []
hgrepos = []
issue_num = 29940
keywords = ['patch']
message_count = 4.0
messages = ['290782', '377503', '377513', '377518']
nosy_count = 4.0
nosy_names = ['rhettinger', 'taleinat', 'samwyse', 'eamanu']
pr_nums = ['12915', '22390']
priority = 'normal'
resolution = 'out of date'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue29940'
versions = ['Python 3.8']

[samwyse]

The help(obj) function uses the type of obj to create its result. This is less than helpful when requesting help on a wrapped object. Since 3.5, inspect.signature() and inspect.from_callable() have a follow_wrapped option to get around similar issues. Adding the option to help() would prevent surprising behavior while still allowing current behavior to be used when needed. See http://stackoverflow.com/a/17705456/603136 for more.

[taleinat]

To clarify, to my understanding the issue here is that when using a class as a decorator, and copying the wrapped function's __doc__ to self.__doc__ in __init__, help() will pick up the wrapper class's __doc__ rather than the instance's __doc__.

For example:

class Deco:
    "A decorator."
    def __init__(self, func):
        functools.update_wrapper(self, func)
    def __call__(self, *args, **kwargs):
        pass

@Deco
def double(n):
    "A function."
    return n * 2

help(double) will show "A decorator." rather than "A function." despite the use of functools.update_wrapper().

[eamanu]

Hi @taleinat,

Seems tha the wrapped func already has the __doc__ (in this case) copied.

following your example:

>>> double
<test.Deco object at 0x7fe8d1fd5b20>
>>> double.__doc__
'A function'

so help(double) will print correctly the double doc.

[taleinat]

The issue was not that __doc__ was not copied, but that help() would use the class's __doc__ when called on an instance, even if that instance had its own __doc__.

See the StackOverflow question for another example.

You will not see this issue with the latest master branch, because it has already been resolved by PR #63678, as described and discussed in bpo-40257.

Closing as "out of date".