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/

ZeroIntensity

Congrats on the PEP acceptance :)

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

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

+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"?

The way I wrote it still sounds best to me...

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

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:25:28Z

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

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.

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


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

I think defining Py_GIL_DISABLED "manually" is still only supported on Windows.

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

encukou · 2026-04-14T12:53:08Z

I've addressed the comments; does anyone want to re-review?
If not I'll merge around Thursday.

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

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-appBot added the awaiting core review label Apr 2, 2026

bedevere-appBot mentioned this pull request Apr 2, 2026
Implement PEP 803 -- abi3t #146636
Closed
9 tasks

AIdjis reviewed Apr 2, 2026
View reviewed changes

Comment threadDoc/whatsnew/3.15.rst Outdated

AIdjis reviewed Apr 2, 2026
View reviewed changes

Comment threadDoc/whatsnew/3.15.rst Outdated

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

encukouand others added 2 commits April 6, 2026 12:06

Apply suggestions from code review
30d97b1
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Respond to reviews
e7e102a

encukou mentioned this pull request Apr 7, 2026
Document the entire C API #141004
Open

Merge in the main branch
fec46db

encukou requested a review from StanFromIreland as a code owner April 8, 2026 07:32

da-woods reviewed Apr 9, 2026
View reviewed changes

Comment threadDoc/c-api/stable.rst Outdated

encukou added 2 commits April 10, 2026 14:36

Correct macro name
47ff800

Merge in the main branch
f279be8

clin1234 mentioned this pull request Apr 12, 2026
gh-146636: Add Free-threaded Stable ABI migration guide #148453
Closed

encukou merged commit 0fcf2b7 into python:mainApr 16, 2026
39 checks passed

bedevere-appBot removed the awaiting core review label Apr 16, 2026

encukou deleted the 803-docs branch April 16, 2026 12:17

ljfp pushed a commit to ljfp/cpython that referenced this pull request Apr 25, 2026
pythongh-146636: PEP 803: Reference documentation (pythonGH-148013)
cedb210
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

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

Uh oh!

Conversation

encukou commented Apr 2, 2026• edited by github-actions BotLoading 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!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

StanFromIreland commented Apr 2, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ngoldbaum left a comment

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

encukou commented Apr 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

encukou commented Apr 2, 2026•
edited by github-actions Bot
Loading