Docstrings are not inherited

[davfsa]

Describe the bug
Docstrings are not inherited. Considering this is not any special case and it defined by the Python standard, I thought it would be appropriate to open the issue here, but the end goal is for mkdocstrings.

To Reproduce
Steps to reproduce the behavior:

class A:
    def foo(self):
        """This is a docstring"""

class B(A):
    def foo(self):
        # Inherited docstring defined in A.foo

>>> from griffe.loader import GriffeLoader
>>> loader = GriffeLoader()
>>> module = loader.load_module("module")
>>> print(module.classes["A"].functions["foo"].docstring)
This is a docstring
>>> print(module.classes["B"].functions["foo"].docstring)
None

Expected behavior
Docstrings are inherited.

System:

• griffe version: 0.22.0
• Python version: 3.10.4
• OS: Linux

Additional context
N/A

[machow]

It seems like griffe's behavior matches python's behavior

class A:
    def foo(self):
        """This is a docstring"""

class B(A):
    def foo(self):
        # Inherited docstring defined in A.foo

        ...

# returns NoneType
type(B.foo.__doc__)

[davfsa]

It seems like griffe's behavior matches python's behavior

class A:
    def foo(self):
        """This is a docstring"""

class B(A):
    def foo(self):
        # Inherited docstring defined in A.foo

        ...

# returns NoneType
type(B.foo.__doc__)

That is correct, but griffe seems to be more like inspect, which does take into account inherited docstrings when using inspect.getdoc()

As I initially stated, the end goal is mkdocstrings, so I can open an issue there instead if needed.

cc @pawamoy

[pawamoy]

Hello @davfsa, sorry for the late reply and thanks for the report.
Thanks @machow as well for helping out.

Currently Griffe does not support any kind of inheritance. Since different users wish for different things, there is some work to do to specify exactly what we want to provide, and how it should be configurable.

Just wanted to let you know that I don't forget about issues. My time is limited but I'll eventually get to it!

[gab832]

Hi @pawamoy, I'm Gerard from Cloudblue. We are also interested on the inherited methods. How is it going? Is there any plan to do it? Thanks for all the work you are doing!

[pawamoy]

Hi Gerard, I've started working on it, it shouldn't take long :)

[gab832]

That's a really good news. Thank you again @pawamoy !!

[pawamoy]

So, we now have inheritance support, so this issue can be tackled.

I'm imagining a Griffe extension that would somehow post-process the whole tree, looking for class members (methods, attributes) that do not have a docstring, and checking in the parent classes (using MRO) for equally named members with docstrings. We would assign the first found docstring to the base members, without duplicating it (we need to maintain the docstring's parent, needed to parse annotations correctly, in the right scope).

What do you think?

[davfsa]

Sorry for taking so long to get back to you!

I would personally implement it in a way that when griffe gets the docstring of a specific object, if it were to be not set, it would traverse the inheritance members upwards in the search for that docstring, returning it if found. I feel like having an extension later re-parse the whole tree might be too expensive to do after the fact, instead of just in the first pass.

[pawamoy]

Thanks for your feedback.

It's not possible to do it in the first pass anyway since we need to be able to compute the inherited members, and for this the whole tree must have finished loading. Maybe you meant to do this dynamically, when trying to access the docstring? It would mean that we have to store the configuration option somewhere in the object hierarchy to know if we should try and get docstrings from parent classes.

[davfsa]

Maybe you meant to do this dynamically, when trying to access the docstring?

Yeah, that is what I meant 😅

---

Also, this may be slighly different to what you would like, but I found this comment while looking at the source code:

griffe/src/griffe/agents/inspector.py

Lines 149 to 151 in c1476d0

	# we avoid `inspect.getdoc` to avoid getting
	# the `__doc__` attribute from a parent class,
	# but we still want to clean the doc

would using inspect.getdoc be an easier "solution" to this?

It is possible I am also entirely misunderstanding the reason for the comment

[pawamoy]

That's a good remark. This comment is in the "inspector", which loads data from objects in memory (dynamic analysis). Using getdoc there wouldn't solve the case for static analysis (the "visitor"). On the contrary, solving the case for static analysis will also fix it for dynamic analysis 😄 That's because the solution would operate at an abstraction layer above: in Griffe data structures.

The main thing we have to consider when thinking about a solution for this, is how to integrate it well with Object.has_docstring and Object.has_docstrings, which are used by mkdocstrings depending on the show_if_no_docstring configuation option.

To be honest I'm fine with fetching inherited docstrings dynamically. The one thing that is a bit annoying is that, as said above, we have to store the user choice somewhere in the object hierarchy to be able to do that:

@property
def docstring(self) -> Docstring | None:
    if USER_CONFIGURED_INHERIT_DOCSTRINGS:  # where to store that?
        self._docstring = self.try_and_get_docstring_from_parent_classes()
    return self._docstring

Or maybe we could add an inherited_docstring property, but that will complicate things further in has_docstring and has_docstrings, as well as in the Python handler templates.

[pawamoy]

We also have to think about making this configurable per-object in mkdocstrings 🤔 And if that's even something users want (like, "inherit docstrings but not for this object").