Share code for getdoc() between inspect and pydoc

[serhiy-storchaka]

Currently, inspect and pydoc use similar, but slightly different complex code to retrieve a doc string for object (class, function, method, etc). This is a consequence of two issues: bpo-15582 (#59787) and bpo-40257 (#84438).

In #59787, inheriting docstrings from parent class was added. It usually works fine for overridden methods, but for classes it is often wrong. If the parent class docstring says that it is an abstract class, a base class or a generic implementation class, showing this for a subclass is wrong. It is worse than not showing a docstring at all (like it was before #59787). So #84438 reverted this particular change. It fixed also other issue -- pydoc now shows a docstring not only for classes and function, but for arbitrary objects if they have docstring. This allows to show docstring for typing.Any and other pseudo-types. But there were complains against these changes, so they were reverted for inspect.getdoc(). But taht behavior is wrong for pydoc, so a modified version of inspect.getdoc() was copied in pydoc.

The problem is that that code is pretty complex. And any time we change it (for example #131116), we need to change in two places. It is easy to forgot to synchronize the code or introduce a bug. Also, the third-party code that use getdoc() may need the behavior of the pydoc version, which is not public.

The implementation should be shared. We may add options to control the behavior, and the default behavior may change in future. If there is a way to get the old behavior, there would be less complains.

Linked PRs

• gh-132686: Add parameters inherit_class_doc and fallback_to_class_doc for inspect.getdoc() #132691

[thomashammett]

I'd like to work on this issue and submit a PR to fix it. Is anyone already working on this, or may I take it? Thank you.

[serhiy-storchaka]

#132691 adds new options for getdoc().

@ncoghlan, @vadmium, @vedgar, @Carreau, @gvanrossum, what are your thoughts about these options?

[serhiy-storchaka]

Sorry, @thomashammett, the work was already almost done when I created this issue.

[thomashammett]

No worries! Thanks.

[vedgar]

#132691 adds new options for getdoc().

@ncoghlan, @vadmium, @vedgar, @Carreau, @gvanrossum, what are your thoughts about these options?

I'm not quite sure why I was mentioned here... is there a particular reason you want my opinion?

[serhiy-storchaka]

Because you were one of the opponents of unconditional change in #84438.
#84438 (comment)
#84438 (comment)

[vedgar]

But if I understood correctly, the default behavior of help now remains the same, right? That's the whole thing I wanted to preserve. ~V. ned, 20. tra 2025. 11:18 Serhiy Storchaka ***@***.***> je napisao:

…

Because you were one of the opponents of unconditional change in #84438 <#84438>. #84438 (comment) <#84438 (comment)> #84438 (comment) <#84438 (comment)> — Reply to this email directly, view it on GitHub <#132686 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACGTVAUDXZJ6QCTOLVNCNYL22NQ7VAVCNFSM6AAAAAB3NAQMBKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDQMJXGA4DAMZSGM> . You are receiving this because you were mentioned.Message ID: ***@***.***> *serhiy-storchaka* left a comment (python/cpython#132686) <#132686 (comment)> Because you were one of the opponents of unconditional change in #84438 <#84438>. #84438 (comment) <#84438 (comment)> #84438 (comment) <#84438 (comment)> — Reply to this email directly, view it on GitHub <#132686 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACGTVAUDXZJ6QCTOLVNCNYL22NQ7VAVCNFSM6AAAAAB3NAQMBKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDQMJXGA4DAMZSGM> . You are receiving this because you were mentioned.Message ID: ***@***.***>