Opaque PyObject ABI support

.github/workflows/ci.yml

@@ -66,6 +66,14 @@ jobs:
       - uses: obi1kenobi/cargo-semver-checks-action@v2
         with:
           baseline-rev: ${{ steps.fetch_merge_base.outputs.merge_base }}
+          feature-group: "only-explicit-features"
+          features: "full"
+      - uses: obi1kenobi/cargo-semver-checks-action@v2
+        with:
+          baseline-rev: ${{ steps.fetch_merge_base.outputs.merge_base }}
+          feature-group: "only-explicit-features"
+          features: "full,abi3"
+
 
   check-msrv:
     needs: [fmt, resolve]
@@ -648,7 +656,7 @@ jobs:
       - uses: actions/checkout@v6.0.2
       - uses: actions/setup-python@v6
         with:
-          python-version: "3.14"
+          python-version: "3.15-dev"
       - uses: Swatinem/rust-cache@v2
         with:
           save-if: ${{ github.ref == 'refs/heads/main' || contains(github.event.pull_request.labels.*.name, 'CI-save-pr-cache') }}

Cargo.toml

@@ -125,6 +125,11 @@ abi3-py313 = ["abi3-py314", "pyo3-ffi/abi3-py313"]
 abi3-py314 = ["abi3-py315", "pyo3-ffi/abi3-py314"]
 abi3-py315 = ["abi3", "pyo3-ffi/abi3-py315"]
 
+abi3t = ["pyo3-ffi/abi3t"]
+
+# With abi3t, we can manually set the minimum Python version.
+abi3t-py315 = ["abi3t"]
+
 # deprecated: no longer needed, raw-dylib is used instead
 generate-import-lib = ["pyo3-ffi/generate-import-lib"]
 

guide/src/python-from-rust/calling-existing-code.md

@@ -154,10 +154,13 @@ mod foo {
     }
 }
 
+# #[cfg(not(Py_TARGET_ABI3T))]
 fn main() -> PyResult<()> {
     pyo3::append_to_inittab!(foo);
     Python::attach(|py| Python::run(py, c"import foo; foo.add_one(6)", None, None))
 }
+# #[cfg(Py_TARGET_ABI3T)]
+# fn main() -> () {}
 ```
 
 If `append_to_inittab` cannot be used due to constraints in the program, an alternative is to create a module using [`PyModule::new`] and insert it manually into `sys.modules`:

newsfragments/5924.added.md

@@ -0,0 +1,7 @@
+* Added a PythonAbi struct, along with PythonAbiKind, StableAbi, and GilUsed
+enums to pyo3-build-config. These types allow specifying the Python ABI to use
+for a build. You can construct a PythonAbi struct using a PythonAbiBuilder
+struct.
+
+* Added an InterpreterConfigBuilder struct for building InterpreterConfig
+structs with a more ergonomic syntax.

newsfragments/5924.changed.md

@@ -0,0 +1,6 @@
+* The boolean `abi3` field of `pyo3_build_config::impl_::InterpreterConfig` is now
+  deprecated and has been replaced by a target_abi field, which is a `PythonAbi`
+  struct.
+* The InterpreterConfig::from_interpreter function now accepts a second
+  `abi3_version` argument. The old behavior is the same as passing
+  `abi3_version = None` .

noxfile.py

@@ -86,6 +86,9 @@ def _supported_interpreter_versions(
 
 PY_VERSIONS = _supported_interpreter_versions("cpython")
 ABI3_PY_VERSIONS = [p for p in PY_VERSIONS if not p.endswith("t")]
+ABI3T_PY_VERSIONS = [
+    p for p in PY_VERSIONS if p.endswith("t") and int(p.split(".")[1].strip("t")) > 14
+]
 PYPY_VERSIONS = _supported_interpreter_versions("pypy")
 
 
@@ -97,7 +100,7 @@ def test(session: nox.Session) -> None:
 
 @nox.session(name="test-rust", venv_backend="none")
 def test_rust(session: nox.Session):
-    _run_cargo_test(session, package="pyo3-build-config")
+    _run_cargo_test(session, package="pyo3-build-config", features="resolve-config")
     _run_cargo_test(session, package="pyo3-macros-backend")
     _run_cargo_test(session, package="pyo3-macros")
 
@@ -124,15 +127,11 @@ def test_rust(session: nox.Session):
         # We need to pass the feature set to the test command
         # so that it can be used in the test code
         # (e.g. for `#[cfg(feature = "abi3-py38")]`)
-        if feature_set and "abi3" in feature_set and FREE_THREADED_BUILD:
-            # free-threaded builds don't support abi3 yet
-            continue
-
         _run_cargo_test(session, features=feature_set, extra_flags=flags)
-
         if (
             feature_set
             and "abi3" in feature_set
+            and "abi3t" not in feature_set
             and "full" in feature_set
             and sys.version_info >= (3, 9)
         ):
@@ -143,6 +142,20 @@ def test_rust(session: nox.Session):
                 extra_flags=flags,
             )
 
+        if (
+            feature_set
+            and "abi3t" in feature_set
+            and "full" in feature_set
+            and sys.version_info >= (3, 16)
+        ):
+            # run abi3t-py315 tests to check for abi3t forward
+            # compatibility
+            _run_cargo_test(
+                session,
+                features=feature_set.replace("abi3t", "abi3t-py315"),
+                extra_flags=flags,
+            )
+
 
 @nox.session(name="test-py", venv_backend="none")
 def test_py(session: nox.Session) -> None:
@@ -1194,7 +1207,7 @@ def test_version_limits(session: nox.Session):
     with _config_file() as config_file:
         env["PYO3_CONFIG_FILE"] = config_file.name
 
-        assert "3.6" not in PY_VERSIONS
+        assert "3.7" not in PY_VERSIONS
         config_file.set("CPython", "3.6")
         _run_cargo(session, "check", env=env, expect_error=True)
 
@@ -1216,6 +1229,7 @@ def test_version_limits(session: nox.Session):
         config_file.set("CPython", "3.16")
         env["PYO3_USE_ABI3_FORWARD_COMPATIBILITY"] = "1"
         _run_cargo(session, "check", env=env)
+        del env["PYO3_USE_ABI3_FORWARD_COMPATIBILITY"]
 
         # we only support 3.11 PyPy
         assert "3.10" not in PYPY_VERSIONS
@@ -1230,6 +1244,23 @@ def test_version_limits(session: nox.Session):
         config_file.set("CPython", "3.14t")
         _run_cargo(session, "check", env=env)
 
+        # 3.15t is PyO3's maximum version of free-threaded Python
+        config_file.set("CPython", "3.15t")
+        _run_cargo(session, "check", env=env)
+
+        # 3.16t should build with abi3t forward compatibility
+        config_file.set("CPython", "3.16t")
+        env["PYO3_USE_ABI3T_FORWARD_COMPATIBILITY"] = "1"
+        _run_cargo(session, "check", env=env)
+        del env["PYO3_USE_ABI3T_FORWARD_COMPATIBILITY"]
+
+        # 3.17t isn't supported
+        config_file.set("CPython", "3.17t")
+        _run_cargo(session, "check", env=env, expect_error=True)
+
+        # 3.17t CPython should build if abi3 is explicitly requested
+        _run_cargo(session, "check", "--features=pyo3/abi3t", env=env)
+
     # attempt to build with latest version and check that abi3 version
     # configured matches the feature
     max_minor_version = max(int(v.split(".")[1]) for v in ABI3_PY_VERSIONS)
@@ -1251,7 +1282,7 @@ def test_version_limits(session: nox.Session):
     # "An abi3-py3* feature must be specified when compiling without a Python
     # interpreter."
     #
-    # then `ABI3_MAX_MINOR` in `pyo3-build-config/src/impl_.rs` is probably outdated.
+    # then `STABLE_ABI_MAX_MINOR` in `pyo3-build-config/src/impl_.rs` is probably outdated.
     assert f"version=3.{max_minor_version}" in stderr, (
         f"Expected to see version=3.{max_minor_version}, got: \n\n{stderr}"
     )
@@ -1271,6 +1302,9 @@ def _check_raw_dylib_macro(session: nox.Session):
         if minor >= 13:
             expected_dlls.add(f"python3{minor}t")
             expected_dlls.add(f"python3{minor}t_d")
+        if minor >= 15:
+            expected_dlls.add("python3t")
+            expected_dlls.add("python3t_d")
 
     # PyPy DLL names (libpypy3.X-c.dll)
     pypy_min, pypy_max = _parse_supported_interpreter_version("pypy")
@@ -1415,6 +1449,10 @@ def check_feature_powerset(session: nox.Session):
         f"abi3-py3{ver.split('.')[1]}" for ver in ABI3_PY_VERSIONS
     }
 
+    EXPECTED_ABI3T_FEATURES = {
+        f"abi3t-py3{ver.split('.')[1].strip('t')}" for ver in ABI3T_PY_VERSIONS
+    }
+
     EXCLUDED_FROM_FULL = {
         "nightly",
         "extension-module",
@@ -1428,20 +1466,37 @@ def check_feature_powerset(session: nox.Session):
     features = cargo_toml["features"]
 
     full_feature = set(features["full"])
-    abi3_features = {feature for feature in features if feature.startswith("abi3")}
+    abi3_features = {
+        feature
+        for feature in features
+        if feature.startswith("abi3") and not feature.startswith("abi3t")
+    }
     abi3_version_features = abi3_features - {"abi3"}
 
-    unexpected_abi3_features = abi3_version_features - EXPECTED_ABI3_FEATURES
-    if unexpected_abi3_features:
+    abi3t_features = {feature for feature in features if feature.startswith("abi3t")}
+    abi3t_version_features = abi3t_features - {"abi3t"}
+
+    unexpected_stable_abi_features = (
+        abi3_version_features - EXPECTED_ABI3_FEATURES - EXPECTED_ABI3T_FEATURES
+    )
+    if unexpected_stable_abi_features:
         session.error(
-            f"unexpected `abi3` features found in Cargo.toml: {unexpected_abi3_features}"
+            f"unexpected `abi3` or `abi3t` features found in Cargo.toml: {unexpected_stable_abi_features}"
         )
 
     missing_abi3_features = EXPECTED_ABI3_FEATURES - abi3_version_features
     if missing_abi3_features:
         session.error(f"missing `abi3` features in Cargo.toml: {missing_abi3_features}")
 
-    expected_full_feature = features.keys() - EXCLUDED_FROM_FULL - abi3_features
+    missing_abi3t_features = EXPECTED_ABI3T_FEATURES - abi3t_version_features
+    if missing_abi3t_features:
+        session.error(
+            f"missing `abi3t` features in Cargo.toml: {missing_abi3t_features}"
+        )
+
+    expected_full_feature = (
+        features.keys() - EXCLUDED_FROM_FULL - abi3_features - abi3t_features
+    )
 
     uncovered_features = expected_full_feature - full_feature
     if uncovered_features:
@@ -1470,6 +1525,7 @@ def check_feature_powerset(session: nox.Session):
     features_to_skip = [
         *(EXCLUDED_FROM_FULL),
         *abi3_version_features,
+        *abi3t_version_features,
     ]
 
     # deny warnings
@@ -1482,17 +1538,18 @@ def check_feature_powerset(session: nox.Session):
         subcommand = "minimal-versions"
 
     comma_join = ",".join
-    _run_cargo(
-        session,
-        subcommand,
-        "--feature-powerset",
-        '--optional-deps=""',
-        f'--skip="{comma_join(features_to_skip)}"',
-        *(f"--group-features={comma_join(group)}" for group in features_to_group),
-        "check",
-        "--all-targets",
-        env=env,
-    )
+    for abi_name in ["abi3", "abi3t"]:
+        _run_cargo(
+            session,
+            subcommand,
+            "--feature-powerset",
+            '--optional-deps=""',
+            f'--skip="{comma_join(features_to_skip + [abi_name])}"',
+            *(f"--group-features={comma_join(group)}" for group in features_to_group),
+            "check",
+            "--all-targets",
+            env=env,
+        )
 
 
 @nox.session(name="update-ui-tests", venv_backend="none")
@@ -1608,6 +1665,22 @@ def _get_feature_sets() -> Tuple[Optional[str], ...]:
     if is_rust_nightly():
         features += ",nightly"
 
+    if FREE_THREADED_BUILD:
+        if sys.version_info >= (3, 15):
+            return (None, "abi3t", features, f"abi3t,{features}")
+        else:
+            return (None, features)
+
+    # do fewer abi3t builds?
+    if sys.version_info >= (3, 15):
+        return (
+            None,
+            "abi3",
+            "abi3t",
+            features,
+            f"abi3,{features}",
+            f"abi3t,{features}",
+        )
     return (None, "abi3", features, f"abi3,{features}")