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

[SourceForge.net]

Bugs item #1163367, was opened at 2005-03-15 00:39
Message generated for change (Settings changed) made by birkenfeld
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: Georg Brandl (birkenfeld)
Date: 2006-01-20 18: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