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

Created on 2015-12-02 12:22 by Juchen Zeng, last changed 2015-12-07 06:28 by rhettinger.

Messages (3)
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.
History
Date User Action Args
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