gh-95245: Document Py_TPFLAGS_PREHEADER (GH-135861)

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 060d6f60174b41af41d5d67779dbbf21988c726e..8bd3144f88aa71aec18c5aa6ff66d792cd239290 100644 (file)
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -1286,6 +1286,19 @@ and :c:data:`PyType_Type` effectively act as defaults.)
       :c:member:`~PyTypeObject.tp_weaklistoffset` field is set in a superclass.
 
 
+   .. c:macro:: Py_TPFLAGS_PREHEADER
+
+      These bits indicate that the VM will manage some fields by storing them
+      before the object. Currently, this macro is equivalent to
+      :c:expr:`Py_TPFLAGS_MANAGED_DICT | Py_TPFLAGS_MANAGED_WEAKREF`.
+
+      This macro value relies on the implementation of the VM, so its value is not
+      stable and may change in a future version. Prefer using individual
+      flags instead.
+
+      .. versionadded:: 3.12
+
+
    .. c:macro:: Py_TPFLAGS_ITEMS_AT_END
 
       Only usable with variable-size types, i.e. ones with non-zero

diff --git a/Include/object.h b/Include/object.h
index b1bcc9481871b4c55c941bef662cfcb93de9f590..8979ac7dd095a4277271ab8548ed4e762ace4cc1 100644 (file)
--- a/Include/object.h
+++ b/Include/object.h
@@ -550,6 +550,9 @@ given type object has a specified feature.
  */
 #define Py_TPFLAGS_MANAGED_DICT (1 << 4)
 
+/* Type has dictionary or weakref pointers that are managed by VM and has
+ * to allocate space to store these.
+ */
 #define Py_TPFLAGS_PREHEADER (Py_TPFLAGS_MANAGED_WEAKREF | Py_TPFLAGS_MANAGED_DICT)
 
 /* Set if instances of the type object are treated as sequences for pattern matching */