Enhance inspect.getdoc to follow inheritance chains

[ncoghlan]

BPO	15582
Nosy	@ncoghlan, @merwok, @PCManticore, @ericsnowcurrently, @berkerpeksag, @vadmium, @serhiy-storchaka, @1st1
Files	inspect_getdoc.patch issue15582.patch: Add documentation. issue15582_1.patch: Ups, remove unintented change. inspect_getdoc_inherited.patch getdoc-news.patch getdoc-news.v2.patch

^{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 = 'https://github.com/serhiy-storchaka'
closed_at = <Date 2015-07-30.15:12:21.015>
created_at = <Date 2012-08-08.02:52:13.350>
labels = ['type-feature', 'library']
title = 'Enhance inspect.getdoc to follow inheritance chains'
updated_at = <Date 2015-07-30.15:12:20.988>
user = 'https://github.com/ncoghlan'

bugs.python.org fields:

activity = <Date 2015-07-30.15:12:20.988>
actor = 'berker.peksag'
assignee = 'serhiy.storchaka'
closed = True
closed_date = <Date 2015-07-30.15:12:21.015>
closer = 'berker.peksag'
components = ['Library (Lib)']
creation = <Date 2012-08-08.02:52:13.350>
creator = 'ncoghlan'
dependencies = []
files = ['33118', '34445', '34733', '38414', '39379', '40062']
hgrepos = []
issue_num = 15582
keywords = ['patch']
message_count = 26.0
messages = ['167654', '167909', '206045', '215593', '232322', '232323', '234171', '237691', '237694', '237716', '237760', '240027', '240041', '240057', '240058', '240349', '241489', '241520', '241608', '241726', '241753', '242005', '243248', '247645', '247680', '247681']
nosy_count = 9.0
nosy_names = ['ncoghlan', 'eric.araujo', 'Claudiu.Popa', 'python-dev', 'eric.snow', 'berker.peksag', 'martin.panter', 'serhiy.storchaka', 'yselivanov']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue15582'
versions = ['Python 3.5']

[ncoghlan]

Currently, if you override a method from a base class, the docstring is not inherited, even if it remains accurate.

This issue proposes an enhancement to inspect.getdoc() that allows the docstring to be retrieved from the inheritance hierarchy in the case where it is not overridden in the subclass by providing an explicit docstring.

Specifically, in the case where obj.__doc__ is None, and either the first parameter is a bound method, or a class object is passed in as the second parameter, inspect.getdoc will search the MRO based on obj.__name__ until it finds an attribute with a non-None __doc__ value.

(In Python 2, this could have been automatic for both bound and unbound methods. Unfortunately, there are no unbound methods in Python 3, so the second parameter is needed to handle the unbound method case)

[ericsnowcurrently]

I have just the thing for this, but haven't had a chance to put a patch together. I might be able to get to it in the next week if Dave "bitey" Beazley isn't too much of a distraction. :)

[PCManticore]

Hello!

Here's a patch. Currently it lacks doc updates, but if the solution is okay, then I could provide them.

[PCManticore]

Yury, Nick, how is my latest patch?

[1st1]

@Claudiu, you should also add this test and make sure that it passes:

   class Parent:
      __doc__ = 'some documentation'

   class Child(Parent):
      __doc__ = None

assert getdoc(Child) is None

In other words -- we use __doc__ defined in parent classes only when there was no __doc__ in children's __dict__s.

[PCManticore]

Alright, I'll update my patch later this week.

[PCManticore]

Yury, regarding your last message, is it actually possible to have a subclass which doesn't have a __doc__ attribute in its __dict__, except using slots? __doc__ seems to be set to None every time if it's not specified, so I don't know how could I detect the case where the client sets '__doc__ = None' himself.

The following example might be more explanatory:

>>> class A:
...    __doc__ = "a"
...
>>> inspect.getdoc(A)
'a'
>>> inspect.getdoc(A())
'a'
>>> class B(A):
...   __doc__ = None
...
>>> vars(B)
mappingproxy({'__doc__': None, '__module__': '__main__'})
>>> B.__dict__
mappingproxy({'__doc__': None, '__module__': '__main__'})
>>> class C(A): pass
...
>>> vars(C)
mappingproxy({'__doc__': None, '__module__': '__main__'})
>>>

Nevertheless, my patch ignores this case, since it operates only on methods. When trying to do inspect.getdoc(Child, parent=Parent), it will try to look for an attribute 'Child' in the mro of Parent and thus it will return None, since this doesn't exist (this can actually be a problem, if that attribute actually exist).

[serhiy-storchaka]

The patch adds support only for unbound methods and requires additional parameter for this. It is not what should be done in this issue at all.

I'm interested in this issue so I'll write a patch. It should be easier to write it myself than describe it.

[PCManticore]

The patch adds support only for unbound methods and requires additional parameter for this.

Just curios, which part works only for unbound methods?

It is not what should be done in this issue at all.
It should be easier to write it myself than describe it.

Well, some hints for the right way to do this would have been appreciated.

[serhiy-storchaka]

Here is a patch that supports classes, bound and unbound methods, class methods, properties, method and class descriptors.

[ncoghlan]

Serhiy's patch looks good to me.

I'd completely missed that __qualname__ could be used to avoid needing a second argument even when handling objects other than bound methods. That's very cool, and I can see why you figured it was easier to just write the patch than explain what you had in mind.

[python-dev]

New changeset 157b7055bb9d by Serhiy Storchaka in branch 'default':
Issue bpo-15582: inspect.getdoc() now follows inheritance chains.
https://hg.python.org/cpython/rev/157b7055bb9d