add PythonABI and new builder structs for pyo3-build-config InterpreterConfig by ngoldbaum · Pull Request #5924 · PyO3/pyo3

ngoldbaum · 2026-03-30T18:22:12Z

Towards #5786.

Refactor pyo3_build_config::impl_::InterpreterConfig to use an enum to represent the kinds of stable ABI instead of boolean abi3 flag. Also replace names that contain "abi3" with "stable_abi".

This is extracted from a branch that enables abi3t builds and Python 3.15 stable ABI support, where I add a third enum variant to represent abi3t. My goal here is to make upstreaming that change simpler. PEP 803 was accepted over the weekend so a new ABI is definitely happening.

I also personally find the enum clearer to understand and easier to read code that uses it instead of the boolean flag.

#3110) Towards #3064. This is purely refactoring, there should be no functional changes as a result of this. Currently the build metadata special-cases ABI3 builds or more generally assumes stable ABI builds and ABI3 builds are the same thing. With PEP 803 and the new abi3t ABI in Python 3.15, that is no longer the case. This replaces the old `ABI3Version` enum with a new struct combining two enums: ```rust /// struct describing ABI layout to use for build #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct StableAbi { /// The "kind" of stable ABI. Either abi3 or abi3t currently. pub kind: StableAbiKind, /// The minimum Python version to build for. pub version: StableAbiVersion, } /// Python version to use as the abi3/abi3t target. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum StableAbiVersion { /// Stable ABI wheels will have a minimum Python version matching the /// version of the current Python interpreter CurrentPython, /// Stable ABI wheels will have a fixed user-specified minimum Python /// version Version(u8, u8), } /// The "kind" of stable ABI. Either abi3 or abi3t currently. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum StableAbiKind { /// The original stable ABI, supporting Python 3.2 and up Abi3, } ``` `StableAbiVersion` is just the old `Abi3Version` enum renamed since the concept of a minimum supported version is shared by abi3t. I have [a branch](main...ngoldbaum:maturin:abi3t) that adds an `Abi3t` variant for `StableAbiKind`. My goal with this PR is to make reviewing the subsequent PR adding abi3t support easier. Also see PyO3/pyo3#5924 where I made a similar change in PyO3. Here in Maturin I needed different types but in principle I could make the two implementations use shared code. I'm not sure if that's actually useful for anything in practice. --------- Co-authored-by: messense <messense@icloud.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

davidhewitt

Thanks, some hazy thoughts here, not sure if I'm being helpful throwing these out there.

Icxolu

I haven't worked too much inside the build code, so I'm not sure that I can help much here, but I gave this a brief read and left some comments.

I do like the builder pattern. I think it's nice to have a different type between the abi configuring phase and the usage phase (even tho it does not protect us from forgetting to configure something)

davidhewitt

I have taken a look through some parts, I think I have a couple of pieces that I'd like clarifying in this PR:

I can't decide if we want to separate "host version" from target abi version. That seemed like it might help in #5960, but maybe it adds complexity for no practical benefit.
I think it'd be helpful to introduce the possibility to configure for abi3t in this PR through a config file, even if the full end-to-end build with abi3t is not done here (we could maybe just halt the build if abi3t is selected for now). I think that'd make it easier to see the full end state possible states we're heading towards, plus help understand where "stable abi" vs "abi3 and abi3t" are the right names.

ngoldbaum · 2026-04-24T20:18:09Z

I just pushed a big commit that restores the version and implementation fields on InterpreterConfig, deprecates the abi3 field, and adds a new target_abi field which is a PythonAbi struct.

I also added a new InterpreterConfigBuilder struct to try to contain some of the boilerplate.

It ends up being an even bigger refactor! But I think we're getting close now.

I also didn't end up adding abi3t yet because this got kinda big. I'm going to try rebasing #5807 on top of this next week and then I can add a stub abi3t implementation here.

In the meantime, I'd very much appreciate feedback on the new approach.

ngoldbaum · 2026-04-24T20:20:12Z

this is out of date now and needs to be updated

… abi3 config

codspeed-hq · 2026-04-30T19:50:34Z

Merging this PR will improve performance by 13.8%

⚡ 1 improved benchmark
✅ 104 untouched benchmarks
⏩ 1 skipped benchmark¹

Performance Changes

	Benchmark	`BASE`	`HEAD`	Efficiency
⚡	`bench_pyclass_create`	4.6 µs	4 µs	+13.8%

_{Comparing ngoldbaum:abi-tag-refactor (3a21665) with main (cf4d883)}

1 benchmark was skipped, so the baseline result was used instead. If it was deleted from the codebase, click here and archive it to remove it from the performance reports. ↩

ngoldbaum · 2026-05-01T01:39:39Z

@davidhewitt @Icxolu this is ready for another pass.

ngoldbaum · 2026-05-01T01:49:28Z

+    }
+}
+
+/// The "kind" of stable ABI. Either abi3 or abi3t currently.


out of date

ngoldbaum · 2026-05-01T01:50:30Z

+            self.target_abi.is_none(),
+            "Target ABI already set to {}",
+            target_abi
+        );


Should probably have a similar check for all the builder functions

ngoldbaum · 2026-05-01T01:51:14Z

-                self.version,
-                version.minor,
-            );
+/// Whether the ABI is for the GIL-enabled or free-threaded build.


copy/paste error from GilUsed

ngoldbaum · 2026-05-01T01:51:47Z


-/// Checks if `abi3` or any of the `abi3-py3*` features is enabled for the PyO3 crate.
-///
-/// Must be called from a PyO3 crate build script.


shouldn't be deleted

ngoldbaum · 2026-05-01T01:52:05Z

-#[cfg_attr(test, derive(Debug, PartialEq, Eq))]
-#[derive(Clone, Default)]
+#[cfg_attr(test, derive(PartialEq, Eq))]
+#[derive(Debug, Clone, Default)]


should be reverted

ngoldbaum

I asked Claude to do a review pass and it spotted some things, along with this comment, which I agree with:

There are now several near-equivalent expressions:

target_abi.kind.is_free_threaded() (the canonical predicate)

flags.0.contains(&BuildFlag::Py_GIL_DISABLED)

the gil_disabled boolean threaded through from_interpreter and from_sysconfigdata

cross_compile_config.abiflags.as_deref() == Some("t")

The PR doesn't create this fragmentation, but it does add the new canonical predicate without unifying the
others. Worth a follow-up issue: every path should converge on target_abi.kind.is_free_threaded() after
construction, with Py_GIL_DISABLED in build_flags purely a downstream consequence.

ngoldbaum · 2026-05-01T02:35:31Z

+        let build_flags = if build_flags.0.contains(&BuildFlag::Py_GIL_DISABLED) {
+            if let Some(target_abi) = self.target_abi {
+                if !target_abi.kind.is_free_threaded() {
+                    warn!(
+                        "build_flags contains Py_GIL_DISABLED but target ABI '{target_abi}' is not free-threaded"
+                    );
+                }
+            }
+            build_flags
+        } else if let Some(target_abi) = self.target_abi {
+            let mut flags = build_flags.clone();
+            if target_abi.kind.is_free_threaded() {
+                flags.0.insert(BuildFlag::Py_GIL_DISABLED);
+            }
+            flags


On reflection, it probably makes sense to move these two branches into finalize when the final state is known.

ngoldbaum · 2026-05-01T02:36:49Z

+        let parts: Vec<&str> = value.split("-").collect();
+        let implementation = parts[0].parse()?;
+        let kind = parts[1].parse()?;
+        let version: PythonVersion = parts[2].parse()?;


Should use splitn(3, '-') and ok_or to avoid panics

ngoldbaum · 2026-05-01T02:37:39Z

+            target_abi: self
+                .target_abi
+                .unwrap_or(PythonAbiBuilder::new(self.implementation, self.version).finalize()),
+            abi3: false,


should be something like matches!(target_abi.kind, PythonAbiKind::Stable(StableAbi::Abi3)) instead

ngoldbaum · 2026-05-01T02:39:49Z

@@ -470,11 +508,17 @@ print("gil_disabled", get_config_var("Py_GIL_DISABLED"))
                .context("failed to parse contents of PYO3_CONFIG_FILE")?;


Should we care that this discards the target abi in the config file if an abi3 feature is set in the build environment?

ngoldbaum · 2026-05-01T02:40:54Z

+                .free_threaded()
+                .unwrap()
+                .finalize()
+        } else if (abi3.is_some() && abi3.unwrap()) || is_abi3() {


The pattern abi3.is_some() && abi3.unwrap() should be spelled abi3 == Some(true). See also other occurrences below.

ngoldbaum · 2026-05-01T02:42:53Z

+                "Invalid config that sets both target_abi and abi3."
+            );
+            target_abi
+        } else if is_abi3t() {


should probably error if abi3 is set?

ngoldbaum · 2026-05-01T02:43:37Z

+                .stable_abi(StableAbi::Abi3t)
+                .unwrap()
+                .finalize()
+        } else if flags_contains_free_threaded {


should add comment explaining that this should fire even if is_abi3() is true for backwards compatibility

ngoldbaum · 2026-05-01T02:44:27Z

+        let mut abi_builder = if gil_disabled {
+            PythonAbiBuilder::new(implementation, target_version)
+        } else {
+            // we already


should delete this comment fragment

ngoldbaum · 2026-05-01T02:49:13Z

+        let target_version = if let Some(min_version) = abi3_version {
+            ensure!(
+                min_version <= version,
+                "cannot set a minimum Python version {} higher than the interpreter version {} \
+                 (the minimum Python version is implied by the abi3-py3{} feature)",
+                min_version,
+                version,
+                min_version.minor
+            );
+            min_version


This should get refactored into a helper function and also get used in the from_build_env implementation, which does a similar mapping from a user-supplied abi3_version parameter to an ABI3 version used for a build.

ngoldbaum · 2026-05-01T02:50:55Z

+    pointer_width: Option<u32>,
+    build_flags: Option<BuildFlags>,
+    suppress_build_script_link_lines: Option<bool>,
+    extra_build_script_lines: Option<Vec<String>>,


Super minor but the option is unnecessary, this can default to vec![]

ngoldbaum added refactoring free-threading labels Mar 30, 2026

ngoldbaum force-pushed the abi-tag-refactor branch 2 times, most recently from 2e92e57 to 4f2177f Compare March 30, 2026 18:37

ngoldbaum mentioned this pull request Mar 30, 2026

Refactor to store CPython ABI metadata in a struct combining two enums PyO3/maturin#3110

Merged

davidhewitt reviewed Mar 31, 2026

View reviewed changes

Comment thread pyo3-build-config/src/impl_.rs

Comment thread pyo3-build-config/src/impl_.rs Outdated

ngoldbaum mentioned this pull request Apr 3, 2026

Opaque PyObject ABI support #5807

Open

davidhewitt mentioned this pull request Apr 10, 2026

fixup_for_abi3_version downgrades version causing wrong link library name when cross-compiling for Android #5960

Open

ngoldbaum changed the title ~~add CPythonABI enum for pyo3-build-config InterpreterConfig~~ add PythonABI struct and use it for pyo3-build-config InterpreterConfig Apr 15, 2026

ngoldbaum force-pushed the abi-tag-refactor branch 2 times, most recently from 51ff27b to dc5c1d1 Compare April 17, 2026 21:18

ngoldbaum commented Apr 17, 2026

View reviewed changes

Comment thread pyo3-build-config/src/impl_.rs

bschoenmaeckers mentioned this pull request Apr 22, 2026

Add RustPython cfg #5994

Merged

Icxolu reviewed Apr 22, 2026

View reviewed changes

Comment thread pyo3-build-config/src/impl_.rs Outdated

Comment thread pyo3-build-config/src/impl_.rs Outdated

Comment thread pyo3-build-config/src/impl_.rs Outdated

davidhewitt reviewed Apr 23, 2026

View reviewed changes

Comment thread pyo3-build-config/src/impl_.rs

Comment thread pyo3-build-config/src/impl_.rs

Comment thread pyo3-build-config/src/impl_.rs

ngoldbaum mentioned this pull request Apr 23, 2026

Add BuildScriptContext #5987

Draft

ngoldbaum force-pushed the abi-tag-refactor branch from aea6287 to e819b62 Compare April 24, 2026 20:13

ngoldbaum commented Apr 24, 2026

View reviewed changes

Comment thread newsfragments/5924.changed.md

Copy link
Copy Markdown

Contributor Author

ngoldbaum Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is out of date now and needs to be updated

ngoldbaum changed the title ~~add PythonABI struct and use it for pyo3-build-config InterpreterConfig~~ add PythonABI and new builder structs for pyo3-build-config InterpreterConfig Apr 24, 2026

ngoldbaum force-pushed the abi-tag-refactor branch from 6931ee2 to d1d5d13 Compare April 24, 2026 21:42

ngoldbaum added 8 commits April 28, 2026 14:41

add CPythonABI enum for pyo3-build-config InterpreterConfig

c8e40b9

add release note

45d5cc1

store ABI details in a new PythonAbi struct

e3dc133

fix nox config file

966a82f

fix ffi-check

9d9a0e2

Refactor to use the builder pattern for InterpreterConfig

f52f1d8

revert noxfile change

77039d2

fix clippy-all

0765953

ngoldbaum added 3 commits April 28, 2026 14:41

fix build-config test

cde688c

Fix issues linking against onld stable ABI versions

b11b262

remove load-bearing debug impls

9cb420a

ngoldbaum force-pushed the abi-tag-refactor branch from a0fddcd to 9cb420a Compare April 28, 2026 20:45

ngoldbaum added 2 commits April 28, 2026 15:05

fix issue with InterpreterConfig::from_interpreter never returning an…

7fe98ab

… abi3 config

fix clippy lint

41be837

ngoldbaum added the CI-no-fail-fast If one job fails, allow the rest to keep testing label Apr 28, 2026

ngoldbaum added 4 commits April 28, 2026 15:34

fix PythonAbiBuilder::from_build_env

58162a4

Only target abi3 for non-free-threaded builds

48a7d20

fix logic error in InterpreterConfig::from_reader

c899390

Add stub abi3t implementation

ea2eab7

ngoldbaum added 3 commits April 30, 2026 14:50

Improve test coverage

8354ef7

fix clippy

6854756

fix 3.14t abi3 builds being a no-op

3a21665

ngoldbaum commented May 1, 2026

View reviewed changes

		@@ -470,11 +508,17 @@ print("gil_disabled", get_config_var("Py_GIL_DISABLED"))
		.context("failed to parse contents of PYO3_CONFIG_FILE")?;

Conversation

ngoldbaum commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

davidhewitt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Icxolu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

davidhewitt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codspeed-hq Bot commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will improve performance by 13.8%

Performance Changes

Footnotes

Uh oh!

ngoldbaum commented May 1, 2026

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!

ngoldbaum 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

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ngoldbaum commented Mar 30, 2026 •

edited

Loading

ngoldbaum commented Apr 24, 2026 •

edited

Loading

codspeed-hq Bot commented Apr 30, 2026 •

edited

Loading