classification
Title: __set_name__ documentation not clear about its usage with non-descriptor classes
Type: Stage: resolved
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: docs@python, miss-islington, rhettinger, xitop
Priority: normal Keywords: patch

Created on 2021-09-14 16:40 by xitop, last changed 2021-09-18 13:06 by rhettinger. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 28439 merged rhettinger, 2021-09-18 01:04
PR 28444 merged miss-islington, 2021-09-18 06:49
Messages (4)
msg401785 - (view) Author: (xitop) Date: 2021-09-14 16:40
The object.__set_name__() function (introduced in Python 3.6 by PEP-487) is mentioned in the "what's new " summary as an extension to the descriptor protocol [1] and documented in the "implementing descriptors" section [2].

However, the PEP itself states that it "adds an __set_name__ initializer for class attributes, especially if they are descriptors.". And it indeed works for plain classes where the descriptor protocol is not used at all (no __get__ or __set__ or __delete__):

----
class NotDescriptor:
    def __set_name__(self, owner, name):
        print('__set_name__ called')
            
class SomeClass:
    attr = NotDescriptor()
----

It is clear that this method is helpful when used in descriptors and that is its intended use, but other valid use-cases probably exist.

I suggest to amend the documentation to clarify that (correct me if I'm wrong) the __set_name__ is called for every class used as an attribute in an other class, not only for descriptors.

---

URLs:

[1]: https://docs.python.org/3/whatsnew/3.6.html#pep-487-descriptor-protocol-enhancements

[2]: https://docs.python.org/3/reference/datamodel.html#implementing-descriptors
msg401852 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2021-09-15 16:33
You are correct that __set_name__ works for non-descriptor classes as well.

The docs for it should be moved out of the "Implementing Descriptors" section.  Also, it should have a non-descriptor example.
msg402123 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2021-09-18 06:49
New changeset 94b462686b7dfabbd69cc9401037d736d71c4dc2 by Raymond Hettinger in branch 'main':
bpo-45198: __set_name__ documentation not clear about its usage with non-descriptor classes (GH-28439)
https://github.com/python/cpython/commit/94b462686b7dfabbd69cc9401037d736d71c4dc2
msg402124 - (view) Author: miss-islington (miss-islington) Date: 2021-09-18 07:10
New changeset 7ab114bf1fa0f28ee267a4c69e597cc49a186a14 by Miss Islington (bot) in branch '3.10':
bpo-45198: __set_name__ documentation not clear about its usage with non-descriptor classes (GH-28439)
https://github.com/python/cpython/commit/7ab114bf1fa0f28ee267a4c69e597cc49a186a14
History
Date User Action Args
2021-09-18 13:06:35rhettingersetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2021-09-18 07:10:07miss-islingtonsetmessages: + msg402124
2021-09-18 06:49:52miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request26847
2021-09-18 06:49:46rhettingersetmessages: + msg402123
2021-09-18 01:04:05rhettingersetkeywords: + patch
stage: patch review
pull_requests: + pull_request26844
2021-09-15 16:33:42rhettingersetversions: + Python 3.10, Python 3.11, - Python 3.6, Python 3.7, Python 3.8
nosy: + rhettinger

messages: + msg401852

assignee: docs@python -> rhettinger
2021-09-14 16:40:25xitopcreate