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 theUser-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.

Ido 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 fromfunction 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 aclassmethod 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 theself 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 discussedat 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. Removingall 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 theInstance 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 theattribute definitions in theinspect 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 andinspect, 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 instdtypes.rst is useful. We should keep the list for things like that. Maybe the list should be moved out ofstdtypes.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 instdtypes.rst. I've been working towards that in my recent PRs.
• Once all things in the big table ininspect.rst are properly documented, we should delete it frominspect.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 instdtypes.rst is useful. We should keep the list for things like that. Maybe the list should be moved out ofstdtypes.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 onThe 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 asobject.__class__ andobject.__dict__, because they are present onall 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 inhttps://docs.python.org/3/library/stdtypes.html#special-attributes (because they do not exist onall 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 athttps://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 onThe 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 :-)