On Thu, Jul 16, 2009 at 9:13 PM, Jean-Paul Calderone<exar...@divmod.com> wrote:
> On Fri, 17 Jul 2009 11:01:49 +1000, Ben Finney <ben+pyt...@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.