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
--
http://mail.python.org/mailman/listinfo/python-list
