Manifest, annotations

Author: encukou

Doc/c-api/module.rst

@@ -685,6 +685,11 @@ remove it.
    Usually, there is only one variable of this type for each extension module
    defined this way.
 
+   In the :ref:`Stable ABI <stable-abi>` for Free-Threaded Builds (``abi3t``),
+   this struct is opaque, and unusable in practice.
+   The struct, including all members, is part of Stable ABI for
+   non-free-threaded builds (``abi3``).
+
    .. c:member:: PyModuleDef_Base m_base
 
       Always initialize this member to :c:macro:`PyModuleDef_HEAD_INIT`:
@@ -695,6 +700,11 @@ remove it.
 
          The type of :c:member:`!PyModuleDef.m_base`.
 
+         In the :ref:`Stable ABI <stable-abi>` for Free-Threaded Builds
+         (``abi3t``), this struct is opaque, and unusable in practice.
+         The struct is part of Stable ABI for
+         non-free-threaded builds (``abi3``).
+
       .. c:macro:: PyModuleDef_HEAD_INIT
 
          The required initial value for :c:member:`!PyModuleDef.m_base`.

Doc/c-api/structures.rst

@@ -33,6 +33,13 @@ under :ref:`reference counting <countingrefs>`.
    The members must not be accessed directly; instead use macros such as
    :c:macro:`Py_REFCNT` and :c:macro:`Py_TYPE`.
 
+   In the :ref:`Stable ABI <stable-abi>` for Free-Threaded Builds (``abi3t``),
+   this struct is opaque; its size and layout may change between
+   Python versions.
+   In Stable ABI for non-free-threaded builds (``abi3``), the
+   :c:member:`!ob_refcnt` and :c:member:`!ob_type` fields are available,
+   but using them directly is discouraged.
+
    .. c:member:: Py_ssize_t ob_refcnt
 
       The object's reference count, as returned by :c:macro:`Py_REFCNT`.
@@ -72,6 +79,19 @@ under :ref:`reference counting <countingrefs>`.
    instead use macros such as :c:macro:`Py_SIZE`, :c:macro:`Py_REFCNT` and
    :c:macro:`Py_TYPE`.
 
+   In the :ref:`Stable ABI <stable-abi>` for Free-Threaded Builds (``abi3t``),
+   this struct is opaque; its size and layout may change between
+   Python versions.
+   In Stable ABI for non-free-threaded builds (``abi3``), the
+   :c:member:`!ob_base` and :c:member:`!ob_size` fields are available,
+   but using them directly is discouraged.
+
+   .. c:member:: PyObject ob_base
+
+      Common object header.
+      Typically, this field is not accessed directly; instead
+      :c:type:`!PyVarObject` can be cast to :c:type:`PyObject`.
+
    .. c:member:: Py_ssize_t ob_size
 
       A size field, whose contents should be considered an object's internal

Doc/data/stable_abi.dat

@@ -249,18 +249,17 @@ def _stable_abi_annotation(
         reftype="ref",
         refexplicit="False",
     )
-    struct_abi_kind = record.struct_abi_kind
-    if struct_abi_kind in {"opaque", "members"}:
-        ref_node += nodes.Text(sphinx_gettext("Limited API"))
-    else:
-        ref_node += nodes.Text(sphinx_gettext("Stable ABI"))
+    ref_node += nodes.Text(sphinx_gettext("Stable ABI"))
     emph_node += ref_node
+    struct_abi_kind = record.struct_abi_kind
     if struct_abi_kind == "opaque":
         emph_node += nodes.Text(" " + sphinx_gettext("(as an opaque struct)"))
     elif struct_abi_kind == "full-abi":
         emph_node += nodes.Text(
             " " + sphinx_gettext("(including all members)")
         )
+    elif struct_abi_kind in {"members", "abi3t-opaque"}:
+        emph_node += nodes.Text(" " + sphinx_gettext("(see below)"))
     if record.ifdef_note:
         emph_node += nodes.Text(f" {record.ifdef_note}")
     if stable_added == "3.2":
@@ -271,11 +270,7 @@ def _stable_abi_annotation(
             " " + sphinx_gettext("since version %s") % stable_added
         )
     emph_node += nodes.Text(".")
-    if struct_abi_kind == "members":
-        msg = " " + sphinx_gettext(
-            "(Only some members are part of the stable ABI.)"
-        )
-        emph_node += nodes.Text(msg)
+
     return emph_node
 
 

Doc/tools/extensions/c_annotations.py

@@ -1,4 +1,4 @@
-# This file lists the contents of the Limited API and Stable ABI.
+# This file lists the contents of Limited API and Stable ABI.
 # Please append new items at the end.
 
 # The syntax of this file is not fixed.
@@ -46,15 +46,24 @@
 #   - 'opaque': No members are part of the ABI, nor is the size. The Limited
 #     API only handles these via pointers. The C definition should be
 #     incomplete (opaque).
-#   - 'members': Only specific members are part of the stable ABI.
-#     The struct's size may change, so it can't be used in arrays.
+#   - 'abi3t-opaque': 'full-abi' in abi3; 'opaque' in abi3t.
+#     For docs, the generated annotation refers to details that need to
+#     be added to the ReST file manually.
+#   - 'members':
+#     - 'opaque' in abi3t.
+#     - In abi3, only specific members are part of the stable ABI.
+#       The struct's size may change, so it can't be used in arrays.
 #     Do not add new structs of this kind without an extremely good reason.
+#     For docs, the generated annotation refers to details that need to
+#     be added to the ReST file manually.
 # - members: For `struct` with struct_abi_kind = 'members', a list of the
 #   exposed members.
 # - doc: for `feature_macro`, the blurb added in documentation
 # - windows: for `feature_macro`, this macro is defined on Windows.
 #   (This info is used to generate the DLL manifest and needs to be available
 #   on all platforms.)
+# - abi3t_opaque: In abi3t, this struct is opaque (as if `struct_abi_kind`
+#   was 'opaque' and `members` was missing).
 
 # Removing items from this file is generally not allowed, and additions should
 # be considered with that in mind. See the devguide for exact rules:
@@ -107,10 +116,10 @@
     struct_abi_kind = 'full-abi'
 [struct.PyModuleDef_Base]
     added = '3.2'
-    struct_abi_kind = 'full-abi'
+    struct_abi_kind = 'abi3t-opaque'
 [struct.PyModuleDef]
     added = '3.2'
-    struct_abi_kind = 'full-abi'
+    struct_abi_kind = 'abi3t-opaque'
 [struct.PyStructSequence_Field]
     added = '3.2'
     struct_abi_kind = 'full-abi'