[issue12077] Harmonizing descriptor protocol documentation
New submission from Davide Rizzo <sorcio@gmail.com>: There are three sources of information for the descriptor protocol: - Data model reference (Doc/reference/datamodel.rst) - Descriptor HowTo guide (Doc/howto/descriptor.rst) - PEP 252 A developer who already knows descriptor tipically reads the first one: object.__get__(self, instance, owner) "... owner is always the owner class ..." Reading a bit further there are the ways a descriptor can be called, and the "direct call" is x.__get__(a). That is, without the third argument (owner) specified. The how-to definition is slightly different: descr.__get__(self, obj, type=None) --> value Here the arguments have different names ("type" shadowing the type bultin) and it seems to be implied that the third argument is optional. The ClassMethod example at the end of the document seems to confirm this: def __get__(self, obj, klass=None): (though another example doesn't). And the method contains an explicit check on klass being None. Also it could be confusing that through the examples in the same document many different names are used for the same argument (type, objtype, klass), and all different than the name used in the reference. Lastly the PEP is more explicit: __get__(): a function callable with one or two arguments. [...] When X is None, the optional second argument, T, should be meta-object. [...] When both X and T are specified ... One more quirk: the reference explains the distinction between data and non-data descriptors, though says nothing about __set__ raising AttributeError for read-only data descriptors. My proposal: - use the same names for __get__ arguments throughout the documentation (both the reference and the tutorial), e.g. __get__(self, instance, owner) - decide whether the third argument should be optional, or state the common usage in the reference, and fix accordingly the examples in the howto - explain data, non-data and read-only descriptors in the __set__ reference, or more simply, how the defintion of __set__ affects these things. ---------- assignee: docs@python components: Documentation messages: 135974 nosy: davide.rizzo, docs@python priority: normal severity: normal status: open title: Harmonizing descriptor protocol documentation versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12077> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti stage: -> needs patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12077> _______________________________________
Changes by Raymond Hettinger <raymond.hettinger@gmail.com>: ---------- assignee: docs@python -> rhettinger nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12077> _______________________________________
Changes by Daniel Urban <urban.dani+py@gmail.com>: ---------- nosy: +durban _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12077> _______________________________________
Jay Parlar <parlar@gmail.com> added the comment: While working on this, I believe it would also make sense to remove all instances of the terms "new-style" and "old-style" from the Descriptor HowTo (and wherever else they might be present) It still makes sense for them to be present in the 2.7 documentation, but they're concepts that don't exist in 3.x ---------- nosy: +Jay.Parlar _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12077> _______________________________________
Jay Parlar <parlar@gmail.com> added the comment: Another problem is that the examples and text in the section "Functions and Methods" is no longer correct in 3.x. Namely the the references to unbound methods, and the example showing an unbound method being returned when accessing a method of a class. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12077> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- nosy: +eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12077> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- type: -> enhancement versions: +Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12077> _______________________________________
Franck Michea added the comment: Here is at least a correction of Descriptors' HowTo. There are two versions since some stuff differs (object inheritance, ...). Here are some of my interrogations though: - RevealAccess is not using instance parameter, so value is shared. Is this intended? - Don't really know what to do with "Function and Methods" part. First I don't really understand the relevance of this in a descriptor how-to. Also it is know outdated in python3 version (unbound thing, ...), so what do? - In __getattribute__ function, I don't really understand the paramters given to __get__, why None and the instance? But this is probably my fault. This also doesn't answer the question about the real source that should be kept. What to do? I also need a proof-read, since english is not my first language... Anyway it's clearly not enough to be published like that Have a nice day! ---------- keywords: +patch nosy: +kushou versions: +Python 3.5 Added file: http://bugs.python.org/file29040/12077_descriptor_howto_python3.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12077> _______________________________________
Changes by Franck Michea <franck.michea@gmail.com>: Added file: http://bugs.python.org/file29041/12077_descriptor_howto_python2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12077> _______________________________________
Changes by Raymond Hettinger <raymond.hettinger@gmail.com>: ---------- assignee: rhettinger -> _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12077> _______________________________________
Changes by Raymond Hettinger <raymond.hettinger@gmail.com>: ---------- assignee: -> rhettinger priority: normal -> low _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12077> _______________________________________
Changes by Ned Batchelder <ned@nedbatchelder.com>: ---------- nosy: +nedbat _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12077> _______________________________________
Martin Panter added the comment: See Issue 23702 specifically about unbound methods in Python 3, and Issue 25435 about general problems with the how-to in Python 3. ---------- nosy: +martin.panter _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12077> _______________________________________
Raymond Hettinger added the comment: I will have a chance to work on this before long. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12077> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: [Davide]
- use the same names for __get__ arguments throughout the documentation (both the reference and the tutorial), e.g. __get__(self, instance, owner)
Early on the choice of variable names diverged (including in various PEPs and in the C source). I will harmonize where I can but the cat is out of the bag.
- decide whether the third argument should be optional, or state the common usage in the reference, and fix accordingly the examples in the howto
PEP 252 specifies that it is optional. Various builtin descriptors also make it optional (function_get, staticmethod_get, classmethod_get, and property_get). I'm fixing the main docs and non-compliant code in PR 12992
explain data, non-data and read-only descriptors in the __set__ reference, or more simply, how the > defintion of __set__ affects these things.
That is reasonable. Will add to the datamodel docs. [Jay Parlar]
Another problem is that the examples and text in the section "Functions and Methods" is no longer correct in 3.x. Namely the the references to unbound methods
That was fixed a good while ago. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue12077> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: See PR 12992 for the cross-reference from the __set__ docs to the section covering data and non-data descriptors. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue12077> _______________________________________
Change by Raymond Hettinger <raymond.hettinger@gmail.com>: ---------- resolution: -> fixed stage: needs patch -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue12077> _______________________________________
participants (9)
-
Daniel Urban -
Davide Rizzo
-
Ezio Melotti
-
Franck Michea
-
Jay Parlar
-
Martin Panter
-
Ned Batchelder
-
Raymond Hettinger
-
Éric Araujo