[New-bugs-announce] [issue36743] Docs: Descript __get__ signature defined differently across the docs

[Jon Dufresne]

New submission from Jon Dufresne <jon.dufresne at gmail.com>:

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 at python
components: Documentation
messages: 341004
nosy: docs at 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 <report at bugs.python.org>
<https://bugs.python.org/issue36743>
_______________________________________