[issue12077] Harmonizing descriptor protocol documentation

[Raymond Hettinger]

Change by Raymond Hettinger :


--
resolution:  -> fixed
stage: needs patch -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12077] Harmonizing descriptor protocol documentation

[Raymond Hettinger]

Raymond Hettinger  added the comment:

See PR 12992 for the cross-reference from the __set__ docs to the section 
covering data and non-data descriptors.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12077] Harmonizing descriptor protocol documentation

[Raymond Hettinger]

Raymond Hettinger  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12077] Harmonizing descriptor protocol documentation

[Raymond Hettinger]

Raymond Hettinger added the comment:

I will have a chance to work on this before long.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12077] Harmonizing descriptor protocol documentation

[Martin Panter]

Martin Panter added the comment:

See Issue 23702 specifically about unbound methods in Python 3, and Issue 25435 
about general problems with the how-to in Python 3.

--
nosy: +martin.panter

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12077] Harmonizing descriptor protocol documentation

[Raymond Hettinger]

Changes by Raymond Hettinger raymond.hettin...@gmail.com:


--
assignee:  - rhettinger
priority: normal - low

___
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

[issue12077] Harmonizing descriptor protocol documentation

[Ned Batchelder]

Changes by Ned Batchelder n...@nedbatchelder.com:


--
nosy: +nedbat

___
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

[issue12077] Harmonizing descriptor protocol documentation

[Raymond Hettinger]

Changes by Raymond Hettinger raymond.hettin...@gmail.com:


--
assignee: rhettinger - 

___
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

[issue12077] Harmonizing descriptor protocol documentation

[Franck Michea]

Franck Michea added the comment:

Here is at least a correction of Descriptors' HowTo. There are two versions 
since some stuff differs (object inheritance, ...).

Here are some of my interrogations though:
 - RevealAccess is not using instance parameter, so value is shared. Is this 
intended?
 - Don't really know what to do with Function and Methods part. First I don't 
really understand the relevance of this in a descriptor how-to. Also it is know 
outdated in python3 version (unbound thing, ...), so what do?
 - In __getattribute__ function, I don't really understand the paramters given 
to __get__, why None and the instance? But this is probably my fault.

This also doesn't answer the question about the real source that should be 
kept. What to do?

I also need a proof-read, since english is not my first language... Anyway it's 
clearly not enough to be published like that

Have a nice day!

--
keywords: +patch
nosy: +kushou
versions: +Python 3.5
Added file: 
http://bugs.python.org/file29040/12077_descriptor_howto_python3.patch

___
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

[issue12077] Harmonizing descriptor protocol documentation

[Franck Michea]

Changes by Franck Michea franck.mic...@gmail.com:


Added file: 
http://bugs.python.org/file29041/12077_descriptor_howto_python2.patch

___
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

[issue12077] Harmonizing descriptor protocol documentation

[Ezio Melotti]

Changes by Ezio Melotti ezio.melo...@gmail.com:


--
type:  - enhancement
versions: +Python 3.4

___
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

[issue12077] Harmonizing descriptor protocol documentation

[Éric Araujo]

Changes by Éric Araujo mer...@netwok.org:


--
nosy: +eric.araujo

___
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

[issue12077] Harmonizing descriptor protocol documentation

[Jay Parlar]

Jay Parlar par...@gmail.com added the comment:

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, and the example showing an unbound method being returned when 
accessing a method of a class.

--

___
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

[issue12077] Harmonizing descriptor protocol documentation

[Jay Parlar]

Jay Parlar par...@gmail.com added the comment:

While working on this, I believe it would also make sense to remove all 
instances of the terms new-style and old-style from the Descriptor HowTo 
(and wherever else they might be present)

It still makes sense for them to be present in the 2.7 documentation, but 
they're concepts that don't exist in 3.x

--
nosy: +Jay.Parlar

___
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

[issue12077] Harmonizing descriptor protocol documentation

[Ezio Melotti]

Changes by Ezio Melotti ezio.melo...@gmail.com:


--
nosy: +ezio.melotti
stage:  - needs patch

___
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

[issue12077] Harmonizing descriptor protocol documentation

[Raymond Hettinger]

Changes by Raymond Hettinger raymond.hettin...@gmail.com:


--
assignee: docs@python - rhettinger
nosy: +rhettinger

___
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

[issue12077] Harmonizing descriptor protocol documentation

[Daniel Urban]

Changes by Daniel Urban urban.dani...@gmail.com:


--
nosy: +durban

___
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

[issue12077] Harmonizing descriptor protocol documentation

[Davide Rizzo]

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