[docs] [issue12077] Harmonizing descriptor protocol documentation

[Raymond Hettinger]

Raymond Hettinger <raymond.hettinger at gmail.com> added the comment:

[Davide]
> - use the same names for __get__ arguments throughout 
> the documentation (both the reference and the tutorial),
>  e.g. __get__(self, instance, owner)

Early on the choice of variable names diverged (including in various PEPs and in the C source).  I will harmonize where I can but the cat is out of the bag.

> - decide whether the third argument should be optional, 
> or state the common usage in the reference, and fix 
> accordingly the examples in the howto

PEP 252 specifies that it is optional.  Various builtin descriptors also make it optional (function_get, staticmethod_get, classmethod_get, and property_get).

I'm fixing the main docs and non-compliant code in PR 12992

> explain data, non-data and read-only descriptors in 
> the __set__ reference, or more simply, how the >
> defintion of __set__ affects these things.

That is reasonable.  Will add to the datamodel docs.

[Jay Parlar]
> Another problem is that the examples and text in 
> the section "Functions and Methods" is no longer 
> correct in 3.x. Namely the the references to
> unbound methods

That was fixed a good while ago.

----------

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