Misleading descriptions in docs about invoking descriptors.

[JuchenZeng]

BPO	25777
Nosy	@rhettinger, @vadmium
PRs	bpo-25777: Wording describes a lookup, not a call #15573 [3.8] bpo-25777: Wording describes a lookup, not a call (GH-15573) #15576

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/rhettinger'
closed_at = <Date 2019-08-29.06:12:51.262>
created_at = <Date 2015-12-02.12:22:21.460>
labels = ['docs']
title = 'Misleading descriptions in docs about invoking descriptors.'
updated_at = <Date 2019-08-29.06:12:51.261>
user = 'https://bugs.python.org/JuchenZeng'

bugs.python.org fields:

activity = <Date 2019-08-29.06:12:51.261>
actor = 'rhettinger'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2019-08-29.06:12:51.262>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2015-12-02.12:22:21.460>
creator = 'Juchen Zeng'
dependencies = []
files = []
hgrepos = []
issue_num = 25777
keywords = ['patch']
message_count = 5.0
messages = ['255712', '255797', '255991', '350722', '350726']
nosy_count = 4.0
nosy_names = ['rhettinger', 'docs@python', 'martin.panter', 'Juchen Zeng']
pr_nums = ['15573', '15576']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue25777'
versions = ['Python 2.7', 'Python 3.4', 'Python 3.5', 'Python 3.6']

[JuchenZeng]

Doc Link

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).

[vadmium]

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__().”

[vadmium]

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.

[rhettinger]

New changeset 03acba6 by Raymond Hettinger in branch 'master':
bpo-25777: Wording describes a lookup, not a call (GH-15573)
03acba6

[rhettinger]

New changeset f3dca6a by Raymond Hettinger (Miss Islington (bot)) in branch '3.8':
bpo-25777: Wording describes a lookup, not a call (GH-15573) (GH-15576)
f3dca6a