The __dict__ attribute of class objects is documented as being a (standard) dictionary, but implemented with a proxy object. I propose to clarify the documentation in “Custom classes” under <https://docs.python.org/3.5/reference/datamodel.html#the-standard-type-hierarchy>, and in <https://docs.python.org/3.5/library/functions.html#type>.

I believe my changes are also applicable to Python 2, as long as I point out the proxy is specific to “new-style” classes.

Isn't the fact that it's read-only a CPython implementation detail? That is, shouldn't that just read: 

"gives a :term:`mapping` object representing the class's namespace"

so as to not enforce anything on any other implementations?

I don’t know if it is an implementation detail or not. Maybe it is the documentation itself which defines that. Anyway, I think your wording would have been fine for my original problem.

I wonder if we should clarify that only reading the mapping is supported, even if we don’t define any particular behaviour for modifying it (like updating the namespace, raising an exception, ignoring the change, etc).

I believe the docs defined that, usually using a bold "CPython implementation detail" sentence.

It seems like it's something that would be considered an implementation detail, though, according to Raymond's answer here: http://stackoverflow.com/questions/32720492/why-is-a-class-dict-a-mappingproxy

Changing it to just state it's a mapping definitely looks like the safest option.

The patch would still apply to Doc/library/functions.rst.


https://docs.python.org/3.10/reference/datamodel.html#the-standard-type-hierarchy  seems to have been changed quite a lot, but still has:

1. "Special read-only attribute: __dict__ is the module’s namespace as a dictionary object."


2. "__dict__
The dictionary containing the class’s namespace."

From what I can see, the original patch changed

... and the *dict* dictionary is the namespace containing definitions for class body and is copied to a standard dictionary to become the __dict__ attribute

into this

... and the *dict* dictionary is copied to the namespace containing definitions for the class body, which is referenced by the __dict__ attribute

so that the documentation avoids saying that the attribute is a dictionary, instead saying it just references a dictionary. However, current documentation says that

... it may be copied or wrapped before becoming the __dict__ attribute

which implies some sort of change already. In this case, is the patch for the functions page still applicable?

Thank you Stanley, I agree that this is no longer needed.