Repository navigation
Harmonizing descriptor protocol documentation #56286
Description
| BPO | 12077 |
|---|---|
| Nosy | @rhettinger, @nedbat, @ezio-melotti, @merwok, @durban, @sorcio, @vadmium |
| Files |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = 'https://github.com/rhettinger'
closed_at = <Date 2019-08-29.08:29:30.896>
created_at = <Date 2011-05-14.13:56:25.249>
labels = ['type-feature', 'docs']
title = 'Harmonizing descriptor protocol documentation'
updated_at = <Date 2019-08-29.08:29:30.896>
user = 'https://github.com/sorcio'bugs.python.org fields:
activity = <Date 2019-08-29.08:29:30.896>
actor = 'rhettinger'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2019-08-29.08:29:30.896>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2011-05-14.13:56:25.249>
creator = 'davide.rizzo'
dependencies = []
files = ['29040', '29041']
hgrepos = []
issue_num = 12077
keywords = ['patch']
message_count = 8.0
messages = ['135974', '136172', '136295', '181915', '293161', '293164', '350724', '350728']
nosy_count = 10.0
nosy_names = ['rhettinger', 'nedbat', 'ezio.melotti', 'eric.araujo', 'daniel.urban', 'docs@python', 'davide.rizzo', 'Jay.Parlar', 'martin.panter', 'franck']
pr_nums = []
priority = 'low'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue12077'
versions = ['Python 2.7', 'Python 3.2', 'Python 3.3', 'Python 3.4', 'Python 3.5']
Activity
sorcio commentedon May 14, 2011
There are three sources of information for the descriptor protocol:
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:
JayParlar commentedon May 17, 2011
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
JayParlar commentedon May 19, 2011
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.
franck commentedon Feb 11, 2013
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:
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!
vadmium commentedon May 6, 2017
See bpo-23702 specifically about unbound methods in Python 3, and bpo-25435 about general problems with the how-to in Python 3.
rhettinger commentedon May 6, 2017
I will have a chance to work on this before long.
rhettinger commentedon Aug 29, 2019
[Davide]
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.
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
That is reasonable. Will add to the datamodel docs.
[Jay Parlar]
That was fixed a good while ago.
rhettinger commentedon Aug 29, 2019
See PR 12992 for the cross-reference from the __set__ docs to the section covering data and non-data descriptors.