[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 <report@bugs.python.org> <http://bugs.python.org/issue25777> _______________________________________
Martin Panter added the comment: Agreed. The same problem is also present in the Python 3 documentation. (Beware there is another report somewhere about updating this how-to more generally for Python 3.) Maybe we could be more explicit and start off “The attribute lookup super(B, obj).m searches . . .” Also, I find the last sentence confusing: “If not in the dictionary, m reverts to a search using object.__getattribute__().” I guess it is describing how super(B, obj).__self__ accesses the internal attribute of the super object itself. Maybe it should say “If not in any base class, the lookup resorts to attributes of the super instance itself using object.__getattribute__().” ---------- stage: -> needs patch versions: +Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25777> _______________________________________
Martin Panter added the comment: Similar change needed for <https://docs.python.org/dev/reference/datamodel.html#invoking-descriptors>. There, it uses the noun “binding”, which seems an appropriate description of the action. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25777> _______________________________________
Changes by Raymond Hettinger <raymond.hettinger@gmail.com>: ---------- assignee: docs@python -> rhettinger nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25777> _______________________________________
Change by Raymond Hettinger <raymond.hettinger@gmail.com>: ---------- keywords: +patch pull_requests: +15249 stage: needs patch -> patch review pull_request: https://github.com/python/cpython/pull/15573 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25777> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: New changeset 03acba6f1a851064ba1fa78965ece4354d499c04 by Raymond Hettinger in branch 'master': bpo-25777: Wording describes a lookup, not a call (GH-15573) https://github.com/python/cpython/commit/03acba6f1a851064ba1fa78965ece4354d4... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25777> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +15252 pull_request: https://github.com/python/cpython/pull/15576 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25777> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: New changeset f3dca6acee609a3a12f22152fd98602c1cbadde0 by Raymond Hettinger (Miss Islington (bot)) in branch '3.8': bpo-25777: Wording describes a lookup, not a call (GH-15573) (GH-15576) https://github.com/python/cpython/commit/f3dca6acee609a3a12f22152fd98602c1cb... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25777> _______________________________________
Change by Raymond Hettinger <raymond.hettinger@gmail.com>: ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25777> _______________________________________
participants (4)
-
Juchen Zeng -
Martin Panter
-
miss-islington
-
Raymond Hettinger