Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
encukou merged 18 commits into python:main from encukou:abiinfo-slot
Sep 5, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
894ef3d
Add _PyUnicodeWriter_FormatV
encukou Jul 24, 2025
72349ba
Add capi test file for modsupport
encukou Jul 24, 2025
3b6aa96
Add PyABIInfo
encukou Jul 24, 2025
c015606
Add _Py_INTERNAL_ABI_SLOT (to _datetime for now)
encukou Jul 24, 2025
c5740af
Add docs
encukou Jul 29, 2025
da293e3
Add to limited API manifest
encukou Jul 29, 2025
44df416
Un-document PyABIInfo_FREETHREADING_AGNOSTIC for now
encukou Jul 29, 2025
feb428d
Blurb & What's New
encukou Jul 29, 2025
aa1eb4a
Fix docs
encukou Jul 29, 2025
b628d7d
Remove duplicated test
encukou Jul 29, 2025
4800a5d
Apply suggestions from code review
encukou Jul 30, 2025
4c9e918
Casts to avoid data loss warnings
encukou Jul 30, 2025
1b18761
Use hex literal for 3.15
encukou Aug 7, 2025
814ac60
Merge in the main branch
encukou Aug 7, 2025
f6f5b1d
Merge in the main branch
encukou Aug 26, 2025
2644080
Add example of intended usage before the API documentation
encukou Aug 26, 2025
cb0309f
Restore changelog / comments for PYTHON_API_VERSION
encukou Aug 26, 2025
7492e16
Merge branch 'main' into abiinfo-slot
encukou Sep 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions Doc/c-api/module.rst
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
162 changes: 159 additions & 3 deletions Doc/c-api/stable.rst
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down Expand Up @@ -199,6 +199,162 @@
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

Check warning on line 286 in Doc/c-api/stable.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:data reference target not found: PyFilter_Type [ref.data]

.. 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.

Check warning on line 306 in Doc/c-api/stable.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:type reference target not found: PyGILState_STATE [ref.type]
.. c:macro:: PyABIInfo_INTERNAL

Check warning on line 308 in Doc/c-api/stable.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:data reference target not found: PyGetSetDescr_Type [ref.data]
Specifies ABI specific to a particular build of CPython.
Internal use only.

Free-threading compatibility -- one of:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We're still planning to get rid of these options once FT is merged, right? Maybe we ought to use abiflags here (i.e. a string) instead, for future extensibility? This isn't going to be checked anywhere that it needs to be bitflags.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How would you encode being compatible with both GIL and FT?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO, we can remove them when there are no GIL-only extensions around any more. That would be a lot of time after FT is the only option.


.. 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).

Check warning on line 341 in Doc/c-api/stable.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:data reference target not found: PyListIter_Type [ref.data]
Comment on lines +340 to +341
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems easier for us to just check this on our side than to expect users to get it right?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And isn't the legacy value 1 rather than 3?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, users should use PyABIInfo_DEFAULT_ABI_VERSION or PyABIInfo_VAR -- those are our side too.
I prefer the data to be simpler, but if you want, we can keep the exception in.

The legacy value is 3. (Not that it matters that much; it's always compared to a Python version.)


Check warning on line 342 in Doc/c-api/stable.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:data reference target not found: PyListRevIter_Type [ref.data]
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


Check warning on line 357 in Doc/c-api/stable.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:data reference target not found: PyLongRangeIter_Type [ref.data]
.. _limited-api-list:

Contents of Limited API
Expand Down
3 changes: 3 additions & 0 deletions Doc/data/stable_abi.dat
View file Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 3 additions & 0 deletions Doc/using/configure.rst
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
5 changes: 5 additions & 0 deletions Doc/whatsnew/3.15.rst
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -666,6 +666,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
----------------------
Expand Down
12 changes: 12 additions & 0 deletions Include/cpython/modsupport.h
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
6 changes: 6 additions & 0 deletions Include/internal/pycore_unicodeobject.h
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down
66 changes: 66 additions & 0 deletions Include/modsupport.h
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
5 changes: 4 additions & 1 deletion Include/moduleobject.h
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 */
Expand Down
Loading
Loading

AltStyle によって変換されたページ (->オリジナル) /