[Python-ideas] inheriting docstrings and mutable docstings for classes

[Steven D'Aprano]

On 25/08/12 10:10, Mark Adam wrote:

> In any case, I found myself wanting this auto-inheritance [of docstrings]
> for easier testing with doctest.  I don't want my subclasses to mess up
> invariants in my parent classes, and if the doctests were inherited this
> would be easy to check.
>
> Just my (late) 2 cents worth after examining the current python issues list.


I have run into exactly that issue myself. But then I realised that this may
not work in practice, and in fact could be outright misleading.

The problem is that my class docstrings probably refer to the class by name:

class Spam:
     def get(self, n):
         """Get n chunks of lovely spam.

         >>> Spam().get(4)
         'Spam spam spam LOVELY SPAM!!!'
         """

class Ham(Spam):
     pass


If Ham.get inherits the docstring, I may be fooled into thinking that I've
tested Ham.get when all I've done is test Spam.get twice.

A better solution to this use-case might be a class decorator which copies
docstrings from superclasses (if they aren't explicitly set in the subclass).
The decorator could optionally apply a bunch of string transformations to
the docstrings:

@copy_docstrings({'spam': 'ham'}, case_mangling=True)
class Ham(Spam):
     pass



-- 
Steven