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

[Eric Snow]

On Fri, Aug 24, 2012 at 6:54 PM, Steven D'Aprano <steve at 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