gh-137210: Add a struct, slot & function for checking an extension's ABI (GH-137212)

Co-authored-by: Steve Dower <[email protected]>

Author: encukou

Doc/c-api/module.rst

@@ -388,6 +388,28 @@ The available slot types are:
 
    .. versionadded:: 3.13
 
+.. c:macro:: Py_mod_abi
+
+   A pointer to a :c:struct:`PyABIInfo` structure that describes the ABI that
+   the extension is using.
+
+   When the module is loaded, the :c:struct:`!PyABIInfo` in this slot is checked
+   using :c:func:`PyABIInfo_Check`.
+
+   A suitable :c:struct:`!PyABIInfo` variable can be defined using the
+   :c:macro:`PyABIInfo_VAR` macro, as in:
+
+   .. code-block:: c
+
+      PyABIInfo_VAR(abi_info);
+
+      static PyModuleDef_Slot mymodule_slots[] = {
+         {Py_mod_abi, &abi_info},
+         ...
+      };
+
+   .. versionadded:: 3.15
+
 
 .. _moduledef-dynamic:
 

Doc/c-api/stable.rst

@@ -2,9 +2,9 @@
 
 .. _stable:
 
-***************
-C API Stability
-***************
+***********************
+C API and ABI Stability
+***********************
 
 Unless documented otherwise, Python's C API is covered by the Backwards
 Compatibility Policy, :pep:`387`.
@@ -199,6 +199,162 @@ This is the case with Windows and macOS releases from ``python.org`` and many
 third-party distributors.
 
 
+ABI Checking
+============
+
+.. versionadded:: next
+
+Python includes a rudimentary check for ABI compatibility.
+
+This check is not comprehensive.
+It only guards against common cases of incompatible modules being
+installed for the wrong interpreter.
+It also does not take :ref:`platform incompatibilities <stable-abi-platform>`
+into account.
+It can only be done after an extension is successfully loaded.
+
+Despite these limitations, it is recommended that extension modules use this
+mechanism, so that detectable incompatibilities raise exceptions rather than
+crash.
+
+Most modules can use this check via the :c:data:`Py_mod_abi`
+slot and the :c:macro:`PyABIInfo_VAR` macro, for example like this:
+
+.. code-block:: c
+
+   PyABIInfo_VAR(abi_info);
+
+   static PyModuleDef_Slot mymodule_slots[] = {
+      {Py_mod_abi, &abi_info},
+      ...
+   };
+
+
+The full API is described below for advanced use cases.
+
+.. c:function:: int PyABIInfo_Check(PyABIInfo *info, const char *module_name)
+
+   Verify that the given *info* is compatible with the currently running
+   interpreter.
+
+   Return 0 on success. On failure, raise an exception and return -1.
+
+   If the ABI is incompatible, the raised exception will be :py:exc:`ImportError`.
+
+   The *module_name* argument can be ``NULL``, or point to a NUL-terminated
+   UTF-8-encoded string used for error messages.
+
+   Note that if *info* describes the ABI that the current code uses (as defined
+   by :c:macro:`PyABIInfo_VAR`, for example), using any other Python C API
+   may lead to crashes.
+   In particular, it is not safe to examine the raised exception.
+
+   .. versionadded:: next
+
+.. c:macro:: PyABIInfo_VAR(NAME)
+
+   Define a static :c:struct:`PyABIInfo` variable with the given *NAME* that
+   describes the ABI that the current code will use.
+   This macro expands to:
+
+   .. code-block:: c
+
+      static PyABIInfo NAME = {
+          1, 0,
+          PyABIInfo_DEFAULT_FLAGS,
+          PY_VERSION_HEX,
+          PyABIInfo_DEFAULT_ABI_VERSION
+      }
+
+   .. versionadded:: next
+
+.. c:type:: PyABIInfo
+
+   .. c:member:: uint8_t abiinfo_major_version
+
+      The major version of :c:struct:`PyABIInfo`. Can be set to:
+
+      * ``0`` to skip all checking, or
+      * ``1`` to specify this version of :c:struct:`!PyABIInfo`.
+
+   .. c:member:: uint8_t abiinfo_minor_version
+
+      The major version of :c:struct:`PyABIInfo`.
+      Must be set to ``0``; larger values are reserved for backwards-compatible
+      future versions of :c:struct:`!PyABIInfo`.
+
+   .. c:member:: uint16_t flags
+
+      .. c:namespace:: NULL
+
+      This field is usually set to the following macro:
+
+      .. c:macro:: PyABIInfo_DEFAULT_FLAGS
+
+         Default flags, based on current values of macros such as
+         :c:macro:`Py_LIMITED_API` and :c:macro:`Py_GIL_DISABLED`.
+
+      Alternately, the field can be set to to the following flags, combined
+      by bitwise OR.
+      Unused bits must be set to zero.
+
+      ABI variant -- one of:
+
+         .. c:macro:: PyABIInfo_STABLE
+
+            Specifies that the stable ABI is used.
+
+         .. c:macro:: PyABIInfo_INTERNAL
+
+            Specifies ABI specific to a particular build of CPython.
+            Internal use only.
+
+      Free-threading compatibility -- one of:
+
+         .. c:macro:: PyABIInfo_FREETHREADED
+
+            Specifies ABI compatible with free-threading builds of CPython.
+            (That is, ones compiled with :option:`--disable-gil`; with ``t``
+            in :py:data:`sys.abiflags`)
+
+         .. c:macro:: PyABIInfo_GIL
+
+            Specifies ABI compatible with non-free-threading builds of CPython
+            (ones compiled *without* :option:`--disable-gil`).
+
+   .. c:member:: uint32_t build_version
+
+      The version of the Python headers used to build the code, in the format
+      used by :c:macro:`PY_VERSION_HEX`.
+
+      This can be set to ``0`` to skip any checks related to this field.
+      This option is meant mainly for projects that do not use the CPython
+      headers directly, and do not emulate a specific version of them.
+
+   .. c:member:: uint32_t abi_version
+
+      The ABI version.
+
+      For the Stable ABI, this field should be the value of
+      :c:macro:`Py_LIMITED_API`
+      (except if :c:macro:`Py_LIMITED_API` is ``3``; use
+      :c:expr:`Py_PACK_VERSION(3, 2)` in that case).
+
+      Otherwise, it should be set to :c:macro:`PY_VERSION_HEX`.
+
+      It can also be set to ``0`` to skip any checks related to this field.
+
+      .. c:namespace:: NULL
+
+      .. c:macro:: PyABIInfo_DEFAULT_ABI_VERSION
+
+         The value that should be used for this field, based on current
+         values of macros such as :c:macro:`Py_LIMITED_API`,
+         :c:macro:`PY_VERSION_HEX` and :c:macro:`Py_GIL_DISABLED`.
+
+   .. versionadded:: next
+
+
 .. _limited-api-list:
 
 Contents of Limited API

Doc/data/stable_abi.dat

@@ -293,6 +293,9 @@ General Options
 
 .. option:: --disable-gil
 
+   .. c:macro:: Py_GIL_DISABLED
+      :no-typesetting:
+
    Enables support for running Python without the :term:`global interpreter
    lock` (GIL): free threading build.
 

Doc/using/configure.rst

@@ -670,6 +670,11 @@ New features
   a string. See the documentation for caveats.
   (Contributed by Petr Viktorin in :gh:`131510`)
 
+* Add API for checking an extension module's ABI compatibility:
+  :c:data:`Py_mod_abi`, :c:func:`PyABIInfo_Check`, :c:macro:`PyABIInfo_VAR`
+  and :c:data:`Py_mod_abi`.
+  (Contributed by Petr Viktorin in :gh:`137210`)
+
 
 Porting to Python 3.15
 ----------------------

Doc/whatsnew/3.15.rst

@@ -24,3 +24,15 @@ typedef struct _PyArg_Parser {
 
 PyAPI_FUNC(int) _PyArg_ParseTupleAndKeywordsFast(PyObject *, PyObject *,
                                                  struct _PyArg_Parser *, ...);
+
+#ifdef Py_BUILD_CORE
+// Internal; defined here to avoid explicitly including pycore_modsupport.h
+#define _Py_INTERNAL_ABI_SLOT                             \
+    {Py_mod_abi, (void*) &(PyABIInfo) {                   \
+        .abiinfo_major_version = 1,                       \
+        .abiinfo_minor_version = 0,                       \
+        .flags = PyABIInfo_INTERNAL,                      \
+        .build_version = PY_VERSION_HEX,                  \
+        .abi_version = PY_VERSION_HEX }}                  \
+    ///////////////////////////////////////////////////////
+#endif

Include/cpython/modsupport.h

@@ -82,6 +82,12 @@ extern int _PyUnicode_FormatAdvancedWriter(
     Py_ssize_t start,
     Py_ssize_t end);
 
+/* PyUnicodeWriter_Format, with va_list instead of `...` */
+extern int _PyUnicodeWriter_FormatV(
+    PyUnicodeWriter *writer,
+    const char *format,
+    va_list vargs);
+
 /* --- UTF-7 Codecs ------------------------------------------------------- */
 
 extern PyObject* _PyUnicode_EncodeUTF7(

Include/internal/pycore_unicodeobject.h

@@ -134,6 +134,72 @@ PyAPI_FUNC(PyObject *) PyModule_FromDefAndSpec2(PyModuleDef *def,
 
 #endif /* New in 3.5 */
 
+/* ABI info & checking (new in 3.15) */
+#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030f0000
+typedef struct PyABIInfo {
+    uint8_t abiinfo_major_version;
+    uint8_t abiinfo_minor_version;
+    uint16_t flags;
+    uint32_t build_version;
+    uint32_t abi_version;
+} PyABIInfo;
+#define PyABIInfo_STABLE        0x0001
+#define PyABIInfo_GIL           0x0002
+#define PyABIInfo_FREETHREADED  0x0004
+#define PyABIInfo_INTERNAL      0x0008
+
+#define PyABIInfo_FREETHREADING_AGNOSTIC (PyABIInfo_GIL|PyABIInfo_FREETHREADED)
+
+PyAPI_FUNC(int) PyABIInfo_Check(PyABIInfo *info, const char *module_name);
+
+// Define the defaults
+#ifdef Py_LIMITED_API
+    #define _PyABIInfo_DEFAULT_FLAG_STABLE PyABIInfo_STABLE
+    #if Py_LIMITED_API == 3
+        #define PyABIInfo_DEFAULT_ABI_VERSION _Py_PACK_VERSION(3, 2)
+    #else
+        #define PyABIInfo_DEFAULT_ABI_VERSION Py_LIMITED_API
+    #endif
+#else
+    #define _PyABIInfo_DEFAULT_FLAG_STABLE 0
+    #define PyABIInfo_DEFAULT_ABI_VERSION PY_VERSION_HEX
+#endif
+#if defined(Py_LIMITED_API) && defined(_Py_OPAQUE_PYOBJECT)
+    #define _PyABIInfo_DEFAULT_FLAG_FT PyABIInfo_FREETHREADING_AGNOSTIC
+#elif defined(Py_GIL_DISABLED)
+    #define _PyABIInfo_DEFAULT_FLAG_FT PyABIInfo_FREETHREADED
+#else
+    #define _PyABIInfo_DEFAULT_FLAG_FT PyABIInfo_GIL
+#endif
+#if defined(Py_BUILD_CORE)
+    #define _PyABIInfo_DEFAULT_FLAG_INTERNAL PyABIInfo_INTERNAL
+#else
+    #define _PyABIInfo_DEFAULT_FLAG_INTERNAL 0
+#endif
+
+#define PyABIInfo_DEFAULT_FLAGS (                           \
+        _PyABIInfo_DEFAULT_FLAG_STABLE                      \
+        | _PyABIInfo_DEFAULT_FLAG_FT                        \
+        | _PyABIInfo_DEFAULT_FLAG_INTERNAL                  \
+    )                                                       \
+    /////////////////////////////////////////////////////////
+
+#define _PyABIInfo_DEFAULT() {                              \
+        1, 0,                                               \
+        PyABIInfo_DEFAULT_FLAGS,                            \
+        PY_VERSION_HEX,                                     \
+        PyABIInfo_DEFAULT_ABI_VERSION }                     \
+    /////////////////////////////////////////////////////////
+
+#define PyABIInfo_VAR(NAME) \
+    static PyABIInfo NAME = _PyABIInfo_DEFAULT;
+
+#undef _PyABIInfo_DEFAULT_STABLE
+#undef _PyABIInfo_DEFAULT_FT
+#undef _PyABIInfo_DEFAULT_INTERNAL
+
+#endif /* ABI info (new in 3.15) */
+
 #ifndef Py_LIMITED_API
 #  define Py_CPYTHON_MODSUPPORT_H
 #  include "cpython/modsupport.h"

Include/modsupport.h

@@ -81,10 +81,13 @@ struct PyModuleDef_Slot {
 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030d0000
 #  define Py_mod_gil 4
 #endif
+#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= _Py_PACK_VERSION(3, 15)
+#  define Py_mod_abi 5
+#endif
 
 
 #ifndef Py_LIMITED_API
-#define _Py_mod_LAST_SLOT 4
+#define _Py_mod_LAST_SLOT 5
 #endif
 
 #endif /* New in 3.5 */