note mutating tp_dict is bad (closes #12719)

diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 4a6335c8698962d9a7a81f0749861f99543014b6..68ca9adaa9b02834458c2085aa85564d99f1d656 100644 (file)
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -745,6 +745,11 @@ type objects) *must* have the :attr:`ob_size` field.
    This field is not inherited by subtypes (though the attributes defined in here
    are inherited through a different mechanism).
 
+   .. warning::
+
+      It is not safe to use :c:func:`PyDict_SetItem` on or otherwise modify
+      :attr:`tp_dict` with the dictionary C-API.
+
 
 .. c:member:: descrgetfunc PyTypeObject.tp_descr_get