[docs] [issue38099] __dict__ attribute is incorrectly stated to be read-only

[Reed]

Reed <readuw at gmail.com> added the comment:

Thank you for the clarification. I didn't realize the section only referred to types, but it makes sense now that I read the documentation more carefully.

The documentation is still incorrect for certain attributes (e.g. __bases__ and __name__) as they can be mutated. For example:

    class A: pass
    A.__name__ = 'AA'

    class B(A): pass
    class C(B): pass
    C.__bases__ = (A,)

Also, this documentation is incorrectly linked to by other parts of the documentation. For example, in https://docs.python.org/3/reference/datamodel.html#the-standard-type-hierarchy, there is the sentence:

"Special attributes: __dict__ is the attribute dictionary; __class__ is the instance’s class."

__dict__ and __class__ link to the documentation about types, and yet that sentence is referring to all instances of any class (such as `A()`), not just type objects (such as `A`).

In terms of concrete improves, I would suggest:
    * Adding a section somewhere describing __dict__ and __class__ for all instances, not just types. Or change the original section to refer to all instances.

Assuming the original section is not changed to refer to all instances:
    * In the sentence "The implementation adds a few special read-only attributes to several object types", replace "object types" with "types" or "instances whose class subclasses from `type`" 
    * Replace `instance.class` with `class.class`. The phrase `instance` is confusing, as it then describes `class.__bases__`, which does explicitly use the word "class" to indicate it only applies to classes.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue38099>
_______________________________________