[issue20751] Misleading examples indDescriptor protocol documentation
New submission from Jan Kaliszewski: 1. One misleading detail in the descriptor protocol documentation for super bindings is that the following fragment of the http://docs.python.org/reference/datamodel.html#invoking-descriptors page: """ Super Binding If a is an instance of super, then the binding super(B, obj).m() searches obj.__class__.__mro__ for the base class A immediately preceding B and then invokes the descriptor with the call: A.__dict__['m'].__get__(obj, obj.__class__). """ ...introduces the method *call* (".m()") which AFAIK has nothing to do with the actual matter of the description (attribute resolution). Also, the "If *a* is an instance of super" fragment is strange, as *a* is not used in the following sentences at all. I believe the description should be: """ Super Binding If binding to a super instance, super(B, obj).x searches obj.__class__.__mro__ for the base class A immediately preceding B and then invokes the descriptor with the call: A.__dict__['x'].__get__(obj, obj.__class__). """ (using 'x' as the attribute name, as for the other kinds of binding). *** 2. Also, in some earlier fragment of the same page: """ Direct Call The simplest and least common call is when user code directly invokes a descriptor method: x.__get__(a). """ The call x.__get__(a) without the second argument seems to be wrong if __get__ is implemented according to the specification "object.__get__(self, instance, owner)" from the same documentation page. ---------- assignee: docs@python components: Documentation messages: 212035 nosy: docs@python, zuo priority: normal severity: normal status: open title: Misleading examples indDescriptor protocol documentation versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20751> _______________________________________
Changes by Jan Kaliszewski <zuo@chopin.edu.pl>: ---------- title: Misleading examples indDescriptor protocol documentation -> Misleading examples in the descriptor protocol documentation _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20751> _______________________________________
Mark Lawrence added the comment: Who is best placed to comment on the suggested docs changes given in msg212035? ---------- nosy: +BreamoreBoy versions: +Python 3.5 -Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20751> _______________________________________
Martin Panter added the comment: Lower-case “a” is defined at the top of the list: “The starting point . . . is ‘a.x’.” The last entry may fit in better if it was written “If binding to an instance of ‘super’ ”. The problem with the m() call is also mentioned in Issue 25777, about the descriptor how-to. Issue 12077 seems to be largely about the __get__ signature. ---------- dependencies: +Harmonizing descriptor protocol documentation nosy: +martin.panter, rhettinger stage: -> needs patch title: Misleading examples in the descriptor protocol documentation -> Misleading descriptor protocol documentation: direct call, super binding versions: +Python 2.7, Python 3.6, Python 3.7 -Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20751> _______________________________________
Changes by Mark Lawrence <breamoreboy@gmail.com>: ---------- nosy: -BreamoreBoy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20751> _______________________________________
participants (3)
-
Jan Kaliszewski -
Mark Lawrence -
Martin Panter