[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 he re. 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@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 <http://bugs.python.org/issue25772> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue25777] Misleading descriptions in docs about invoking descriptors.
New submission from Juchen Zeng: [Doc Link](https://docs.python.org/2/howto/descriptor.html#invoking-descriptors) In descriptions about how to invoke descriptors with super(), it says: The call super(B, obj).m() searches obj.__class__.__mro__ for the base class A immediately following B and then returns A.__dict__['m'].__get__(obj, B). If not a descriptor, m is returned unchanged. If not in the dictionary, m reverts to a search using object.__getattribute__(). But the call ` super(B, obj).m()` will not return `A.__dict__['m'].__get__(obj, B)`, it will trigger the `__call__` method of ` A.__dict__['m'].__get__(obj, B)` if it has that attr, and return what this `__call__` method returns. It could be anything. It's actually `super(B, obj).m` returns `A.__dict__['m'].__get__(obj, B)` if m is a descriptor. In short, the original description in the doc can be abbreviated to: `The call super(B, obj).m() [did something] and returns A.__dict__['m'].__get__(obj, B).` Which is obviously misleading. As the method/function call isn't the core part in this sentence. I suggest the doc to be fixed like this: The action super(B, obj).m searches obj.__class__.__mro__ for the base class A immediately following B and then returns A.__dict__['m'].__get__(obj, B). -- assignee: docs@python components: Documentation messages: 255712 nosy: Juchen Zeng, docs@python, martin.panter priority: normal severity: normal status: open title: Misleading descriptions in docs about invoking descriptors. versions: Python 2.7 ___ Python tracker <http://bugs.python.org/issue25777> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
