Repository navigation
Share code for getdoc() between inspect and pydoc #132686
Description
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.
Activity
thomashammett commentedon Apr 18, 2025
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.
pythongh-132686: Add parameters inherit_class_doc and fallback_to_cla…
serhiy-storchaka commentedon Apr 18, 2025
#132691 adds new options for getdoc().
@ncoghlan, @vadmium, @vedgar, @Carreau, @gvanrossum, what are your thoughts about these options?
serhiy-storchaka commentedon Apr 18, 2025
Sorry, @thomashammett, the work was already almost done when I created this issue.
thomashammett commentedon Apr 18, 2025
No worries! Thanks.
vedgar commentedon Apr 20, 2025
I'm not quite sure why I was mentioned here... is there a particular reason you want my opinion?
serhiy-storchaka commentedon Apr 20, 2025
Because you were one of the opponents of unconditional change in #84438.
#84438 (comment)
#84438 (comment)
vedgar commentedon Apr 20, 2025
gh-132686: Add parameters inherit_class_doc and fallback_to_class_doc…
pythongh-132686: Add parameters inherit_class_doc and fallback_to_cla…