[issue12077] Harmonizing descriptor protocol documentation
New submission from Davide Rizzo
Changes by Ezio Melotti
Changes by Raymond Hettinger
Changes by Daniel Urban
Jay Parlar
Jay Parlar
Changes by Éric Araujo
Changes by Ezio Melotti
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
Changes by Franck Michea
Changes by Raymond Hettinger
Changes by Raymond Hettinger
Changes by Ned Batchelder
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
Raymond Hettinger added the comment:
I will have a chance to work on this before long.
----------
_______________________________________
Python tracker
Raymond Hettinger
- 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
Raymond Hettinger
Change by Raymond Hettinger
participants (9)
-
Daniel Urban
-
Davide Rizzo
-
Ezio Melotti
-
Franck Michea
-
Jay Parlar
-
Martin Panter
-
Ned Batchelder
-
Raymond Hettinger
-
Éric Araujo