I don't think it really makes sense to make this a separate subsection, since there are no other subsections inside the datamodel section on instance methods. I'd just keep this as a sentence ending with a colon, personally

Same here, I'm not sure it really makes sense to make this a distinct subsection when there aren't any other subsections inside the datamodel section on builtin functions

I thought about that, and I decided by subsection because:

1. consistency with other sections (e.g., the one you highlighted above and Code Objects). In this case, I would fix some other sections, too.
2. personally, I like that (although it is a unique section).
3. if I see the summary, I immediately know the element has or does not have special attributes. More explicit.

Actually, when I opened the issue, I thought about a unique table for both attributes with a column to identify the kind, as the User-defined functions section was before your recent changes.

Those are all reasonable points! I don't mind the new subsection in the section on builtin functions too much; I'm happy for that to stay.

I do think the new subsection in the section on instance methods makes it more confusing, however. It implies that the entirety of the section on instance methods is about their special read-only attributes, except for the first paragraph. This isn't true: the final paragraph in section 3.2.8.2 has nothing to do with the special read-only methods of instance methods:

Note that the transformation from function object to instance method object happens each time the attribute is retrieved from the instance. In some cases, a fruitful optimization is to assign the attribute to a local variable and call that local variable. Also notice that this transformation only happens for user-defined functions; other callable objects (and all non-callable objects) are retrieved without transformation. It is also important to note that user-defined functions which are attributes of a class instance are not converted to bound methods; this only happens when the function is an attribute of the class.

What if do we move this paragraph to the second paragraph? This seems an explanation for the first one.

Well, what about these two paragraphs?

When an instance method object is created by retrieving a classmethod object from a class or instance, its __self__ attribute is the class itself, and its __func__ attribute is the function object underlying the class method.

When an instance method object is called, the underlying function (__func__) is called, inserting the class instance (__self__) in front of the argument list. For instance, when C is a class which contains a definition for a function f(), and x is an instance of C, calling x.f(1) is equivalent to calling C.f(x, 1).

The first paragraph is about the special read-only attributes of method objects; the second one isn't (it's about a broader topic to do with the semantics of Python methods). So maybe we should move the second paragraph out of the section about the special read-only attributes -- but that would make no sense; it's much more logical to talk about how the self reference is inserted at the beginning of the argument list after we've talked about the special __self__ attribute. The two paragraphs belong together.

For the section on instance methods, I think the existing structure -- where the special read-only attributes are discussed at the same time as other details on method semantics -- makes most sense. Unless you want to propose reworking the whole section on instance methods (which should go into a separate PR, IMO), I don't think we should add a subsection just for the read-only attributes.

it's about a broader topic to do with the semantics of Python methods

Despite this, I think that we can consider all these paragraphs as about the attributes. They talk about how the attributes work together to element (object, class, method..) to work as well. The attributes are cited a lot of time.

In first look, I understand this paragraph under attributes this way. However, I also noted some paragraphs didn't are about the attribute, but about the element. I would propose moving these paragraphs to the introduction of the section, probrably.

Another two idea are:

1. Adding a new section something like "More details", "How it works" about extra content.
2. Removing all attribute's subsection mark in the chapter

I prefer first option (although more work), but the second one also provide consistence.

Unless you want to propose reworking the whole section on instance methods (which should go into a separate PR, IMO),

Shall we do this together. Some details about it can scape me. :) I think what I told above is in this direction.

(Sorry for any confused thought. It is a brainstorm)

I'm sorry, but I still disagree that using a subsection for the Instance methods section is the right way to go there, at least the way you've currently done it in this PR :/ I'd be happy to look at a broader rewrite of that section, because I agree that consistency between the different sections is nice. But unfortunately I don't really have time to push forward on that right now (and I doubt I will until PyCon).

This attribute is present on all Python objects everywhere, and is already documented as such here: https://docs.python.org/3/library/stdtypes.html#special-attributes. Please revert this addition; there's no need to duplicate that documentation here.

In fact, I've realized that attribute definition duplication is a problem in this chapter. See __doc__ and __name__ attributes, e.g.

I'm thinking about a kind of hierarchy: a section with all common attributes and in each callable type something like "the attributes are those above plus these more: ... ". The content that you highlighted now is a good beginning in this direction. However, Reference Language must be referenced by the Library Reference. Besides, we don't have a reference to the cited content in this chapter.

Also, I found the attribute definitions in the inspect module documentation. This could be erased and added a refer to the Language Reference.

In my opinion, the Language Reference is more important than other sections. All other sections must refer to the Reference, not the contrary.

So, my suggestion is:

1. Keeping this definition (although the duplication). This helps make explicit the problem.
2. Continue this review in this chapter
3. Discussing a format to avoid duplication inside this chapter (and implement it)
4. Removing duplication outside this chapter (the section you cited and inspect, for example) and refer to it

What do you think? Any other ideas?

Yes, I've been working towards similar goals to you in my recent PRs #112781, #112933, #112735, etc. My opinions:

• For attributes that really do exist on all objects everywhere, like __class__ and __dict__, the list in stdtypes.rst is useful. We should keep the list for things like that. Maybe the list should be moved out of stdtypes.rst and into the datamodel somewhere, but that's a separate question from whether we should keep the list or not, and I think we should keep the list.
• For attributes that don't exist on all objects everywhere, like __name__ and __doc__, we should document them on the specific objects for which they exist in the datamodel, and eventually delete them from the list in stdtypes.rst. I've been working towards that in my recent PRs.
• Once all things in the big table in inspect.rst are properly documented, we should delete it from inspect.rst and point to the datamodel docs. I have it on my to-do list to file PRs to improve documentation for attributes on class objects, module objects and coroutine objects.

• For attributes that really do exist on all objects everywhere, like __class__ and __dict__, the list in stdtypes.rst is useful. We should keep the list for things like that. Maybe the list should be moved out of stdtypes.rst and into the datamodel somewhere, but that's a separate question from whether we should keep the list or not, and I think we should keep the list.

My suggestion is to put the list on The standard type hierarchy. The second paragraph already cited special attributes, so this seems like a good place to show them.

Does it make sense for you?

Some things have changed since we had this conversation in March!

Now, __class__ and __dict__ are documented as object.__class__ and object.__dict__, because they are present on all Python objects: https://docs.python.org/3/reference/datamodel.html#object.__class__, https://docs.python.org/3/reference/datamodel.html#object.__dict__. But __name__ and __doc__ are now more consistently listed for classes documented in the data model that define these attributes, and they are still listed in https://docs.python.org/3/library/stdtypes.html#special-attributes (because they do not exist on all Python objects).

All things considered, I still think it's incorrect for the __class__ attribute to be documented here, since it doesn't really add anything to the documentation at https://docs.python.org/3/reference/datamodel.html#object.__class__. So my original request remains: please get rid of this bullet point :-)

My suggestion is to put the list on The standard type hierarchy. The second paragraph already cited special attributes, so this seems like a good place to show them.

Let's have this conversation in an issue or PR elsewhere; the question doesn't really seem relevant to this PR :-) Maybe the list should be moved out of stdtypes into the datamodel, and maybe not -- whatever the case, I don't think it should be done as part of this PR :-)