Thanks to visit codestin.com
Credit goes to github.com

Skip to content

gh-146636: PEP 803: Reference documentation #148013

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.

Sign up for GitHub

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 12 commits into from
Apr 16, 2026
Merged

gh-146636: PEP 803: Reference documentation #148013

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
8e203eb
abi3t docs
encukou Mar 31, 2026
c1d7fef
Manifest, annotations
encukou Apr 2, 2026
f83f6b4
Fixup
encukou Apr 2, 2026
b3e31c6
I'm not good with numbers
encukou Apr 2, 2026
2372da9
Merge in the main branch
encukou Apr 3, 2026
b3799de
Address review
encukou Apr 3, 2026
3bc47ee
Add a blurb for the PEP
encukou Apr 3, 2026
30d97b1
Apply suggestions from code review
encukou Apr 6, 2026
e7e102a
Respond to reviews
encukou Apr 6, 2026
fec46db
Merge in the main branch
encukou Apr 8, 2026
47ff800
Correct macro name
encukou Apr 10, 2026
f279be8
Merge in the main branch
encukou Apr 10, 2026
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
Prev Previous commit
Next Next commit
Apply suggestions from code review 
Co-authored-by: Hugo van Kemenade <[email protected]>
  • Loading branch information
@encukou @hugovk
encukou and hugovk authored Apr 6, 2026
commit 30d97b1c359771d58e729924f8748979fc7ae694
14 changes: 7 additions & 7 deletions Doc/c-api/stable.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,10 +67,10 @@

There are two Stable ABIs:

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

- ``abi3t``, introduced in Pyton 3.15, is compatible with
- ``abi3t``, introduced in Python 3.15, is compatible with
:term:`free-threaded <free-threaded build>` builds of CPython.
It has stricter API limitations than ``abi3``.

Expand Down Expand Up @@ -125,7 +125,7 @@

.. note::

When using a build tool (for example, ``setuptools``), the tool is
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.
Copy link
Copy Markdown
Contributor

@ngoldbaum ngoldbaum Apr 3, 2026

Choose a reason for hiding this comment

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

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.

Copy link
Copy Markdown
Member Author

@encukou encukou Apr 6, 2026

Choose a reason for hiding this comment

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

AFAIK Setuptools is the most widely known build tool; the example is there to clarify what kind of “build tool” I'm talking about.

Setuptools has a --py_limited_api argument. All tools will ideally need an update for abi3t.

Expand All @@ -143,7 +143,7 @@
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``.
The macros must be defined before including ``Python.h``.
Since :c:macro:`Py_PACK_VERSION` is not available at this point, you
will need to use the numeric value directly.
For reference, the values for a few recent Python versions are:
Expand All @@ -158,13 +158,13 @@
.. c:macro:: Py_LIMITED_API

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

.. c:macro:: Py_TARGET_ABI3T

Target ``abi3t``, that is,
:term:`free-threaded <free-threaded build>` builds of CPython.
:term:`free-threaded builds <free-threaded build>` of CPython.
See :ref:`above <abi3-compiling>` for common information.
Comment thread
encukou marked this conversation as resolved.

.. versionadded:: next
Expand All @@ -172,7 +172,7 @@
Both macros specify a target ABI; the different naming style is due to
backwards compatibility.

.. admonition:: Historical note

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

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:func reference target not found: PyErr_Display [ref.func]

You can also define ``Py_LIMITED_API`` as ``3``. This works the same as
``0x03020000`` (Python 3.2, the version that introduced Stable ABI).
Expand All @@ -180,7 +180,7 @@
When both are defined, ``Python.h`` may, or may not, redefine
:c:macro:`!Py_LIMITED_API` to match :c:macro:`!Py_TARGET_ABI3T`.

On a a :term:`free-threaded build` -- that is, when
On a :term:`free-threaded build` -- that is, when
:c:macro:`Py_GIL_DISABLED` is defined -- :c:macro:`!Py_TARGET_ABI3T`
defaults to the value of :c:macro:`!Py_TARGET_ABI3T`.
Comment thread
encukou marked this conversation as resolved.
Outdated
This means that there are two ways to build for both ``abi3`` and ``abi3t``:
Expand Down
6 changes: 3 additions & 3 deletions Doc/whatsnew/3.15.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -390,7 +390,7 @@ agen() for x in a)``.
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.
:term:`free-threaded builds <free-threaded build>` of CPython.
This usually requires some non-trivial changes to the source code;
specifically:

Expand All @@ -410,8 +410,8 @@ free-threading (``cp315t``) separately.

Stable ABI for Free-Threaded Builds should typically
be selected in a build tool (such as Setuptools, meson-python, Cython,
Comment thread
encukou marked this conversation as resolved.
Outdated
Scikit-build-core, Maturin, and similar).
At the time of writing this entry, these tools did **not** support ``abi3t``.
scikit-build-core, Maturin).
At the time of writing, 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
Comment thread
ZeroIntensity marked this conversation as resolved.
Expand Down
Loading