Doc error on super(cls,self)

[macquigg]

BPO	973579
Nosy	@freddrake, @birkenfeld

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/freddrake'
closed_at = <Date 2006-01-20.17:07:26.000>
created_at = <Date 2004-06-15.22:43:24.000>
labels = ['docs']
title = 'Doc error on super(cls,self)'
updated_at = <Date 2006-01-20.17:07:26.000>
user = 'https://bugs.python.org/macquigg'

bugs.python.org fields:

activity = <Date 2006-01-20.17:07:26.000>
actor = 'georg.brandl'
assignee = 'fdrake'
closed = True
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2004-06-15.22:43:24.000>
creator = 'macquigg'
dependencies = []
files = []
hgrepos = []
issue_num = 973579
keywords = []
message_count = 5.0
messages = ['21202', '21203', '21204', '21205', '21206']
nosy_count = 4.0
nosy_names = ['fdrake', 'georg.brandl', 'jimjjewett', 'macquigg']
pr_nums = []
priority = 'normal'
resolution = 'duplicate'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue973579'
versions = []

[macquigg]

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.

[jimjjewett]

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.

"""

[macquigg]

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.

[macquigg]

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.

[birkenfeld]

Logged In: YES
user_id=1188172

bpo-1163367 suggests a more complete new wording. Closing as
duplicate.