gh-146636: PEP 803: Reference documentation by encukou · Pull Request #148013 · python/cpython

encukou · 2026-04-02T14:17:02Z

Issue: Implement PEP 803 -- abi3t #146636

📚 Documentation preview 📚: https://cpython-previews--148013.org.readthedocs.build/

Doc/whatsnew/3.15.rst

ZeroIntensity

Congrats on the PEP acceptance :)

Mostly editorial comments from me. The content generally looks good.

ZeroIntensity · 2026-04-02T14:32:32Z

Doc/c-api/module.rst

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


Why is "Free-Threaded Builds" in title case, but then "non-free-threaded builds" isn't?

ZeroIntensity · 2026-04-02T14:36:17Z

Doc/c-api/stable.rst


-.. c:macro:: Py_LIMITED_API
+- ``abi3``, introduced in Pyton 3.2, is compatible with
+  **non**-:term:`free threaded <free-threaded build>` builds of CPython.


Nitpicky, but I believe "free threaded" needs a dash here. In the original issue where we added the "free-threaded build" term (#144277), we determined that no dash was correct only when "free threaded" was a noun.

ZeroIntensity · 2026-04-02T14:45:47Z

Doc/c-api/stable.rst

+Note that compiling for Stable ABI is *not* a complete guarantee that code will
+be compatible with the expected Python versions.
+Stable ABI prevents *ABI* issues, like linker errors due to missing


I think we need to precede "Stable ABI" with "the"?

Suggested change

Note that compiling for Stable ABI is *not* a complete guarantee that code will

be compatible with the expected Python versions.

Stable ABI prevents *ABI* issues, like linker errors due to missing

Note that compiling for the Stable ABI is *not* a complete guarantee that code will

be compatible with the expected Python versions.

The Stable ABI prevents *ABI* issues, like linker errors due to missing

Even if there's two of them?

Yeah, not too sure about the rules here. What about "the Stable ABIs"?

ZeroIntensity · 2026-04-02T14:51:25Z

Doc/c-api/stable.rst

+symbols or data corruption due to changes in structure layouts or function
+signatures.
+However, other changes in Python can change the *behavior* of extensions.
+See Python's Backwards Compatibility Policy (:pep:`387`) for details.


This sentence confused me a little when I first read it. I had read it as "We might change the behavior of extensions -- go read our backward compatibility policy if you want to know what", but then we provide an example right after the reader was diverted. Could we move this sentence to after the following paragraph, or put it in a seealso note?

ZeroIntensity · 2026-04-02T14:54:17Z

Doc/whatsnew/3.15.rst

+C extensions that target the :ref:`Stable ABI <stable-abi>` can now be
+compiled for the new *Stable ABI for Free-Threaded Builds* (also known
+as ``abi3t``), which makes them compatible with
+:term:`free-threaded build <free-threaded build>` builds of CPython.


Suggested change

:term:`free-threaded build <free-threaded build>` builds of CPython.

:term:`free-threaded <free-threaded build>` builds of CPython.

ZeroIntensity · 2026-04-02T14:57:07Z

Doc/whatsnew/3.15.rst

+  part of the instance struct; and
+- Switching from a ``PyInit_`` function to a new export hook,
+  :c:func:`PyModExport_* <PyModExport_modulename>`, introduced for this
+  purpose in :pep:`903`.


Suggested change

purpose in :pep:`903`.

purpose in :pep:`803`.

ZeroIntensity · 2026-04-02T14:58:14Z

Doc/whatsnew/3.15.rst

+  :c:func:`PyModExport_* <PyModExport_modulename>`, introduced for this
+  purpose in :pep:`903`.
+
+Note that Stable ABI does not offer all functionality CPython has to offer.


Suggested change

Note that Stable ABI does not offer all functionality CPython has to offer.

Note that the Stable ABI does not offer all the functionality that CPython has to offer.

Or if you don't like "the" before "Stable ABI":

Suggested change

Note that Stable ABI does not offer all functionality CPython has to offer.

Note that Stable ABI does not offer all the functionality that CPython has to offer.

ZeroIntensity · 2026-04-02T15:00:06Z

Doc/whatsnew/3.15.rst

+be selected in a build tool (such as Setuptools, ``meson-python``, Cython,
+Scikit-build-core, Maturin, and similar).


Is it intentional that meson-python is the only package in a code block here?

ZeroIntensity · 2026-04-02T15:00:33Z

Doc/whatsnew/3.15.rst

+be selected in a build tool (such as Setuptools, ``meson-python``, Cython,
+Scikit-build-core, Maturin, and similar).
+At the time of writing this entry, these tools did **not** support ``abi3t``.
+If this is the case for "your" tool, compile for ``cp315t`` separately.


Hm, why is "your" in quotes?

Doc/whatsnew/3.15.rst

StanFromIreland · 2026-04-02T15:47:41Z

The new check caught removals: https://github.com/python/cpython/actions/runs/23907059205/job/69719041532?pr=148013 (and on your PR out of everyone's ;-)

hugovk · 2026-04-03T09:00:11Z

Doc/c-api/stable.rst

+There are two Stable ABIs:

-.. c:macro:: Py_LIMITED_API
+- ``abi3``, introduced in Pyton 3.2, is compatible with


Suggested change

- ``abi3``, introduced in Pyton 3.2, is compatible with

- ``abi3``, introduced in Python 3.2, is compatible with

hugovk · 2026-04-03T09:00:19Z

Doc/c-api/stable.rst


-   Define this macro before including ``Python.h`` to opt in to only use
-   the Limited API, and to select the Limited API version.
+- ``abi3t``, introduced in Pyton 3.15, is compatible with


Suggested change

- ``abi3t``, introduced in Pyton 3.15, is compatible with

- ``abi3t``, introduced in Python 3.15, is compatible with

Doc/c-api/stable.rst

hugovk · 2026-04-03T09:06:55Z

Doc/c-api/stable.rst

-   signatures.
-   However, other changes in Python can change the *behavior* of extensions.
-   See Python's Backwards Compatibility Policy (:pep:`387`) for details.
+   When using a build tool (for example, ``setuptools``), the tool is


Suggested change

When using a build tool (for example, ``setuptools``), the tool is

When using a build tool (for example, Setuptools), the tool is

hugovk · 2026-04-03T09:08:43Z

Doc/c-api/stable.rst

+Typically, you should choose a specific value rather than the version of
+the Python headers you are compiling against.
+
+The macro(s) must be defined before including ``Python.h``.


"(s)" is a bit awkward, prefer a generic singular or plural:

Suggested change

The macro(s) must be defined before including ``Python.h``.

The macros must be defined before including ``Python.h``.

hugovk · 2026-04-03T09:14:39Z

Doc/c-api/stable.rst

+.. c:macro:: Py_TARGET_ABI3T
+
+   Target ``abi3t``, that is,
+   :term:`free-threaded <free-threaded build>` builds of CPython.


Suggested change

:term:`free-threaded <free-threaded build>` builds of CPython.

:term:`free-threaded builds <free-threaded build>` of CPython.

hugovk · 2026-04-03T09:15:01Z

Doc/c-api/stable.rst


-Limited API Scope and Performance
---------------------------------
+On a a :term:`free-threaded build` -- that is, when


Suggested change

On a a :term:`free-threaded build` -- that is, when

On a :term:`free-threaded build` -- that is, when

hugovk · 2026-04-03T09:18:20Z

Doc/whatsnew/3.15.rst

+C extensions that target the :ref:`Stable ABI <stable-abi>` can now be
+compiled for the new *Stable ABI for Free-Threaded Builds* (also known
+as ``abi3t``), which makes them compatible with
+:term:`free-threaded <free-threaded build>` builds of CPython.


Suggested change

:term:`free-threaded <free-threaded build>` builds of CPython.

:term:`free-threaded builds <free-threaded build>` of CPython.

hugovk · 2026-04-03T09:20:08Z

Doc/whatsnew/3.15.rst

+
+Stable ABI for Free-Threaded Builds should typically
+be selected in a build tool (such as Setuptools, meson-python, Cython,
+Scikit-build-core, Maturin, and similar).


Don't really need "and similar" after "such as".

Suggested change

Scikit-build-core, Maturin, and similar).

scikit-build-core, Maturin).

hugovk · 2026-04-03T09:20:21Z

Doc/whatsnew/3.15.rst

+Stable ABI for Free-Threaded Builds should typically
+be selected in a build tool (such as Setuptools, meson-python, Cython,
+Scikit-build-core, Maturin, and similar).
+At the time of writing this entry, these tools did **not** support ``abi3t``.


Suggested change

At the time of writing this entry, these tools did **not** support ``abi3t``.

At the time of writing, these tools did **not** support ``abi3t``.

ngoldbaum

Thanks for putting this together! I left a few comments inline, please take them or leave them as you see fit.

ngoldbaum · 2026-04-03T17:22:37Z

Doc/c-api/module.rst

   defined this way.

+   In the :ref:`Stable ABI <stable-abi>` for free-threaded builds (``abi3t``),
+   this struct is opaque, and unusable in practice.


This is all covered above, but for people who land here with a direct link to this section, you could add a cross-reference suggesting the PyModExport API instead?

ngoldbaum · 2026-04-03T17:25:28Z

Doc/c-api/stable.rst

+   When using a build tool (for example, ``setuptools``), the tool is
+   generally responsible for setting macros and synchronizing them with
+   extension filenames and other metadata.
+   Prefer using the tool's options over defining the macros manually.


Maybe setuptools is a poor example to use above then? Because setuptools expects users to set the build flags manually...

You could delete the "(For example, SetupTools)" above, or maybe refer to meson-python or scikit-build-core instead? These days that's what I recommend to people depending on if they already use CMake or not.

ngoldbaum · 2026-04-03T17:27:47Z

Doc/c-api/stable.rst

+
+   Target ``abi3t``, that is,
+   :term:`free-threaded <free-threaded build>` builds of CPython.
+   See :ref:`above <abi3-compiling>` for common information.


Maybe add "The free-threaded and GIL-enabled can both load abi3t extensions".

ngoldbaum · 2026-04-03T17:30:27Z

Doc/c-api/stable.rst


-The goal for the Limited API is to allow everything that is possible with the
+- define both :c:macro:`!Py_LIMITED_API` and :c:macro:`!Py_TARGET_ABI3T`, or
+- define only :c:macro:`!Py_LIMITED_API` and build for free-threaded Python.


Suggested change

- define only :c:macro:`!Py_LIMITED_API` and build for free-threaded Python.

- Define only :c:macro:`!Py_LIMITED_API` and define :c:macro:`!Py_GIL_DISABLED`.

This happens automatically with a free-threaded interpreter, except on Windows.

ngoldbaum · 2026-04-03T17:34:45Z

Doc/whatsnew/3.15.rst

+free-threading (``cp315t``) separately.
+
+Stable ABI for Free-Threaded Builds should typically
+be selected in a build tool (such as Setuptools, meson-python, Cython,


Maybe split this between build backends and bindings generators? Both probably need configuration.

It's a little confusing to group Cython in with meson-python.

encukou added 3 commits April 2, 2026 15:03

abi3t docs

8e203eb

Manifest, annotations

c1d7fef

Fixup

f83f6b4

encukou requested review from AA-Turner, ZeroIntensity, ericsnowcurrently and hugovk as code owners April 2, 2026 14:17

bedevere-app bot added the awaiting core review label Apr 2, 2026

bedevere-app bot mentioned this pull request Apr 2, 2026

Implement PEP 803 -- abi3t #146636

Open

8 tasks

AIdjis reviewed Apr 2, 2026

View reviewed changes

Doc/whatsnew/3.15.rst Outdated Show resolved Hide resolved

AIdjis reviewed Apr 2, 2026

View reviewed changes

Doc/whatsnew/3.15.rst Outdated Show resolved Hide resolved

I'm not good with numbers

b3e31c6

ZeroIntensity reviewed Apr 2, 2026

View reviewed changes

encukou added 3 commits April 3, 2026 10:53

Merge in the main branch

2372da9

Address review

b3799de

Add a blurb for the PEP

3bc47ee

hugovk reviewed Apr 3, 2026

View reviewed changes

ngoldbaum reviewed Apr 3, 2026

View reviewed changes

	:term:`free-threaded build <free-threaded build>` builds of CPython.
	:term:`free-threaded <free-threaded build>` builds of CPython.

	Note that Stable ABI does not offer all functionality CPython has to offer.
	Note that the Stable ABI does not offer all the functionality that CPython has to offer.

		be selected in a build tool (such as Setuptools, ``meson-python``, Cython,
		Scikit-build-core, Maturin, and similar).

	- ``abi3``, introduced in Pyton 3.2, is compatible with
	- ``abi3``, introduced in Python 3.2, is compatible with

	- ``abi3t``, introduced in Pyton 3.15, is compatible with
	- ``abi3t``, introduced in Python 3.15, is compatible with

	When using a build tool (for example, ``setuptools``), the tool is
	When using a build tool (for example, Setuptools), the tool is

	The macro(s) must be defined before including ``Python.h``.
	The macros must be defined before including ``Python.h``.

	:term:`free-threaded <free-threaded build>` builds of CPython.
	:term:`free-threaded builds <free-threaded build>` of CPython.

	On a a :term:`free-threaded build` -- that is, when
	On a :term:`free-threaded build` -- that is, when

	Scikit-build-core, Maturin, and similar).
	scikit-build-core, Maturin).

	At the time of writing this entry, these tools did not support ``abi3t``.
	At the time of writing, these tools did not support ``abi3t``.

	- define only :c:macro:`!Py_LIMITED_API` and build for free-threaded Python.
	- Define only :c:macro:`!Py_LIMITED_API` and define :c:macro:`!Py_GIL_DISABLED`.
	This happens automatically with a free-threaded interpreter, except on Windows.

Uh oh!

Conversation

encukou commented Apr 2, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ZeroIntensity left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

StanFromIreland commented Apr 2, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ngoldbaum left a comment

Choose a reason for hiding this comment

Uh oh!

ngoldbaum Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

encukou commented Apr 2, 2026 •

edited by github-actions bot

Loading

ngoldbaum Apr 3, 2026 •

edited

Loading