[issue25772] Misleading descriptions about built-in type `super.`
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-... ---------- assignee: docs@python components: Documentation messages: 255643 nosy: Juchen Zeng, docs@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@bugs.python.org> <http://bugs.python.org/issue25772> _______________________________________
Martin Panter added the comment: I agree. I think Issue 23674 already covers this. I will try to propose some changes there. ---------- nosy: +martin.panter resolution: -> duplicate status: open -> closed superseder: -> super() documentation isn't very clear _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25772> _______________________________________
R. David Murray added the comment: 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 :) ---------- nosy: +r.david.murray title: Misleading descriptions about built-in type `super.` -> Misleading descriptions about built-in `super.` _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25772> _______________________________________
Eryk Sun added the comment:
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. ---------- nosy: +eryksun _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25772> _______________________________________
R. David Murray added the comment: Heh. OK, learn something new every day. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25772> _______________________________________
Martin Panter added the comment: I agree. I think Issue 23674 already covers this. I will try to propose some changes there. ---------- nosy: +martin.panter resolution: -> duplicate status: open -> closed superseder: -> super() documentation isn't very clear _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25772> _______________________________________
R. David Murray added the comment: 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 :) ---------- nosy: +r.david.murray title: Misleading descriptions about built-in type `super.` -> Misleading descriptions about built-in `super.` _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25772> _______________________________________
Eryk Sun added the comment:
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. ---------- nosy: +eryksun _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25772> _______________________________________
R. David Murray added the comment: Heh. OK, learn something new every day. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25772> _______________________________________
participants (4)
-
Eryk Sun -
Juchen Zeng
-
Martin Panter
-
R. David Murray