how to inherit docstrings?

[Eric Snow]

On Thu, Jun 9, 2011 at 7:12 PM, Carl Banks <pavlovevidence at gmail.com> wrote:
> On Thursday, June 9, 2011 3:27:36 PM UTC-7, Gregory Ewing wrote:
>> IMO, it shouldn't be necessary to explicitly copy docstrings
>> around like this in the first place. Either it should happen
>> automatically, or help() should be smart enough to look up
>> the inheritance hierarchy when given a method that doesn't
>> have a docstring of its own.
>
> Presumably, the reason you are overriding a method in a subclass is to change its behavior; I'd expect an inherited docstring to be inaccurate more often than not.  So I'd be -1 on automatically inheriting them.
>

When I write ABCs to capture an interface, I usually put the
documentation in the docstrings there.  Then when I implement I want
to inherit the docstrings.  Implicit docstring inheritance for
abstract base classes would meet my needs.  I'm just not clear on the
impact this would have for the other use cases of docstrings.

> However, I'd be +1 easily on a little help from the language to explicitly request to inherit the docstring.
>

Yeah, that's more or less how I feel too.  But what would fill that
role?  This comes back to my original question.  A method at
definition time does not know its class, nor would the decorator, so
they won't know where from to inherit the docstring.

Like I said originally, you can approach this a number of ways, but
the one that appeals to me most (plain function decorators) doesn't
work without some explicit help, which I would rather avoid.  Implicit
help would be nice, but how to do it?

The most direct form, presenting the class to the execution frame of
the body somehow, seems risky and strange.  It's sort of like the
function object being inserted into the locals when it is called.
However, the class object would have to be created before the body
gets exec'ed, rather than as now, where <metaclass>.__new__ is called
after...  Changing that would require changes to type.__new__ and how
it's used.

Perhaps a good approach would be to have a special decorator in the
stdlib that type.__new__ would recognize, like this:

def inherits_docstring(f):
    if f.__doc__ is None:
        f.__doc__ = NotImplemented
    return f

# actually in typeobject.c, or something
def type.__new__(meta, name, bases, namespace):
    # do the normal stuff here
    # now handle docstring inheritance
    for name, obj in namespace.items():
        if hasattr(obj, "__doc__") and obj.__doc__ is NotImplemented:
            # inherit the docstring...

But then I look at that and wonder if it's too special-cased to be
worth the trouble.  I can just use a metaclass or class decorator that
does that, and override builtin.__build__class__ to force its use
everywhere; or use one base class for all my classes that uses the
metaclass.  But it would be nice to have implicit support.

-eric


>
> Carl Banks
> --
> http://mail.python.org/mailman/listinfo/python-list
>