gh-146636: Add Free-threaded Stable ABI migration guide by encukou · Pull Request #150580 · python/cpython

encukou · 2026-05-29T16:26:41Z

Issue: Implement PEP 803 -- abi3t #146636

This document provides detailed instructions on how to use the Free Threading Stable ABI in CPython, including guidelines for module initialization, API usage, and thread safety considerations.

Clarified access restrictions on PyObject members and recommended functions for type and reference count manipulation.

Clarified that direct access to PyObject members is prohibited.

Co-authored-by: da-woods <dw-git@d-woods.co.uk>

Updated documentation to clarify the identification of free-threaded limited API builds in C, including changes to macros and initialization methods.

Updated the documentation to clarify the use of the stable ABI and GIL management in Python extensions, including changes to member access and initialization methods.

Removed sections on API guidelines, critical sections, and thread safety from the documentation.

read-the-docs-community · 2026-05-29T16:30:54Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #32953252 | 📁 Comparing 51a55ac against main (26696a6)

🔍 Preview build

38 files changed · + 1 added · ± 37 modified

+Added

howto/abi3t-migration.html

±Modified

ngoldbaum · 2026-05-29T16:57:05Z

Thanks, this looks great! I'll probably use the tables in my EuroPython talk.

I'm hopeful that we'll be able to ship abi3t support in the next releases of PyO3 and Maturin (see PyO3/pyo3#5807 and PyO3/maturin#3113).

I am also planning to add a section to the free-threaded guide about building abi3t extensions, including practicalities like dealing with bindings generators and the NumPy C API. When that is ready, maybe we can just link there for all the ecosystem-wide details that don't belong in the CPython docs?

Co-authored-by: da-woods <dw-git@d-woods.co.uk> Co-authored-by: Stan Ulbrych <stan@python.org>

encukou · 2026-06-01T12:56:07Z

Thanks for the reviews and suggestions!

I am also planning to add a section to the free-threaded guide about building abi3t extensions, including practicalities like dealing with bindings generators and the NumPy C API. When that is ready, maybe we can just link there for all the ecosystem-wide details that don't belong in the CPython docs?

That sounds great!

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

encukou · 2026-06-03T12:02:06Z

I'll merge now; any improvements can go in separate PRs.

miss-islington-app · 2026-06-03T12:02:44Z

Thanks @encukou for the PR 🌮🎉.. I'm working now to backport this PR to: 3.15.
🐍🍒⛏🤖

bedevere-app · 2026-06-03T12:02:59Z

GH-150844 is a backport of this pull request to the 3.15 branch.

…0580) (#150844) Co-authored-by: Petr Viktorin <encukou@gmail.com> Co-authored-by: Charlie Lin <tuug@gmx.us> Co-authored-by: da-woods <dw-git@d-woods.co.uk> Co-authored-by: Stan Ulbrych <stan@python.org> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

…GH-150580) Co-authored-by: Charlie Lin <tuug@gmx.us> Co-authored-by: da-woods <dw-git@d-woods.co.uk> Co-authored-by: Stan Ulbrych <stan@python.org> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

clin1234and others added 20 commits May 17, 2026 05:33

Add reference to freethreading-stable-abi-howto
8040796

Add documentation for Free Threading Stable ABI usage
7175e14
This document provides detailed instructions on how to use the Free Threading Stable ABI in CPython, including guidelines for module initialization, API usage, and thread safety considerations.

Update documentation on PyObject opaqueness and module init
e0f3bd2
Clarified access restrictions on PyObject members and recommended functions for type and reference count manipulation.

Fix formatting for PyObject opaqueness section
3739aec

Fix formatting of code snippet in documentation
c235a75

Update documentation on PyObject opaqueness
753156b
Clarified that direct access to PyObject members is prohibited.

Py_Type
344105e
Co-authored-by: da-woods <dw-git@d-woods.co.uk>

Clarify free-threaded limited API build documentation
29b932d
Updated documentation to clarify the identification of free-threaded limited API builds in C, including changes to macros and initialization methods.

Revise freethreading-stable-abi.rst for clarity
8545eeb
Updated the documentation to clarify the use of the stable ABI and GIL management in Python extensions, including changes to member access and initialization methods.

Add freethreading-stable-abi.rst to documentation index
2a11368

Simplify threading and API guidelines in documentation
2f2e756
Removed sections on API guidelines, critical sections, and thread safety from the documentation.

Update freethreading-stable-abi.rst
5d23810

Update freethreading-stable-abi.rst
a8294fa

Update freethreading-stable-abi.rst
43538cf

Update module slot definitions to use PySlot from PEP 820
ed0e4fe

Update freethreading-stable-abi.rst
a7fcbcc

Fix typo in freethreading-stable-abi.rst
ccdedb0

Update freethreading-stable-abi.rst
3b401db

Merge in the main branch
a7fdaaf

Rewrite as a guide
cb9545a

encukou requested review from AA-Turner, StanFromIreland and hugovk as code owners May 29, 2026 16:26

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

bedevere-appBot added the awaiting core review label May 29, 2026

encukou mentioned this pull request May 29, 2026
gh-146636: Add Free-threaded Stable ABI migration guide #148453
Closed

encukou added the skip news label May 29, 2026

encukou added 2 commits May 29, 2026 18:33

Clarification
22a9bfe

No static types
1448abd

da-woods reviewed May 29, 2026
View reviewed changes

Comment threadDoc/howto/abi3t-migration.rst Outdated

StanFromIreland reviewed May 29, 2026
View reviewed changes

encukou mentioned this pull request Jun 1, 2026
Mark various accepted PEPs as Final python/peps#4986
Merged

encukouand others added 3 commits June 1, 2026 14:15

Apply suggestions from code review
fcc553a
Co-authored-by: da-woods <dw-git@d-woods.co.uk> Co-authored-by: Stan Ulbrych <stan@python.org>

Address reviews
6d8dc71

Add link to What's New
d89c007

hugovk reviewed Jun 1, 2026
View reviewed changes

encukouand others added 2 commits June 2, 2026 13:41

Apply suggestions from code review
370ef9b
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Petr Viktorin <encukou@gmail.com>

Remove heading-like incomplete sentence
51a55ac

encukou mentioned this pull request Jun 2, 2026
abi3-abi3t documentation update #150187
Closed

encukou merged commit c720e18 into python:mainJun 3, 2026
30 checks passed

bedevere-appBot removed the awaiting core review label Jun 3, 2026

encukou added awaiting core review needs backport to 3.15 pre-release feature fixes, bugs and security fixes labels Jun 3, 2026

encukou deleted the abi3t-migration-sq branch June 3, 2026 12:02

bedevere-appBot removed the needs backport to 3.15 pre-release feature fixes, bugs and security fixes label Jun 3, 2026

Uh oh!

Uh oh!

Conversation

encukou commented May 29, 2026• edited by bedevere-app BotLoading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-communityBot commented May 29, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Uh oh!

ngoldbaum commented May 29, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

encukou commented Jun 1, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

encukou commented Jun 3, 2026

Uh oh!

Uh oh!

miss-islington-appBot commented Jun 3, 2026

Uh oh!

bedevere-appBot commented Jun 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

encukou commented May 29, 2026•
edited by bedevere-app Bot
Loading

read-the-docs-communityBot commented May 29, 2026•
edited
Loading