Override a method but inherit the docstring

[Jean-Paul Calderone]

On Fri, 17 Jul 2009 11:01:49 +1000, Ben Finney <ben+python at benfinney.id.au> wrote:
>Howdy all,
>
>The following is a common idiom::
>
>    class FooGonk(object):
>        def frobnicate(self):
>            """ Frobnicate this gonk. """
>            basic_implementation(self.wobble)
>
>    class BarGonk(FooGonk):
>        def frobnicate(self):
>            special_implementation(self.warble)
>
>The docstring for ‘FooGonk.frobnicate’ is, intentionally, perfectly
>applicable to the ‘BarGonk.frobnicate’ method also. Yet in overriding
>the method, the original docstring is not associated with it.
>
>Ideally there would be a way to specify that the docstring should be
>inherited. The best I can come up with is::
>
>    class BarGonk(FooGonk):
>        def frobnicate(self):
>            special_implementation(self.warble)
>        frobnicate.__doc__ = FooGonk.frobnicate.__doc__
>
>but that violates DRY (the association between BarGonk and FooGonk is
>being repeated), puts the docstring assignment awkwardly after the end
>of the method instead of at the beginning where docstrings normally go,
>and reads poorly besides.
>
>What is the most Pythonic, DRY-adherent, and preferably least-ugly
>approach to override a method, but have the same docstring on both
>methods?
>

How about this?

    class BarGonk(FooGonk):
        @inherit_docstring
        def frobnicate(self):
            special_implementation(self.warble)

The implementation of "inherit_docstring" is left as an exercise for the
reader (it's not utterly trivial, I admit, as "FooGonk" will not readily
be at hand, but it is still possible).

By the way, I don't think this is a particularly good idea.  Presumably
there is a reason your implementation is special.  It would probably be
better if this were reflected in the docstring somehow.  Perhaps this
idea is a better one:

    class BarGonk(FooGonk):
        @append_to_docstring
        def frobnicate(self):
            """
            This implementation takes the warble into consideration.
            """
            special_implementation(self.warble)

With the result of BarGonk.frobnicate.__doc__ being set to:


     Frobnicate this gonk.

     This implementation takes the warble into consideration.

Jean-Paul