[issue25777] Misleading descriptions in docs about invoking descriptors.

[Raymond Hettinger]

Raymond Hettinger  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/f3dca6acee609a3a12f22152fd98602c1cbadde0


--

___
Python tracker 

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

[Raymond Hettinger]

Change by Raymond Hettinger :


--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

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

[miss-islington]

Change by miss-islington :


--
pull_requests: +15252
pull_request: https://github.com/python/cpython/pull/15576

___
Python tracker 

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

[Raymond Hettinger]

Raymond Hettinger  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/03acba6f1a851064ba1fa78965ece4354d499c04


--

___
Python tracker 

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

[Raymond Hettinger]

Change by Raymond Hettinger :


--
keywords: +patch
pull_requests: +15249
stage: needs patch -> patch review
pull_request: https://github.com/python/cpython/pull/15573

___
Python tracker 

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

[Raymond Hettinger]

Changes by Raymond Hettinger :


--
assignee: docs@python -> rhettinger
nosy: +rhettinger

___
Python tracker 

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

[Martin Panter]

Martin Panter added the comment:

Similar change needed for 
. 
There, it uses the noun “binding”, which seems an appropriate description of 
the action.

--

___
Python tracker 

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

[Martin Panter]

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 

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

[Juchen Zeng]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com