__set_name__ documentation not clear about its usage with non-descriptor classes

[xitop]

BPO	45198
Nosy	@rhettinger, @pablogsal, @miss-islington
PRs	bpo-45198: __set_name__ documentation not clear about its usage with non-descriptor classes #28439 [3.10] bpo-45198: __set_name__ documentation not clear about its usage with non-descriptor classes (GH-28439) #28444

^{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 2021-09-18.13:06:35.228>
created_at = <Date 2021-09-14.16:40:25.057>
labels = ['3.11', '3.9', '3.10', 'docs']
title = '__set_name__ documentation not clear about its usage with non-descriptor classes'
updated_at = <Date 2021-10-04.19:18:41.534>
user = 'https://bugs.python.org/xitop'

bugs.python.org fields:

activity = <Date 2021-10-04.19:18:41.534>
actor = 'pablogsal'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2021-09-18.13:06:35.228>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2021-09-14.16:40:25.057>
creator = 'xitop'
dependencies = []
files = []
hgrepos = []
issue_num = 45198
keywords = ['patch']
message_count = 5.0
messages = ['401785', '401852', '402123', '402124', '403148']
nosy_count = 5.0
nosy_names = ['rhettinger', 'docs@python', 'pablogsal', 'xitop', 'miss-islington']
pr_nums = ['28439', '28444']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue45198'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

[xitop]

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:

[rhettinger]

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.