how to inherit docstrings?

[Steven D'Aprano]

On Fri, 10 Jun 2011 14:46:06 -0700, Carl Banks wrote:

> On Friday, June 10, 2011 2:51:20 AM UTC-7, Steven D'Aprano wrote:
>> On Thu, 09 Jun 2011 20:36:53 -0700, Carl Banks wrote:
>> > Put it this way: if Python doesn't automatically inherit docstrings,
>> > the worst that can happen is missing information.  If Python does
>> > inherit docstrings, it can lead to incorrect information.
>> 
>> This is no different from inheriting any other attribute. If your class
>> inherits "attribute", you might get an invalid value unless you take
>> steps to ensure it is a valid value. This failure mode doesn't cause us
>> to prohibit inheritance of attributes.
> 
> Ridiculous.  The docstring is an attribute of the function, not the
> class, which makes it very different from any other attribute.  

I don't know about you, but I'm talking about inheritance of both class 
and method docstrings.


> Consider this:
> 
> 
> class A(object):
>     foo = SomeClass()
> 
> 
> class B(A):
>     foo = SomeOtherUnrelatedClass()
> 
> 
> Would you have B.foo "inherit" all the attributes of A.foo that it
> doesn't define itself?

If A.foo and B.foo are *unrelated*, they probably don't belong in 
*related* classes. But putting that aside, if they truly are unrelated, 
then no, of course you wouldn't inherit attributes of A.foo in B.foo, 
including the docstring. That would be a stupid thing to do.

But why do you assume they are unrelated? Nobody is suggesting that (say) 
str.len should inherit its doc string from dict.update. That would be 
ridiculous, but not as ridiculous as assuming that's what we want to 
happen!

If the classes, or methods, are related, chances are good that the 
docstrings need to be related too. Possibly even identical. If they need 
to be identical, then this proposal gives a way of enforcing that 
identity without needing to keep two docstrings in sync manually.

Carl, I'm not exactly sure what your opposition is about here. Others 
have already given real-world use cases for where inheriting docstrings 
would be useful and valuable. Do you think that they are wrong? If so, 
you should explain why their use-case is invalid and what solution they 
should use.

If you fear that such docstring inheritance will become the default, 
leading to a flood of inappropriate documentation, then I think we all 
agree that this would be a bad thing.

But we can already "inherit" docstrings, in a manner of speaking, via an 
explicit name binding step, and that hasn't lead to inappropriate 
documentation:

def blarg1(*args):
    """Blarg the input and return a wibble."""
    # implementation #1

def blarg2(*args):
    # implementation #2

blag2.__doc__ = blag1.__doc__

# or perhaps blag1.__doc__.replace("wibble", "frob")


When you need to keep the docstrings of blag1 and blag2 in sync, it may 
be better to "inherit" them rather than keep two independent strings that 
need to be manually edited in sync.

functools.wraps() already does this. This proposal merely extends that 
same idea to classes and methods via inheritance instead of explicit name 
binding. Provided that such "inheritance" requires a deliberate choice by 
the caller (a decorator, a metaclass, some other syntax), where's the 
harm?



-- 
Steven