[Python-Dev] Descriptor write-up [second draft]

[Brett C.]

Raymond Hettinger wrote:
> Thanks for the first round of comments.
> Here is a second draft:
> 
> http://users.rcn.com/python/download/Descriptor.htm
> 

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