On Fri, Aug 24, 2012 at 6:54 PM, Steven D'Aprano <steve@pearwood.info> wrote:
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
Yeah, see http://bugs.python.org/issue15731. -eric