Title: inspect.getdoc() should append parent class method docs when encountering a local one line docstring
Type: enhancement Stage: needs patch
Components: Library (Lib) Versions: Python 3.11
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: gregory.p.smith, steven.daprano
Priority: normal Keywords:

Created on 2022-01-11 21:39 by gregory.p.smith, last changed 2022-01-12 01:01 by gregory.p.smith.

Messages (3)
msg410335 - (view) Author: Gregory P. Smith (gregory.p.smith) * (Python committer) Date: 2022-01-11 21:39
Today `inspect.getdoc()` is quite simple. If a method has any docstring, it returns it.

There is one idiom where this is not very useful to our users.  A """See base class.""" docstring on a method.

Rather than having to repeat the canonical base class documentation in all methods or argue with tooling about not having a docstring in this common scenario, a single line docstring being used as a hint to just bring in the parent's docstring would be more helpful to the user.

Today's inspect.getdoc() could would turn from:

into something like:

    if doc is None or (isinstance(doc, str) and '\n' not in doc.strip()):
              parent_doc = _finddoc(object)
              if doc is None:
                  doc = parent_doc
              elif isinstance(parent_doc, str):
                  doc = f'{doc}\nParent class MRO doc:\n{parent_doc}'
          except (AttributeError, TypeError):
              return doc

Why not just tell people to omit docstrings when they want parent docs?  Because not all coding styles and linter tooling allows for this as they aim to enforce that documentation _is_ written.  Source analysis tooling and IDEs may not have a whole transitive dependency view of where the base classes even come from and are thus incapable of reliably analyzing whether a parent MRO method even exists or has a docstring.  This allows for trivial one line docstrings in that situation while still providing better information to the help() user.

This would add value to when using help(typical_subclass_of_abstract_thing.method) in notebooks.
msg410338 - (view) Author: Steven D'Aprano (steven.daprano) * (Python committer) Date: 2022-01-11 22:10
Many docstrings are only 1 line without being "See base class." And many docstrings are multiple lines while also referring the reader to see the parent class for further details. So this DWIM heuristic to guess whether or not to display a parent class docstring will have a lot of both false positives and false negatives.

The false negatives just revert to the status quo, but the false positives will be annoying.

I am leery of DWIM code. The reader should be capable of recognising that sort of message and calling up help for that class, so I think the benefit here is minimal and the failures common.

But if we do go ahead with this, I have a style issue.

At the moment, getdoc shadows `object`, for no good purpose. (I'm fine with shadowing builtins if there is a good reason.) This is a minor issue that is not worth fixing on its own, but if you do end up touching getdoc to implement this, could you please remove the unnecessary shadowing? If we can call the function "get *doc*" we can call the parameter *obj* :-)
msg410373 - (view) Author: Gregory P. Smith (gregory.p.smith) * (Python committer) Date: 2022-01-12 01:01
From the context of help(typical_subclass_of_abstract_thing.method), the user isn't told what the base classes are or which one might have documentation.  So it could become an exercise in frustration.

and LOL yes the parameter name is silly but that's a separate module wide cleanup that could be done - inspect is full of public APIs that shadow object as a parameter name.  it is often quite old code.
Date User Action Args
2022-01-12 01:01:26gregory.p.smithsetmessages: + msg410373
2022-01-11 22:10:12steven.dapranosetnosy: + steven.daprano
messages: + msg410338
2022-01-11 21:39:13gregory.p.smithcreate