[docs] [issue12077] Harmonizing descriptor protocol documentation

[Davide Rizzo]

New submission from Davide Rizzo <sorcio at gmail.com>:

There are three sources of information for the descriptor protocol:
- Data model reference (Doc/reference/datamodel.rst)
- Descriptor HowTo guide (Doc/howto/descriptor.rst)
- PEP 252

A developer who already knows descriptor tipically reads the first one:
object.__get__(self, instance, owner) "... owner is always the owner class ..."
Reading a bit further there are the ways a descriptor can be called, and the "direct call" is x.__get__(a). That is, without the third argument (owner) specified.

The how-to definition is slightly different:
descr.__get__(self, obj, type=None) --> value
Here the arguments have different names ("type" shadowing the type bultin) and it seems to be implied that the third argument is optional. The ClassMethod example at the end of the document seems to confirm this:
def __get__(self, obj, klass=None):
(though another example doesn't).
And the method contains an explicit check on klass being None.
Also it could be confusing that through the examples in the same document many different names are used for the same argument (type, objtype, klass), and all different than the name used in the reference.

Lastly the PEP is more explicit:
__get__(): a function callable with one or two arguments. [...] When X is None, the optional second argument, T, should be meta-object. [...] When both X and T are specified ...

One more quirk: the reference explains the distinction between data and non-data descriptors, though says nothing about __set__ raising AttributeError for read-only data descriptors.

My proposal:
- use the same names for __get__ arguments throughout the documentation (both the reference and the tutorial), e.g. __get__(self, instance, owner)
- decide whether the third argument should be optional, or state the common usage in the reference, and fix accordingly the examples in the howto
- explain data, non-data and read-only descriptors in the __set__ reference, or more simply, how the defintion of __set__ affects these things.

----------
assignee: docs at python
components: Documentation
messages: 135974
nosy: davide.rizzo, docs at python
priority: normal
severity: normal
status: open
title: Harmonizing descriptor protocol documentation
versions: Python 2.7, Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12077>
_______________________________________