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

I agree. I think Issue 23674 already covers this. I will try to propose some changes there.

Just FYI, 'super' is not a type, it is a function that returns a proxy.  (In python3 there is also compiler magic involved in the no-argument form, but it is still a function :)

> Just FYI, 'super' is not a type

No, super is a type:

    >>> super
    <type 'super'>

It's one of 3 types defined in Objects/typeobject.c: 

    PyBaseObject_Type : "object"
    PyType_Type       : "type"
    PySuper_Type      : "super"

A super instance (CPython superobject) has the following members: 

     __thisclass__  : the class invoking super()
     __self__       : the instance invoking super()
     __self_class__ : the type of the instance invoking super()

super has a cutsom __getattribute__ (tp_getattro) slot, super_getattro, which proxies attribute access starting at the parent/sibling of __thisclass__ in the __mro__ of __self_class__. 

super even defines a __get__ descriptor (tp_descr_get) method, super_descr_get, though I've never used it as such.

Heh.  OK, learn something new every day.