classification
Title: Misleading descriptions in docs about invoking descriptors.
Type: Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: Juchen Zeng, docs@python, martin.panter, rhettinger
Priority: normal Keywords: patch

Created on 2015-12-02 12:22 by Juchen Zeng, last changed 2019-08-29 06:12 by rhettinger. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 15573 merged rhettinger, 2019-08-29 05:23
PR 15576 merged miss-islington, 2019-08-29 05:59
Messages (5)
msg255712 - (view) Author: Juchen Zeng (Juchen Zeng) Date: 2015-12-02 12:22
[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).
msg255797 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-12-03 00:15
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__().”
msg255991 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-12-05 23:14
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.
msg350722 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-08-29 05:59
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/03acba6f1a851064ba1fa78965ece4354d499c04
msg350726 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-08-29 06:12
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/f3dca6acee609a3a12f22152fd98602c1cbadde0
History
Date User Action Args
2019-08-29 06:12:51rhettingersetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2019-08-29 06:12:16rhettingersetmessages: + msg350726
2019-08-29 05:59:54miss-islingtonsetpull_requests: + pull_request15252
2019-08-29 05:59:46rhettingersetmessages: + msg350722
2019-08-29 05:23:07rhettingersetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request15249
2015-12-07 06:28:32rhettingersetassignee: docs@python -> rhettinger

nosy: + rhettinger
2015-12-05 23:14:25martin.pantersetmessages: + msg255991
2015-12-03 00:15:37martin.pantersetstage: needs patch
messages: + msg255797
versions: + Python 3.4, Python 3.5, Python 3.6
2015-12-02 12:22:21Juchen Zengcreate