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

[Raymond Hettinger]

> * 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.

Clarified.


> * 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.

Sounds like an obscure grammar nit (one that doesn't appear in any of
my grammar books).  I think it reads well enough as is.


> 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.

Nope, new-style is taken to mean objects/classes inheriting from
object/type.  Meta-class objects are neither new-style nor old-style.
While there is room to argue with this arbitrary distinction, it is
consistent with Guido's essay and especially relevant to my article
because most of the rules don't necessarily apply when meta-classes
are used.  This is because the machinery for descriptors is 
embedded in type.__getattribute__ and object.__getattribute__.  
Override or fail to inherit either of these and all bets are off.


> * 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.

I'll keep an open mind on this one but think it is probably fine as it
stands.  Though the calling pattern may not be beautiful and could be
confusing to some, my description accurately represents the signature
and cases where are argument is potentially ignored.  That is just the
way it is.


> * In `Invoking Descriptors', it might help a bit insisting on the
> (presumed) fact that `hasattr' itself does not look for descriptors.

I considered this and other explanations when writing the article.
The subject is already complex enough that additional explanations
can make it harder to understand rather than easier.  Sidetrips
can add more confusion than they cure.  I see no reason to delve
into what hasattr() doesn't do.


> 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.

It did have a purpose.  I put in pure python code only when it served
as an aid to understanding.  In this case, the operation of
__getattribute__
is more readily described with prose.  I do include a C code reference
for those wanting all the gory details.  If you look at the reference,
you'll see that a pure python equivalent would not be succinct or
provide
any deep insights not covered the text.

Once again, it was a question of whether to break-up the flow of the
argument/explanation.  I like it the way it is.



> * 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'?

It is a matter of perspective.  A is defined before its derived class B
and can be said to precede it in the inheritance graph; however, the
MRO list would have B ... A ... O so there is a case for the word
"following".  To keep consistent with Guido's essay, I'll make the
change and adopt your convention.


> In case yes, than maybe `A' and `B' might be exchanged for clarity.

No.  A is higher than B on the inheritance hierarchy.  Also, the
lettering
is consistent with Guido's essay.



> * 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. 

Fixed.



> 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'.

That's the way it is.



> Third is that on the last line, "self.fdel(obj, value)" was
> probably meant to be "self.fdel(obj)".

Fixed.



Raymond Hettinger