Descriptor write-up [second draft]
Thanks for the first round of comments. Here is a second draft: http://users.rcn.com/python/download/Descriptor.htm Changes: * various grammatical, punctuation, etc * changed variable names between examples * discuss data and non-data descriptors * show the precedence of the data vs non-data descriptors * moved the C code references inside the Python code * eliminated the python code for obj.__getattribute__ because code was complex enough to hide the discussion points To do: When this one is done, will use it as a basis for updating the official docs. The final version of this will be done through docutils with reStructured text. That ought to take care of the vagaries of converting a Word document to html. Raymond
Raymond Hettinger wrote:
Thanks for the first round of comments. Here is a second draft:
Once again, good job, Raymond! But now, to the nit-picky stuff. =) For the section entitled "Definition and Introduction", I don't like it reading like its namesake. I feel like the intro paragraphs should come first to let you know why you should be learning this stuff and then give the general overview of what a descriptor is. In "Descriptor Protocol" it feels abrupt when you mention how to make a data descriptor read-only. I feel like it should read more like "To make a read-only data descriptor, define both __get__ and __set__ with the __set__ raising an AttributeError exception when called since a data descriptor must define *some* __set__ method", or something like that. It just comes off as some random piece of info with no tie into why it is that way. For the "Properties" the __get__ parameter list you use the name 'type'. Unfortunately that masks the built-in. Not a big issue but people might copy this code and such so having it as correct as possible won't hurt. Otherwise its a great piece. -Brett
Once again, good job, Raymond!
But now, to the nit-picky stuff. =) For the section entitled "Definition and Introduction", I don't like it reading like its namesake. I feel like the intro paragraphs should come first to let you know why you should be learning this stuff and then give the general overview of what a descriptor is.
"All I want to know is what a descriptor is" --> "Okay, read the definition" That's the Raymond way -- No character development, foreshadowing, false climaxes, nada.
In "Descriptor Protocol" it feels abrupt when you mention how to make a data descriptor read-only. I feel like it should read more like "To make a read-only data descriptor, define both __get__ and __set__ with the __set__ raising an AttributeError exception when called since a data descriptor must define *some* __set__ method", or something like that. It just comes off as some random piece of info with no tie into why it is that way.
Fixed.
For the "Properties" the __get__ parameter list you use the name 'type'. Unfortunately that masks the built-in. Not a big issue but people might copy this code and such so having it as correct as possible won't hurt.
Unfortunately, type *is* the advertised parameter name. Fixed it anyway.
Otherwise its a great piece.
Thanks. Raymond ################################################################# ################################################################# ################################################################# ##### ##### ##### ################################################################# ################################################################# #################################################################
participants (3)
-
Brett C.
-
Raymond Hettinger
-
Raymond Hettinger