[issue36743] Docs: Descript __get__ signature defined differently across the docs

[Raymond Hettinger]

Raymond Hettinger  added the comment:


New changeset c71ae1a45bd6e6d0f5aebc470b35f5a7dc0d8078 by Raymond Hettinger 
(Miss Islington (bot)) in branch '3.8':
bpo-36743: __get__ is sometimes called without the owner argument (GH-12992) 
(GH-15589)
https://github.com/python/cpython/commit/c71ae1a45bd6e6d0f5aebc470b35f5a7dc0d8078


--

___
Python tracker 

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

[issue36743] Docs: Descript __get__ signature defined differently across the docs

[Raymond Hettinger]

Change by Raymond Hettinger :


--
resolution:  -> fixed
stage: patch review -> 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

[issue36743] Docs: Descript __get__ signature defined differently across the docs

[miss-islington]

Change by miss-islington :


--
pull_requests: +15265
pull_request: https://github.com/python/cpython/pull/15589

___
Python tracker 

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

[issue36743] Docs: Descript __get__ signature defined differently across the docs

[Raymond Hettinger]

Raymond Hettinger  added the comment:


New changeset 0dac68f1e593c11612ed54af9edb865d398f3b05 by Raymond Hettinger in 
branch 'master':
bpo-36743: __get__ is sometimes called without the owner argument (#12992)
https://github.com/python/cpython/commit/0dac68f1e593c11612ed54af9edb865d398f3b05


--

___
Python tracker 

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

[issue36743] Docs: Descript __get__ signature defined differently across the docs

[Raymond Hettinger]

Raymond Hettinger  added the comment:

Collecting various factlets on this topic

PEP 252 gives the specification for the descriptor protocol: "__get__(): a 
function callable with one or two arguments that retrieves the attribute value 
from an object."

function_get, property_get, classmethod_get, and staticmethod_get all support 
calls with one or two arguments:

>>> a = A()
>>> class A:
def m(self):
return 42
@property
def p(self):
return 43
@classmethod
def c(cls):
return 44
@staticmethod
def s():
return 45

>>> a = A()
>>> vars(A)['m'].__get__(a)()
42
>>> vars(A)['m'].__get__(a, A)()
42
>>> vars(A)['p'].__get__(a)
43
>>> vars(A)['p'].__get__(a, A)
43
>>> vars(A)['c'].__get__(a)()
44
>>> vars(A)['c'].__get__(a, A)()
44
>>> vars(A)['s'].__get__(a)()
45
>>> vars(A)['s'].__get__(a, A)()
45

Python functions that comply with the specification should also do the same (as 
taught by the descriptor HOWTO).  That said, I have found multiple Python 
functions that aren't providing the None default.  I will fix those as I find 
them.

type.__getattribute__, object.__getattribute__ and super.__getattribute__ 
always call __get__ with both attributes specified:

>>> class D:
def __get__(*args):
print(args)

>>> class C:
d = D()

>>> class S(C):
def f(self):
return super().d

>>> C.d
(<__main__.D object at 0x104d967f0>, None, )
>>> C().d
(<__main__.D object at 0x104d967f0>, <__main__.C object at 0x104df77c0>, 
)
>>> S().f()
(<__main__.D object at 0x104d967f0>, <__main__.S object at 0x104df7580>, 


--

___
Python tracker 

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

[issue36743] Docs: Descript __get__ signature defined differently across the docs

[Jeroen Demeyer]

Jeroen Demeyer  added the comment:

> Perhaps the datamodel docs can be clarified to note that callers are allowed 
> to omit the third argument

That's not true in general, only when __get__ is a slot wrapper (i.e. for 
classes implemented in C). When __get__ is a Python function, nothing special 
is done, it's just a Python function.

--

___
Python tracker 

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

[issue36743] Docs: Descript __get__ signature defined differently across the docs

[Jeroen Demeyer]

Jeroen Demeyer  added the comment:

Personally, I have always found "instance" and "owner" very confusing names for 
these arguments. If you want to change the documentation, I would recommend 
changing those names too. Better names would be "obj" and "cls" or something 
like that.

--
nosy: +jdemeyer

___
Python tracker 

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

[issue36743] Docs: Descript __get__ signature defined differently across the docs

[Raymond Hettinger]

Change by Raymond Hettinger :


--
keywords: +patch
pull_requests: +12915
stage:  -> patch review

___
Python tracker 

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

[issue36743] Docs: Descript __get__ signature defined differently across the docs

[Raymond Hettinger]

Raymond Hettinger  added the comment:

Perhaps the datamodel docs can be clarified to note that callers are allowed to 
omit the third argument (which usually only makes sense when the second 
argument is not None). FWIW, section 3.3.2.3 already has an example of a direct 
call to a __get__ descriptor with only the *obj* argument.

--
assignee: docs@python -> rhettinger
versions:  -Python 2.7, Python 3.5, Python 3.6, Python 3.9

___
Python tracker 

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

[issue36743] Docs: Descript __get__ signature defined differently across the docs

[Jon Dufresne]

New submission from Jon Dufresne :

Here: https://docs.python.org/3/reference/datamodel.html#object.__get__

The __get__ signature is defined as:

object.__get__(self, instance, owner)

But here: https://docs.python.org/3/howto/descriptor.html#descriptor-protocol

It is defined as:

descr.__get__(self, obj, type=None)

It is not clear to me as a reader if all descriptors should have the owner/type 
argument default to None or if it should be required. If it should default to 
None, I think all doc examples should follow this expectation to make it clear 
to someone implementing a descriptor for the first time. As best I can tell, 
the owner/type is always passed. So perhaps the =None shouldn't be there.

Grepping the CPython code, I see lots of definitions for both required and 
optional, adding more confusion for me.

If there is a definitive answer, I'm happy to follow through by updating the 
docs.

--
assignee: docs@python
components: Documentation
messages: 341004
nosy: docs@python, jdufresne
priority: normal
severity: normal
status: open
title: Docs: Descript __get__ signature defined differently across the docs
versions: Python 2.7, Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9

___
Python tracker 

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

[issue36743] Docs: Descript __get__ signature defined differently across the docs

[Karthikeyan Singaravelan]

Change by Karthikeyan Singaravelan :


--
nosy: +rhettinger

___
Python tracker 

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