In both the Library Reference, section 2.1, and in the 
Python 2.2 Quick Reference, page 19, the explanation 
for this function is:

super( type[, object-or-type]) 
   Returns the superclass of type. ...

This is misleading.  I could not get this function to work 
right until I realized that it is searching the entire MRO, 
not just the superclasses of 'type'.  See 
comp.lang.python 6/11/04, same subject as above, for 
further discussion and an example.

I think a better explanation would be:

super(cls,self).m(arg)

   Calls method 'm' from a class in the MRO (Method 
Resolution Order) of 'self'.  The selected class is the first 
one which is above 'cls' in the MRO and which 
contains 'm'.

The 'super' built-in function actually returns not a class, 
but a 'super' object.  This object can be saved, like a 
bound method, and later used to do a new search of the 
MRO for a different method to be applied to the saved 
instance.

Logged In: YES 
user_id=764593

Would an expanded example also help?  

I'm not sure I like my own wording yet, but ... I propose it as a 
straw man.

"""super returns the next parent class[1]

class A(object): pass

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

class C(A): pass

class D(B, C): pass

d=D()
d.meth()

In this case, the super(B, self) call will actually return a 
reference to class C.  Class C is not a parent of class B, but it 
is the next parent for this particular instance d of class B.


[1] Actually, a super class mimicing the parent class.  

"""

Logged In: YES 
user_id=676422

I like the example, but the new explanation still leaves the 
impression that super() returns a class ( or something that 
acts like a class).  This is what made super() so difficult to 
figure out the first time I tried it.  The 'super' object returned 
by the function appears to be a collection of references, one 
to the 'self' instance, and one to each of the classes in the 
MRO of self above 'cls'.  The reason it can't be just a class is 
that a given super object needs to retrieve a different class 
each time it is used, depending on what method is provided.

The only thing lacking in the example is motivation for why we 
need super(B,self).meth(arg) instead of just calling C.meth
(self,arg).  I have a longer example and some motivation on 
page 16 in my OOP chapter at 
http://ece.arizona.edu/~edatools/Python/PythonOOP.doc but 
that may be too long if what we need here is a "man page" 
explanation.

Logged In: YES 
user_id=676422

While waiting for the perfect solution, would it be possible to 
have links to this item at the places in the documentation 
where the corrections should be made (Library Reference 2.1, 
Quick Reference page 19)?  It could save an hour of 
experimentation for each new user of this feature.

Logged In: YES 
user_id=1188172

#1163367 suggests a more complete new wording. Closing as
duplicate.