[ python-Bugs-1163367 ] correct/clarify documentation for super

[SourceForge.net]

Bugs item #1163367, was opened at 2005-03-14 16:39
Message generated for change (Comment added) made by bediviere
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1163367&group_id=5470

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: Documentation
Group: Python 2.4
Status: Open
Resolution: None
Priority: 5
Submitted By: Steven Bethard (bediviere)
Assigned to: Fred L. Drake, Jr. (fdrake)
Summary: correct/clarify documentation for super

Initial Comment:
The current documentation for super is confusing.  For
instance, it says that it returns "the superclass of
type" which is incorrect; it actually returns the next
type in type's MRO.  Well, to be truthful, it doesn't
even do that; it returns a proxy object which makes
that type's attributes available, but that's just
another reason to fix the documentation.

I suggest changing the wording to something like:

"""super(type[, object-or-type])

Return an object that exposes the attributes available
through the type's superclasses, without exposing the
attributes of the type itself.  Attributes will be
looked up using the normal resolution order, omitting
the first class in the MRO (that is, the type itself).

If the second argument is present, it should either be
an instance of object, in which case
isinstance(object-or-type, type) must be true, or it
should be an instance of type, in which case
issubclass(object-or-type, type) must be true.  The
typical use for this form of super is to call a
cooperative superclass method:

class C(B):
    def meth(self, arg):
        super(C, self).meth(arg)

If the second argument to super is omitted, the super
object returned will not expose any attributes
directly.  However,  attributes will be accessible
whenever the descriptor machinery is invoked, e.g.
though explicit invocation of __get__.

Note that super is undefined for implicit lookups using
statements or operators such as "super(C, self)[name]".
 These must be spelled out with their explicit lookup,
e.g. "super(C, self).__getitem__(name)". New in version
2.2. 
"""

It's not perfect and I welcome suggestions for
re-wording, but I think it's substantially more
accurate about what super actually does.  It also moves
the "second argument omitted" situation to the end,
since this is a vastly more uncommon use case.

----------------------------------------------------------------------

>Comment By: Steven Bethard (bediviere)
Date: 2006-07-30 23:02

Message:
Logged In: YES 
user_id=945502

The two-arg type form is intended for use with classmethods,
e.g.::

>>> class C(object):
...     @classmethod
...     def f(cls):
...         print 'C.f'
...         
>>> class D(C):
...     @classmethod
...     def f(cls):
...         super(D, cls).f()
...         print 'D.f'
...         
>>> D.f()
C.f
D.f

I do make use of this occasionally, so I do think it should
be documented.

The one-arg form is intended to be used as a class attribute::

>>> class C(object):
...     def f(self):
...         print 'C.f'
... 
>>> class D(C):
...      def f(self):
...          self.super.f()
...          print 'D.f'
... 
>>> D.super = super(D)
>>> D().f()
C.f
D.f

I don't know that we should really be advertising this
one-arg form though.  It requires modifying a class outside
the definition or using some metaclass hackery to be usable.
 And it's misleading because it won't work, for example,
with classmethods:

>>> class C(object):
...     @classmethod
...     def f(cls):
...         print 'C.f'
... 
>>> class D(C):
...     @classmethod
...     def f(cls):
...         cls.super.f()
...         print 'D.f'
... 
>>> D.super = super(D)
>>> D().f()
Traceback (most recent call last):
  File "<interactive input>", line 1, in ?
  File "<interactive input>", line 4, in f
AttributeError: 'super' object has no attribute 'f'

That's why I tried to gloss over it lightly.  Personally I'd
prefer that the one-arg form was just deprecated.  It
introduces a lot more problems than it solves.

But if it has to be documented, it should probably say
something like "A super object created with a single
argument produces a descriptor object. This descriptor
object makes the superclass methods available on the object
returned by its __get__ method. The superclass methods are
only available when __get__ is called with an instance (not
a class)."


----------------------------------------------------------------------

Comment By: Fred L. Drake, Jr. (fdrake)
Date: 2006-07-30 22:29

Message:
Logged In: YES 
user_id=3066

Ok, after playing around a bit with the 1-arg variation and
the 2nd-arg-is-a-type variation, I don't have a clue as to
how either would be used.

It someone can explain either of both of those, please post
an explanation here, and I'll do any LaTeX conversions needed.

I've attached what I have so far as a patch.

----------------------------------------------------------------------

Comment By: Fred L. Drake, Jr. (fdrake)
Date: 2006-07-30 21:58

Message:
Logged In: YES 
user_id=3066

That explanation doesn't deal with the difference between
the 1- and 2-argument signatures.  It can be cleaned up
pretty heavily.  I'll see if I can come up with a decent
comment about 1-argument calls to super().

----------------------------------------------------------------------

Comment By: Steven Bethard (bediviere)
Date: 2006-07-30 21:25

Message:
Logged In: YES 
user_id=945502

If you're talking about the following: 
"""
Note that \function{super} is implemented as part of the
binding process for explicit dotted attribute lookups such
as \samp{super(C, self).__getitem__(name)}.  Accordingly,
\function{super} is undefined for implicit lookups using
statements or operators such as \samp{super(C, self)[name]}. 
""" 
I believe it's trying to say that super works as if it only
overrode __getattr__. Hence ``sup.XXX`` works, but not
``sup[...]``, ``sup(...)``, etc.  That first sentence seems
mostly unnecessary to me.  As long as we say that the
__XXX__ methods must be spelled out explicitly, I think
we've got our bases covered.

----------------------------------------------------------------------

Comment By: Fred L. Drake, Jr. (fdrake)
Date: 2006-07-29 14:40

Message:
Logged In: YES 
user_id=3066

I'm not sure what the paragraph following the \end{verbatim}
means.  Can someone clarify?

----------------------------------------------------------------------

Comment By: Georg Brandl (birkenfeld)
Date: 2006-01-20 10:06

Message:
Logged In: YES 
user_id=1188172

See also Bug #973579 (which I closed as duplicate) for
alternative wording.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1163367&group_id=5470