gh-92678: Document Py_TPFLAGS_MANAGED_DICT and friends

Doc/c-api/gcsupport.rst

@@ -129,6 +129,29 @@ rules:
    The :c:func:`_PyObject_GC_TRACK` and :c:func:`_PyObject_GC_UNTRACK` macros
    have been removed from the public C API.
 
+
+.. c:function:: int _PyObject_VisitManagedDict(PyObject *self, visitproc visit, void *arg)
+
+   Visitor function for types with :const:`Py_TPFLAGS_MANAGED_DICT` bit set.
+   Call this function in :c:member:`~PyTypeObject.tp_traverse`.  The arguments
+   share the same meaning as the arguments of :c:member:`~PyTypeObject.tp_traverse`.
+   A non-zero return value indicates an error and that returned value should be
+   returned immediately.
+
+   .. warning:: This function is unstable and may change with time.
+
+   .. versionadded:: 3.11
+
+
+.. c:function:: void _PyObject_ClearManagedDict(PyObject *self)
+
+   Inquiry function for types with :const:`Py_TPFLAGS_MANAGED_DICT` bit set.
+   Call this function in :c:member:`~PyTypeObject.tp_clear`.
+
+   .. warning:: This function is unstable and may change with time.
+
+   .. versionadded:: 3.11
+
 The :c:member:`~PyTypeObject.tp_traverse` handler accepts a function parameter of this type:
 
 

Doc/c-api/typeobj.rst

@@ -1260,6 +1260,20 @@ and :c:type:`PyType_Type` effectively act as defaults.)
 
       .. versionadded:: 3.10
 
+   .. data:: Py_TPFLAGS_MANAGED_DICT
+
+      Set this bit to allow CPython to automatically manage the ``__dict__``
+      of the instances of a type.  To tell CPython to clear the managed
+      dictionary, you must call
+      :c:func:`_PyObject_VisitManagedDict` in :c:member:`~PyTypeObject.tp_traverse`
+      and :c:func:`_PyObject_ClearManagedDict` in :c:member:`~PyTypeObject.tp_clear`
+      respectively.
+
+      **Inheritance:**
+
+      ???
+
+      .. versionadded:: 3.11
 
 .. c:member:: const char* PyTypeObject.tp_doc
 

Doc/whatsnew/3.11.rst

@@ -1927,6 +1927,15 @@ Porting to Python 3.11
   paths and then modify them, finish initialization and use :c:func:`PySys_GetObject`
   to retrieve :data:`sys.path` as a Python list object and modify it directly.
 
+* CPython no longer assumes that a ``__dict__`` exists after an object. C extension
+  types with inheritance and ``__dict__`` may have MRO problems. To fix this, allow
+  CPython to manage the ``__dict__`` of instances of your type by setting
+  :const:`Py_TPFLAGS_MANAGED_DICT` in :c:member:`~PyTypeObject.tp_flags`.
+  You must call :c:func:`_PyObject_VisitManagedDict` and
+  :c:func:`_PyObject_ClearManagedDict` to support GC collection.  See the
+  respective functions for more information on how to use them.
+  (Contributed by Mark Shannon in :gh:`92678`.)
+
 Deprecated
 ----------