[New-bugs-announce] [issue25772] Misleading descriptions about built-in type `super.`

[Juchen Zeng]

New submission from Juchen Zeng:

A few days ago, I was learning built-in type `super` through [python official doc](https://docs.python.org/2/library/functions.html#super).  
And I was mislead by its documentation, in the part of how `__mro__` resolution works. Below is the part which confuse me:

"""
super(type[, object-or-type])

# ISSUE IRRELEVANT DOC OMITTED

The __mro__ attribute of the type lists the method resolution search order used by both getattr() and super(). The attribute is dynamic and can change whenever the inheritance hierarchy is updated.
"""

>From the description of the doc we can see that `super()` takes two arguments, the first is `type` and the second is an optional `object-or-type`. So, when I saw the doc statement: `The __mro__ attribute of the type lists the method resolution search order used by both getattr() and super(). `, I naturally thought here the `type` refers to the compulsory first `type` argument. But after doing a series of [experiments][EXP_REF]. It turns out in `super()` was using the second `type`'s `__mro__` attribute! And if the second argument is an object, it will use `object.__class__.__mro__` as its resolution order. Unless a learner experimented it throughly like me, he will have lots of difficulty to figured out that `type` mentioned in the doc refers to the second optional argument. I think here the doc should be clearly specified that the second argument's `__mro__` is what super relies on. I suggest to add distinctions on arguments name or add more clarification informations in the doc here.

By the way, the python3 document has the same issue.  
If you decided to fix this, maybe you want to fix its python3 version, too.

 

[EXP_REF]: http://stackoverflow.com/questions/33890918/how-does-super-interacts-with-a-classs-mro-attribute-in-multiple-inheri/33891281#33891281

----------
assignee: docs at python
components: Documentation
messages: 255643
nosy: Juchen Zeng, docs at python, eric.araujo, ezio.melotti, georg.brandl
priority: normal
severity: normal
status: open
title: Misleading descriptions about built-in type `super.`
versions: Python 2.7

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue25772>
_______________________________________