classification
Title: correct/clarify documentation for super
Type: Stage:
Components: Documentation Versions: Python 2.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: bethard, fdrake, georg.brandl, kjohnson, rhettinger
Priority: normal Keywords:

Created on 2005-03-14 23:39 by bethard, last changed 2008-12-06 11:45 by rhettinger. This issue is now closed.

Files
File name Uploaded Description Edit
super.diff fdrake, 2006-07-31 04:29 Fred's documentation patch; still needy.
super.diff fdrake, 2006-07-31 07:01 Revised patch, describing both 2-arg forms.
Messages (12)
msg24610 - (view) Author: Steven Bethard (bethard) * (Python committer) Date: 2005-03-14 23:39
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.
msg24611 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2006-01-20 17:06
Logged In: YES 
user_id=1188172

See also Bug #973579 (which I closed as duplicate) for
alternative wording.
msg24612 - (view) Author: Fred L. Drake, Jr. (fdrake) (Python committer) Date: 2006-07-29 20:40
Logged In: YES 
user_id=3066

I'm not sure what the paragraph following the \end{verbatim}
means.  Can someone clarify?
msg24613 - (view) Author: Steven Bethard (bethard) * (Python committer) Date: 2006-07-31 03:25
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.
msg24614 - (view) Author: Fred L. Drake, Jr. (fdrake) (Python committer) Date: 2006-07-31 03:58
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().
msg24615 - (view) Author: Fred L. Drake, Jr. (fdrake) (Python committer) Date: 2006-07-31 04:29
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.
msg24616 - (view) Author: Steven Bethard (bethard) * (Python committer) Date: 2006-07-31 05:02
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)."
msg24617 - (view) Author: Fred L. Drake, Jr. (fdrake) (Python committer) Date: 2006-07-31 07:01
Logged In: YES 
user_id=3066

Thanks Steven; that helps a lot!

I've attached a revised version of my patch that describes
both 2-arg forms; I'll see about refining it further after
I've had a bit of sleep, and time to play with the 1-arg form.
msg64235 - (view) Author: Kent Johnson (kjohnson) * Date: 2008-03-21 11:48
This issue seems to have foundered on finding an explanation for the
finer points of super(). Perhaps the glaring errors could at least be
corrected, or the fine points could be omitted or glossed over? For
example change the first sentence of the docs to "Returns a proxy for
the type following 'type' in the method resolution order of
'object-or-type'." 

Perhaps link to these?
http://chandlerproject.org/bin/view/Projects/UsingSuper
http://fuhm.net/super-harmful/
msg76887 - (view) Author: Fred L. Drake, Jr. (fdrake) (Python committer) Date: 2008-12-04 15:19
Clearly, I've not gotten to this; unassigning from myself.

Probably a good thing, since I'm one of the people who probably don't
use it correctly in all cases.
msg76919 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2008-12-04 19:20
I'll look at this further.  Since it was originally posted, there have
already been several improvements to the super() docs.

FWIW, there will be no links to super-considered-harmful.  Guido has
frowned upon that document.  Our documentation needs to be written in an
affirmative manner, indicating what problems super() solves and how to
use it well.  This is far better than itemizing its misuses and
suggesting that it is an anti-feature.
msg77114 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2008-12-06 11:45
Updated again in r67607.  Hopefully, this one has been put to rest.  If
someone has further issues with the super() docs, please open a new
report (preferably with suggested wording).
History
Date User Action Args
2008-12-06 11:45:37rhettingersetstatus: open -> closed
resolution: fixed
messages: + msg77114
2008-12-04 19:20:12rhettingersetassignee: rhettinger
messages: + msg76919
nosy: + rhettinger
2008-12-04 15:19:07fdrakesetassignee: fdrake -> (no value)
messages: + msg76887
2008-03-21 11:48:08kjohnsonsetnosy: + kjohnson
messages: + msg64235
2005-03-14 23:39:38bethardcreate