[Python-Dev] Hot-To Guide for Descriptors - Nits! :-)

[François Pinard]

Hello, Raymond.  Cc:ing python-dev, so others can bash me as well! :-)

This is about `http://users.rcn.com/python/download/Descriptor.htm'.
Before anything else, let me thank you for having written this essay!
Please also take all my remarks with a grain of salt or two, as I'm far
for pretending I really understand all the matters here.


* In `Definition and Introduction', a parenthetical note "(ones
that subclass `object' or `type')" qualifies the expression "new
style objects or classes".  Not being an English speaker, I'm a
little mixed up with the plural "ones" and the fact I was expecting
"subclasses" instead of "subclass", maybe replacing "ones" by "those"
would be clearer.

* Another point is that the phrasing suggests that the parenthetical
note is a definition for what precedes it.  In my understanding, the
parenthetical note implies what precedes it, but is not implied by it.
A new-style instance may well have no base class at all, only given its
meta-class is a subtype of `type'.  Would it be more precise to state:
"... new style objects or classes (those for which the meta-class is a
subtype of `type')"?  Being sub-classed from object or type is just a
way, among others, for identifying `type' as the meta-class; but being
sub-classed from object is not really required.

* In `Descriptor Protocol', it might help a bit saying immediately a
word or two about the `type=None' argument.  Looking down for some
hint, the box holding "def __getattribute__(self, key): ..." uses
the statement "return v.__get__(None, self)", which I find confusing
respective to the `__get__' prototype, as `obj' corresponds to None, and
`type=None' likely corresponds to an instance instead of a type.

* In `Invoking Descriptors', it might help a bit insisting on the
(presumed) fact that `hasattr' itself does not look for descriptors.
For symmetry, it would also be nice having two boxes defining
`__getattribute__, one for objects, another for classes, instead of only
the second one.  I was not sure if the assymetry had a purpose, like
maybe telling us that the first case may not be expressed using Python.

* A little below is a quick description of `super()'.  It says that "The
call ... searches ... mro ... for the base class ... immediately
preceding ...".  Should not it be `following' instead of `preceding'?
In case yes, than maybe `A' and `B' might be exchanged for clarity.

* In `Properties', the box starting with "class Property(object):"
raises a few questions.  First is the `doc or ""' to defined
`self.__doc__', it does not seem that the ` or ""' exists in Python
2.2.1 nor 2.3.2, the __doc__ really defaults to None.  Second is that
the argument `objtype=None' to `__get__' is unused, and once more,
this does not help understanding its purpose, maybe some explanation
would be welcome about why it exists and is unneeded in the context of
`property'.  Third is that on the last line, "self.fdel(obj, value)" was
probably meant to be "self.fdel(obj)".

-- 
François Pinard   http://www.iro.umontreal.ca/~pinard