Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #7335 > unrolled thread

Re: how to inherit docstrings?

Back to article view | Back to comp.lang.python

Contents

  Re: how to inherit docstrings? Carl Banks <pavlovevidence@gmail.com> - 2011-06-09 18:12 -0700
    Re: how to inherit docstrings? Ben Finney <ben+python@benfinney.id.au> - 2011-06-10 11:42 +1000
    Re: how to inherit docstrings? Eric Snow <ericsnowcurrently@gmail.com> - 2011-06-09 20:37 -0600
    Re: how to inherit docstrings? Terry Reedy <tjreedy@udel.edu> - 2011-06-09 23:59 -0400
      Re: how to inherit docstrings? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2011-06-10 09:48 +0000
    Re: how to inherit docstrings? Eric Snow <ericsnowcurrently@gmail.com> - 2011-06-09 22:41 -0600
    Re: how to inherit docstrings? Gregory Ewing <greg.ewing@canterbury.ac.nz> - 2011-06-10 19:16 +1200

#7335 — Re: how to inherit docstrings?

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.

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


Carl Banks

[toc] | [next] | [standalone]

#7338

Carl Banks <pavlovevidence@gmail.com> writes:

> 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.

In which case the onus is on the programmer implementing different
behaviour to also override the docstring.

-- 
 \         “When we pray to God we must be seeking nothing — nothing.” |
  `\                                          —Saint Francis of Assisi |
_o__)                                                                  |
Ben Finney

[toc] | [prev] | [next] | [standalone]

#7341

On Thu, Jun 9, 2011 at 7:12 PM, Carl Banks <pavlovevidence@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
>

[toc] | [prev] | [next] | [standalone]

#7346

On 6/9/2011 9:12 PM, Carl Banks wrote:

> 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.
>
> However, I'd be +1 easily on a little help from the language to explicitly request to inherit the docstring.

An empty docstring "" could be interpreted as 'ditto' ;-)
It would be useless otherwise.

-- 
Terry Jan Reedy

[toc] | [prev] | [next] | [standalone]

#7369

On Thu, 09 Jun 2011 23:59:08 -0400, Terry Reedy wrote:

> On 6/9/2011 9:12 PM, Carl Banks wrote:
> 
>> 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.
>>
>> However, I'd be +1 easily on a little help from the language to
>> explicitly request to inherit the docstring.
> 
> An empty docstring "" could be interpreted as 'ditto' ;-) It would be
> useless otherwise.

+1

Better than an decorator!



-- 
Steven

[toc] | [prev] | [next] | [standalone]

#7348

On Thu, Jun 9, 2011 at 9:59 PM, Terry Reedy <tjreedy@udel.edu> wrote:
> On 6/9/2011 9:12 PM, Carl Banks wrote:
>
>> 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.
>>
>> However, I'd be +1 easily on a little help from the language to explicitly
>> request to inherit the docstring.
>
> An empty docstring "" could be interpreted as 'ditto' ;-)
> It would be useless otherwise.
>

I kind of like that.  The only catch is for cases out there where
someone used an empty string.  Then it would change the behavior,
maybe.  But how uncommon that is, not sure.  I would guess pretty
uncommon.

Whole implicitly inherit idea would require the empty docstring to say
don't do it.  With your idea you easily, clearly, and explicitly
indicate that you want the inheritance activated.  That would work for
me.

-eric

> --
> Terry Jan Reedy
>
> --
> http://mail.python.org/mailman/listinfo/python-list
>

[toc] | [prev] | [next] | [standalone]

#7360

Carl Banks wrote:

> Presumably, the reason you are overriding a method in a subclass
> is to change its behavior;

Not always true by any means, and maybe not even usually true.
Consider overriding for the purpose of implementing an abstract
method, or because something about the internal operation of a
method needs to be modified to suit the requirements of the subclass.

I have a lot of situations like this in PyGUI, where there is a
bunch of generic classes defining the public API, and subclasses
of them for each implementation (Cocoa, Gtk and Windows). There
are heaps and heaps of overridden methods in the implementation
classes, and very few of them need or should have a docstring
different from the generic one. Not automatically inheriting
the docstrings puts a big burden on the maintainer to keep all
of them in sync.

-- 
Greg

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.python

csiph-web