2 files changed, 30 insertions, 1 deletions
diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst
index c99c7ef..a5f333e 100644
--- a/Doc/c-api/type.rst
+++ b/Doc/c-api/type.rst
@@ -50,6 +50,23 @@ Type Objects
       The return type is now ``unsigned long`` rather than ``long``.
 
 
+.. c:function:: PyObject* PyType_GetDict(PyTypeObject* type)
+
+   Return the type object's internal namespace, which is otherwise only
+   exposed via a read-only proxy (``cls.__dict__``).  This is a
+   replacement for accessing :c:member:`~PyTypeObject.tp_dict` directly.
+   The returned dictionary must be treated as read-only.
+
+   This function is meant for specific embedding and language-binding cases,
+   where direct access to the dict is necessary and indirect access
+   (e.g. via the proxy or :c:func:`PyObject_GetAttr`) isn't adequate.
+
+   Extension modules should continue to use ``tp_dict``,
+   directly or indirectly, when setting up their own types.
+
+   .. versionadded:: 3.12
+
+
 .. c:function:: void PyType_Modified(PyTypeObject *type)
 
    Invalidate the internal lookup cache for the type and all of its
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 239c191..7249cfe 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -1717,7 +1717,19 @@ and :c:type:`PyType_Type` effectively act as defaults.)
    called; it may also be initialized to a dictionary containing initial attributes
    for the type.  Once :c:func:`PyType_Ready` has initialized the type, extra
    attributes for the type may be added to this dictionary only if they don't
-   correspond to overloaded operations (like :meth:`__add__`).
+   correspond to overloaded operations (like :meth:`__add__`).  Once
+   initialization for the type has finished, this field should be
+   treated as read-only.
+
+   Some types may not store their dictionary in this slot.
+   Use :c:func:`PyType_GetDict` to retreive the dictionary for an arbitrary
+   type.
+
+   .. versionchanged:: 3.12
+
+      Internals detail: For static builtin types, this is always ``NULL``.
+      Instead, the dict for such types is stored on ``PyInterpreterState``.
+      Use :c:func:`PyType_GetDict` to get the dict for an arbitrary type.
 
    **Inheritance:**