[docs] Descriptor HowTo Guide: 2 bits of misleading information

[Ruy Asan]

They gave me a bit of a headache until I figured out it was the guide
itself that was the problem...

Issues appear to be present in all versions up to the current dev branch
(3.4): http://docs.python.org/3.4/howto/descriptor.html


1) Under "Descriptor
Protocol<http://docs.python.org/3.4/howto/descriptor.html#descriptor-protocol>"
the method signature for __get__ is just outright wrong:

descr.__get__(self, obj, type=None) --> value

The type argument is not optional (though obj can be None, but that's not
part of the signature at all). I also think using "obj" and "type"
needlessly inconsistent, pretty much all documentation uses "instance" and
"owner" instead (and they are arguably better descriptions to begin with).

It shouldn't be a big deal but since that is actually the very first
mention of __get__'s signature if you just google "python descriptors",
well, I for one took note of it and stopped paying attention to subsequent
examples.

2) Under "Descriptor
Example<http://docs.python.org/3.4/howto/descriptor.html#descriptor-example>"
the use of "self.value" to store instance data is just very very
misleading. Of course it works in that particular example and this being an
introductory "HowTo" should suggest that none of the examples are actually
meant for production code, but  still, it's showing off a reasonably common
application of descriptors (... storing property values) but using a
*wrong* implementation
(and "*wrong"* in a pretty not-obvious way to catch as well!). Stack
overflow questions and 3rd party guides to descriptors keep having to point
out how that's a bad example.

It also doesn't help that the right way of doing that sort of thing is not
at all trivial and full of pitfalls (internal weakref dicts don't work if
the descriptors are attached to a non-hashable class, and storing in
instance.__dict__ either relies on having to repeat yourself when assigning
descriptors (so they can shadow their own name, but they can only know
their name if explicitly told to them in __init__ or somesuch), or
polluting the instance object with ugly underscore "private values" for
each descriptor).

If storing property values is indeed a valid application of descriptors,
then ideally the HowTo guide should include an official recommended
reference implementation (clearly stating the tradeoffs). -OR-, if this is
the sort of thing that is tricky and difficult because it's *not* actually
a valid application of descriptors (or at least frowned upon) then maybe it
would be best if the HowTo guide used a different type of example
altogether.

Cheers,
- Ruy
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20131218/15b1f321/attachment-0001.html>