New submission from Davide Rizzo <sor...@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@python
components: Documentation
messages: 135974
nosy: davide.rizzo, docs@python
priority: normal
severity: normal
status: open
title: Harmonizing descriptor protocol documentation
versions: Python 2.7, Python 3.2, Python 3.3
_______________________________________
Python tracker <rep...@bugs.python.org>
<http://bugs.python.org/issue12077>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
