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

clin1234 · 2026-04-12T15:07:16Z

Issue: Implement PEP 803 -- abi3t #146636

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

da-woods

There's a lot that isn't right here (or is mostly about freethreading generally rather than about the stable ABI).

da-woods · 2026-04-12T15:57:00Z

+:c:func:`PyDict_SetItem`, or explicitly using macros), it attempts to acquire
+the underlying mutex.
+
+Using Critical Sections


The weakness right now is that I don't think they're part of the stable ABI (but hopefully will be)

If you were referring to https://docs.python.org/3/c-api/dict.html#c.PyDict_SetItem, it's part of the Stable ABI: https://docs.python.org/3/c-api/dict.html#c.PyDict_SetItem

No - I was referring to critical sections. Which I really hope are added before 3.15 comes out but I don't think currently are. Sorry if that was ambiguous.

Now being proposed: #149225

da-woods · 2026-04-12T16:14:50Z

I think the way most people will want to proceed is:

Switch to PEP 793 module initialization (https://peps.python.org/pep-0793/). This will hopefully be a fairly trivial change for most people.
Switch to using opaque objects and accessing all their type data through PyObject_GetTypeData. This will be a painful change for most people (and especially if they're starting from static types).
Follow the general free-threading C API advice in https://docs.python.org/3/howto/free-threading-extensions.html#container-thread-safety (e.g. avoid borrowed reference, use critical sections once they become available). My personal opinion is that it isn't worth duplicating the advice.
Decide if they want to mark their extension as thread-safe.

But steps 1 and 2 are the main ones and are almost not covered here.

clin1234 · 2026-04-12T16:54:01Z

Based on WIP PR: #148013

picnixz · 2026-04-12T16:57:24Z

I don't understand why we are having this PR when the reference documentation is not merged. Can we revisit this later? I would have expected the PEP's author to write this.

picnixz · 2026-04-13T00:53:22Z

I left it as a draft because I do not think it is time for it to be reviewed. Please wait for the PEP author first.

encukou · 2026-04-13T08:13:37Z

Please don't repeat text from free-threading HOWTO. This document should be about migrating from that to the stable ABI; anything that's relevant to free-threading in general should be explained there (and possibly linked from the new document).

Also don't repeat information from the reference docs. A migration guide should link to the docs, and perhaps point out how/why the new thing is different.

And please see here on how-to guides in general: https://diataxis.fr/how-to-guides/

read-the-docs-community · 2026-05-02T00:16:31Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #32725685 | 📁 Comparing 3b401db against main (be9c7cb)

🔍 Preview build

101 files changed · + 3 added · ± 98 modified

+Added

±Modified

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.

da-woods · 2026-05-17T11:58:05Z

+The CPython C API exposes the :c:macro:`!Py_LIMITED_API` macro: in the free-threaded stable ABI
+build it's defined to ``1``, and in the regular build it's not defined.


This isn't right.

da-woods · 2026-05-17T11:59:50Z

+- define both :c:macro:`!Py_LIMITED_API` and :c:macro:`!Py_TARGET_ABI3T`, or
+- define only :c:macro:`!Py_LIMITED_API` and:
+
+ - on Windows, define :c:macro:`!Py_GIL_DISABLED`;
+ - on other systems, use the headers of free-threaded build of Python.


I think the idiomatic way is probably just to define Py_TARGET_ABI3T with the version hex that you want to target.
The other ways (involving defining Py_LIMITED_API and maybe using the free-threading headers) are a bit opaque so it's probably better not to recommend them.

da-woods · 2026-05-17T12:02:01Z

+Accessing any member of ``PyObject`` directly is now prohibited, like the non-GIL
+stable ABI. For instance, prefer ``Py_TYPE()`` and ``Py_SET_TYPE()`` over ``ob_type``,


like the non-GIL stable ABI
I think this is the wrong way around and it's "the GIL stable ABI".
I think also that accessing the members is recommended against in the GIL stable ABI and actually impossible in the freethreading stable ABI.

da-woods · 2026-05-17T12:02:31Z

+the GIL disabled; otherwise importing the extension will raise a warning and
+enable the GIL at runtime.
+
+Multi-phase and single-phase initialization is supported to indicate that an extension module


I don't think single-phase initialization is supported

da-woods · 2026-05-17T12:03:02Z

+ PySlot_END
+ };
+
+Furthermore, using ``PyABIInfo_VAR`` and ``Py_mod_abi`` is recommended so that an


required I think

da-woods · 2026-05-17T12:04:12Z

+
+.. _critical-sections:
+
+Replacements:


At least in the C and C++ world the macros are available and encouraged. So I'm not sure "replacements" makes sense.

da-woods · 2026-05-17T12:04:31Z

+|:c:macro:`Py_BEGIN_CRITICAL_SECTION_MUTEX` |``PyCriticalSection_BeginMutex`` |
+|:c:macro:`Py_END_CRITICAL_SECTION` |``PyCriticalSection_End`` |
+-------------------------------------------+---------------------------------------+
+|:c:macro:`Py_BEGIN_CRITICAL_SECTION2_MUTEX`|``PyCriticalSection2_BeginMutex`` |
+|:c:macro:`Py_END_CRITICAL_SECTION2` |``PyCriticalSection2_End`` |
+-------------------------------------------+---------------------------------------+


I don't think the mutex versions are exposed at all

da-woods · 2026-05-17T12:06:36Z

+``Py_REFCNT``, ``Py_IncRef()`` and ``Py_DecRef()`` over ``ob_refcnt``, etc.
+
+Similarly, members of ``PyVarObject`` are not visible. If you need any object of such type
+to be passed as a ``PyObject`` parameter to any API function, cast it directly as ``PyObject``.


The big consequence here is not that you can't access the members. It's that you can't define structures like
struct S { PyObject_HEAD // your struct goes here };
and thus have to omit the PyObject_HEAD and set the object size to -size to indicate opaqueness.
You also can't use PyVarObject at all easily right now.

encukou · 2026-05-28T14:58:25Z

Thank you @clin1234. I'll take it from here.

clin1234 · 2026-05-28T16:23:37Z

Thank you @clin1234. I'll take it from here.

Any other major PRs as part of implementing PEP 803 that should be mentioned in the Migration Guide?

encukou · 2026-05-29T16:28:30Z

Continued in #150580.

Any other major PRs as part of implementing PEP 803 that should be mentioned in the Migration Guide?

Mentions should go in Release notes; a guide should rather be full of practical advice.
All the PRs should be attached to #146636 though.

bedevere-appBot added awaiting review docs Documentation in the Doc dir skip news labels Apr 12, 2026

github-project-automationBot added this to Docs PRs Apr 12, 2026

github-project-automationBot moved this to Todo in Docs PRs Apr 12, 2026

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

da-woods reviewed Apr 12, 2026
View reviewed changes

Comment threadDoc/howto/freethreading-stable-abi.rst

picnixz marked this pull request as draft April 12, 2026 17:03

bedevere-appBot removed the awaiting review label Apr 12, 2026

clin1234 marked this pull request as ready for review April 12, 2026 17:44

bedevere-appBot added the awaiting review label Apr 12, 2026

picnixz added the DO-NOT-MERGE label Apr 13, 2026

clin1234 requested a review from da-woods May 7, 2026 19:31

clin1234 marked this pull request as draft May 7, 2026 19:31

bedevere-appBot removed the awaiting review label May 7, 2026

clin1234 force-pushed the patch-6 branch from a4b1bea to 0bddc53Compare May 13, 2026 23:50

clin1234 marked this pull request as ready for review May 17, 2026 09:33

bedevere-appBot added the awaiting review label May 17, 2026

clin1234 added 5 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

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

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

clin1234 force-pushed the patch-6 branch from 0bddc53 to 43538cfCompare May 17, 2026 09:33

Update module slot definitions to use PySlot from PEP 820
ed0e4fe

da-woods reviewed May 17, 2026
View reviewed changes

clin1234 added 3 commits May 17, 2026 11:22

Update freethreading-stable-abi.rst
a7fcbcc

Fix typo in freethreading-stable-abi.rst
ccdedb0

Update freethreading-stable-abi.rst
3b401db

encukou closed this May 29, 2026

		The CPython C API exposes the :c:macro:`!Py_LIMITED_API` macro: in the free-threaded stable ABI
		build it's defined to ``1``, and in the regular build it's not defined.

		Accessing any member of ``PyObject`` directly is now prohibited, like the non-GIL
		stable ABI. For instance, prefer ``Py_TYPE()`` and ``Py_SET_TYPE()`` over ``ob_type``,


		.. _critical-sections:

		Replacements:

Uh oh!

Uh oh!

Conversation

clin1234 commented Apr 12, 2026• edited by github-actions BotLoading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

da-woods left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

da-woods commented Apr 12, 2026

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

picnixz commented Apr 12, 2026

Uh oh!

picnixz commented Apr 13, 2026

Uh oh!

encukou commented Apr 13, 2026

Uh oh!

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

Uh oh!

Documentation build overview

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!

encukou commented May 28, 2026

Uh oh!

clin1234 commented May 28, 2026

Uh oh!

encukou commented May 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

clin1234 commented Apr 12, 2026•
edited by github-actions Bot
Loading

clin1234 commented Apr 12, 2026•
edited
Loading

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