PEP 803: Stable ABI for Free-Threaded Builds #4556

encukou · 2025-08-19T15:02:00Z

Basic requirements (all PEP Types)

Standards Track requirements

📚 Documentation preview 📚: https://pep-previews--4556.org.readthedocs.build/

JelleZijlstra

Looks good, some small comment.

peps/pep-0803.rst

willingc

Thanks @encukou. I've made a few readability suggestions.

peps/pep-0803.rst

willingc · 2025-08-19T15:13:54Z

peps/pep-0803.rst

+that is, only a subset of the functions, structures, etc. that CPython
+exposes.
+The limited API is versioned, and building against Limited API 3.X
+yields an extension that is ABI-compatible with CPython 3.X *and above* (modulo


Not sure what "modulo bugs" means in this sentence.

peps/pep-0803.rst

willingc · 2025-08-19T15:36:26Z

peps/pep-0803.rst

+However, CPython will add a line of defense against outdated or misconfigured
+tools, or human mistakes, in the form of a new *module slot* containing
+basic ABI information.


Suggested change

However, CPython will add a line of defense against outdated or misconfigured

tools, or human mistakes, in the form of a new *module slot* containing

basic ABI information.

However, CPython will help defend against outdated or misconfigured

tools, or human mistakes, in the form of a new *module slot* containing

basic ABI information.

I think my wording better suggests that we're adding a distinct mechanism.

willingc · 2025-08-19T15:37:24Z

peps/pep-0803.rst

+This information will be checked when a module is loaded, and incompatible
+extensions will be rejected.


Suggested change

This information will be checked when a module is loaded, and incompatible

extensions will be rejected.

Checks will be done when a module is loaded, and incompatible

extensions will be rejected.

I'd like to say which information is checked (with “this” referring to the previous sentence).

peps/pep-0803.rst

encukou

Thank you for the reviews!

Sometimes I have reasons for a particular wording, and copy editing helps make the nuances stand out :)

encukou · 2025-08-20T10:04:06Z

peps/pep-0803.rst

+   Projects that need this can build separate extensions specifically for
+   the 3.14 free-threaded interpreter, and for older stable ABI versions.
+
+API changes are OK


That's what the next sentence says. Do you think the 4 words don't make sense as a heading?

peps/pep-0803.rst

encukou · 2025-08-20T10:56:02Z

peps/pep-0803.rst

+This information will be checked when a module is loaded, and incompatible
+extensions will be rejected.


I'd like to say which information is checked (with “this” referring to the previous sentence).

encukou · 2025-08-20T10:56:30Z

peps/pep-0803.rst

+However, CPython will add a line of defense against outdated or misconfigured
+tools, or human mistakes, in the form of a new *module slot* containing
+basic ABI information.


I think my wording better suggests that we're adding a distinct mechanism.

peps/pep-0803.rst

encukou · 2025-08-20T10:59:04Z

peps/pep-0803.rst

+Users -- or rather the tools they use for building and installing extensions --
+will continue to be responsible for not putting incompatible extensions on
+Python's import paths.


The tools can only be responsible for their own actions; they're not expected to prevent anything else from messing things up.

encukou · 2025-08-20T11:03:46Z

peps/pep-0803.rst

+  - :c:type:`!PyModuleDef_Base`
+  - :c:type:`PyModuleDef`
+
+- no longer include the following macros:


I'd like to keep the current wording if you don't mind.
AFAIK, “exclude” sounds more like “prevent from being included” or “expel” than a passive “not include”. (And a few dictionaries I checked at least put the definitions in this order.)

peps/pep-0803.rst

Co-authored-by: Carol Willing <[email protected]> Co-authored-by: Jelle Zijlstra <[email protected]>

encukou · 2025-08-26T10:47:30Z

@AA-Turner, are you working on a review?

AA-Turner · 2025-08-26T10:59:36Z

Yes, sorry for the delay. I've been unexpectedly busy, should have it finished by Thursday.

A

encukou · 2025-08-29T15:29:23Z

Please send what you have, or leave it for the next round. I'd like to publish the PEP next week.

AA-Turner

Sorry for the delay Petr, I've written up the notes I had & done a brief editorial/style pass.

A

AA-Turner · 2025-08-29T15:40:09Z

peps/pep-0803.rst

@@ -0,0 +1,322 @@
+PEP: 803
+Title: Stable ABI for Free-Threaded Builds


Do we need to clarify that this is for CPython?

AA-Turner · 2025-08-29T15:40:55Z

peps/pep-0803.rst

+Status: Draft
+Type: Standards Track
+Requires: 703, 793, 697
+Created: 08-Aug-2025


This is the date of formal number assignment

Suggested change

Created: 08-Aug-2025

Created: 19-Aug-2025

AA-Turner · 2025-08-29T15:41:08Z

peps/pep-0803.rst

+
+Stable ABI 3.15 will be compatible with both free-threaded and GIL-enabled
+builds.
+To allow this, the ``PyObject`` internal structure and related APIs


Suggested change

To allow this, the ``PyObject`` internal structure and related APIs

To allow this, the :c:type:`PyObject` internal structure and related APIs

AA-Turner · 2025-08-29T15:42:41Z

peps/pep-0803.rst

+Stable ABI 3.15 will be compatible with both free-threaded and GIL-enabled
+builds.


Grammar, this reads slightly oddly to me. Perhaps "Version 3.15 of the Stable ABI will be ...", or "The Stable ABI version 3.15 will be ..."?

AA-Turner · 2025-08-29T15:45:11Z

peps/pep-0803.rst

+Stable ABI 3.15 will be compatible with both free-threaded and GIL-enabled
+builds.
+To allow this, the ``PyObject`` internal structure and related APIs
+will be removed from the Limited API, requiring migration to new API


I assume removed only for the 3.15 / 0x030F0000 version level, rather than entirely?

AA-Turner · 2025-08-29T16:10:17Z

peps/pep-0803.rst

+New Export Hook (PEP 793)
+-------------------------


Suggested change

New Export Hook (PEP 793)

-------------------------

New Export Hook (:pep:`793`)

----------------------------

AA-Turner · 2025-08-29T16:10:41Z

peps/pep-0803.rst

+
+The following functions will become unusable in practice (in the new Limited
+API), since an extension cannot create valid, statically allocated, input
+for them. To ease the transition for extension developers, they will not yet be removed from the Limited API:


line length (please stick to 79)

AA-Turner · 2025-08-29T16:11:36Z

peps/pep-0803.rst

+
+This slot will become *mandatory* with the new export hook added in
+:pep:`793`.
+(The PEP currently says “there are no required slots”; it will be updated.)


Suggested change

(The PEP currently says “there are no required slots”; it will be updated.)

(That PEP currently says “there are no required slots”; it will be updated.)

AA-Turner · 2025-08-29T16:13:14Z

peps/pep-0803.rst

+
+- Opaque ``PyObject`` is available in CPython main branch after defining the
+  ``_Py_OPAQUE_PYOBJECT`` macro.
+  Implemented in GitHub pull request `#136505 <https://github.com/python/cpython/pull/136505>`__.


Suggested change

Implemented in GitHub pull request `#136505 <https://github.com/python/cpython/pull/136505>`__.

Implemented in GitHub pull request `python/cpython#136505

<https://github.com/python/cpython/pull/136505>`__.

AA-Turner · 2025-08-29T16:13:30Z

peps/pep-0803.rst

+- For a version-checking slot, see GitHub pull request `#137212 <https://github.com/python/cpython/pull/137212>`__.
+- For a check for older ``abi3``, see GitHub pull request `#137957 <https://github.com/python/cpython/pull/137957>`__.


Suggested change

- For a version-checking slot, see GitHub pull request `#137212 <https://github.com/python/cpython/pull/137212>`__.

- For a check for older ``abi3``, see GitHub pull request `#137957 <https://github.com/python/cpython/pull/137957>`__.

- For a version-checking slot, see GitHub pull request `python/cpython#137212

<https://github.com/python/cpython/pull/137212>`__.

- For a check for older ``abi3``, see GitHub pull request `python/cpython#137957

<https://github.com/python/cpython/pull/137957>`__.

encukou added 2 commits August 19, 2025 16:58

PEP 803: Stable ABI for Free-Threaded Builds

38cccbe

codeowners

b968037

encukou requested a review from a team as a code owner August 19, 2025 15:02

JelleZijlstra approved these changes Aug 19, 2025

View reviewed changes

peps/pep-0803.rst Outdated Show resolved Hide resolved

peps/pep-0803.rst Outdated Show resolved Hide resolved

peps/pep-0803.rst Outdated Show resolved Hide resolved

willingc reviewed Aug 19, 2025

View reviewed changes

encukou commented Aug 20, 2025

View reviewed changes

Apply suggestions from code review

f223ba1

Co-authored-by: Carol Willing <[email protected]> Co-authored-by: Jelle Zijlstra <[email protected]>

AA-Turner self-requested a review August 21, 2025 22:22

AA-Turner reviewed Aug 29, 2025

View reviewed changes

		This information will be checked when a module is loaded, and incompatible
		extensions will be rejected.

		@@ -0,0 +1,322 @@
		PEP: 803
		Title: Stable ABI for Free-Threaded Builds

	To allow this, the ``PyObject`` internal structure and related APIs
	To allow this, the :c:type:`PyObject` internal structure and related APIs

		Stable ABI 3.15 will be compatible with both free-threaded and GIL-enabled
		builds.

	(The PEP currently says “there are no required slots”; it will be updated.)
	(That PEP currently says “there are no required slots”; it will be updated.)

	Implemented in GitHub pull request `#136505 <https://github.com/python/cpython/pull/136505>`__.
	Implemented in GitHub pull request `python/cpython#136505
	<https://github.com/python/cpython/pull/136505>`__.

		- For a version-checking slot, see GitHub pull request `#137212 <https://github.com/python/cpython/pull/137212>`__.
		- For a check for older ``abi3``, see GitHub pull request `#137957 <https://github.com/python/cpython/pull/137957>`__.

Uh oh!

PEP 803: Stable ABI for Free-Threaded Builds #4556

Are you sure you want to change the base?

PEP 803: Stable ABI for Free-Threaded Builds #4556

Conversation

encukou commented Aug 19, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Basic requirements (all PEP Types)

Standards Track requirements

Uh oh!

JelleZijlstra left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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

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!

encukou left a comment

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

encukou commented Aug 26, 2025

Uh oh!

AA-Turner commented Aug 26, 2025

Uh oh!

encukou commented Aug 29, 2025

Uh oh!

AA-Turner left a comment

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!

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

encukou commented Aug 19, 2025 •

edited by github-actions bot

Loading