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

Sat Aug 25 02:54:15 CEST 2012

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