gh-146636: Add Free-threaded Stable ABI migration guide#150580
Open
encukou wants to merge 22 commits into
Open
gh-146636: Add Free-threaded Stable ABI migration guide#150580encukou wants to merge 22 commits into
encukou wants to merge 22 commits into
Conversation
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.
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.
encukou
requested review from
AA-Turner,
StanFromIreland and
hugovk
as code owners
9 tasks
Documentation build overview
|
da-woods
reviewed
May 29, 2026
| ======= | ||
|
|
||
| Note that when you build an extension compatible with multiple versions of | ||
| CPython, you should always *test* it witch each version it supports (for |
Contributor
There was a problem hiding this comment.
Suggested change
| CPython, you should always *test* it witch each version it supports (for | |
| CPython, you should always *test* it with each version it supports (for |
Contributor
|
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? |
| +-----------------+-------------------+------------------+ | ||
| | 3.16 | ``cpython-316`` | ``cpython-316t`` | | ||
| +-----------------+-------------------+------------------+ | ||
| | Future versions | (etc.) | (etc.) | |
Member
There was a problem hiding this comment.
Suggested change
| | Future versions | (etc.) | (etc.) | | |
| | Future versions | ``cpython-X`` | ``cpython-Xt`` | |
I suggest this to avoid the Latin abbreviation, which per the devguide we discourage.
| +-----------------+ +------------------+ | ||
| | 3.16 | | ``cpython-316t`` | | ||
| +-----------------+ +------------------+ | ||
| | Future versions | | (etc.) | |
Member
There was a problem hiding this comment.
Suggested change
| | Future versions | | (etc.) | | |
| | Future versions | | ``cpython-Xt`` | |
Ditto.
| resulting extension manually as well. | ||
| This is covered in :ref:`abi3t-migration-tagging` below. | ||
|
|
||
| This guide will ask you to do a series of changes. |
Member
There was a problem hiding this comment.
Suggested change
| This guide will ask you to do a series of changes. | |
| This guide will ask you to make a series of changes. |
| Unless you've done this step already, your extension module defines a | ||
| :ref:`module initialization function <extension-pyinit>` | ||
| named :samp:`PyInit_{<module_name>}`. | ||
| You will need to port it to :ref:`module export hook <extension-export-hook>`, |
Member
There was a problem hiding this comment.
Suggested change
| You will need to port it to :ref:`module export hook <extension-export-hook>`, | |
| You will need to port it to a :ref:`module export hook <extension-export-hook>`, |
|
|
||
| If there is some code before the ``return``, move it to | ||
| a :c:macro:`Py_mod_create` or :c:macro:`Py_mod_exec` slot function. | ||
| See :ref:`PyInit documentation <extension-pyinit>` for related information. |
Member
There was a problem hiding this comment.
Suggested change
| See :ref:`PyInit documentation <extension-pyinit>` for related information. | |
| See the :ref:`PyInit documentation <extension-pyinit>` for related information. |
| Leave out any fields that were missing (excexpt the new :c:macro:`Py_mod_abi`), | ||
| and substitute your own values. | ||
|
|
||
| See :c:type:`PySlot` and :c:ref:`export hook <extension-export-hook>` |
Member
There was a problem hiding this comment.
Suggested change
| See :c:type:`PySlot` and :c:ref:`export hook <extension-export-hook>` | |
| See the :c:type:`PySlot` and :c:ref:`export hook <extension-export-hook>` |
| - :c:func:`PyType_GetModuleByDef` | ||
|
|
||
| Check your code for these. | ||
| If you do not use them, you skip the rest of this section. |
Member
There was a problem hiding this comment.
Suggested change
| If you do not use them, you skip the rest of this section. | |
| If you do not use them, you can skip this section. |
Comment on lines
+351
to
+352
| if (PyModule_GetToken(module, &token) < 0) { | ||
| /* handle error */ |
Member
There was a problem hiding this comment.
Suggested change
| if (PyModule_GetToken(module, &token) < 0) { | |
| /* handle error */ | |
| if (PyModule_GetToken(module, &token) < 0) { | |
| /* handle error */ |
Hmm, the devguide actually doesn’t specify PEP 7/8 for code examples.
| changes extensions may need. | ||
|
|
||
| If you find a problem that other extension authors might run into, | ||
| consider submitting an issue (or pull request) for this guide. |
Member
There was a problem hiding this comment.
Maybe add a link to https://docs.python.org/3/bugs.html?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.