homepage

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

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

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.

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

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