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?

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?

ZeroIntensity · 2026-04-02T15:01:08Z

Doc/whatsnew/3.15.rst

+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.
+If not using a build tool -- or when writing such a tool -- you can select
+``abi3t`` by setting the macro :c:macro:`!Py_TARGET_ABI3T` as discussed


I think it'd be nice if the Py_TARGET_ABI3T were an actual link, because it's not linked anywhere else in this section.

Suggested change

``abi3t`` by setting the macro :c:macro:`!Py_TARGET_ABI3T` as discussed

``abi3t`` by setting the macro :c:macro:`Py_TARGET_ABI3T` as discussed

The link would send you to a stub that mainly links to the common information.
I want to send people directly there -- that's the link on the next line.

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

hugovk · 2026-04-03T09:03:12Z

Doc/c-api/stable.rst

+On some platforms, Python will look for and load shared library files named
+with the ``abi3`` or ``abi3t`` tag (for example, ``mymodule.abi3.so``).
+:term:`Free threaded <free-threaded build>` interpreters only recognize the
+``abi3t`` tag, while non-free threaded ones will prefer ``abi3`` but fall back


Suggested change

``abi3t`` tag, while non-free threaded ones will prefer ``abi3`` but fall back

``abi3t`` tag, while non-free-threaded ones will prefer ``abi3`` but fall back

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

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

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

	``abi3t`` by setting the macro :c:macro:`!Py_TARGET_ABI3T` as discussed
	``abi3t`` by setting the macro :c:macro:`Py_TARGET_ABI3T` as discussed

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

	``abi3t`` tag, while non-free threaded ones will prefer ``abi3`` but fall back
	``abi3t`` tag, while non-free-threaded ones will prefer ``abi3`` but fall back

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

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!

Choose a reason for hiding this comment

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

encukou commented Apr 2, 2026 •

edited by github-actions bot

Loading