This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Doc error on super(cls,self)
Type: Stage:
Components: Documentation Versions:
Status: closed Resolution: duplicate
Dependencies: Superseder:
Assigned To: fdrake Nosy List: fdrake, georg.brandl, jimjjewett, macquigg
Priority: normal Keywords:

Created on 2004-06-15 22:43 by macquigg, last changed 2022-04-11 14:56 by admin. This issue is now closed.

Messages (5)
msg21202 - (view) Author: David MacQuigg (macquigg) Date: 2004-06-15 22:43
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:


   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 
msg21203 - (view) Author: Jim Jewett (jimjjewett) Date: 2004-06-21 14:50
Logged In: YES 

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


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.  

msg21204 - (view) Author: David MacQuigg (macquigg) Date: 2004-06-21 16:23
Logged In: YES 

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 but 
that may be too long if what we need here is a "man page" 
msg21205 - (view) Author: David MacQuigg (macquigg) Date: 2004-07-21 15:20
Logged In: YES 

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.
msg21206 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2006-01-20 17:07
Logged In: YES 

#1163367 suggests a more complete new wording. Closing as
Date User Action Args
2022-04-11 14:56:04adminsetgithub: 40406
2004-06-15 22:43:24macquiggcreate