Opaque PyObject ABI support

.github/workflows/ci.yml

@@ -64,6 +64,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]
@@ -612,7 +620,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

@@ -115,7 +115,14 @@ abi3-py310 = ["abi3-py311", "pyo3-build-config/abi3-py310", "pyo3-ffi/abi3-py310
 abi3-py311 = ["abi3-py312", "pyo3-build-config/abi3-py311", "pyo3-ffi/abi3-py311"]
 abi3-py312 = ["abi3-py313", "pyo3-build-config/abi3-py312", "pyo3-ffi/abi3-py312"]
 abi3-py313 = ["abi3-py314", "pyo3-build-config/abi3-py313", "pyo3-ffi/abi3-py313"]
-abi3-py314 = ["abi3", "pyo3-build-config/abi3-py314", "pyo3-ffi/abi3-py314"]
+abi3-py314 = ["abi3-py315", "pyo3-build-config/abi3-py314", "pyo3-ffi/abi3-py314"]
+abi3-py315 = ["abi3", "pyo3-build-config/abi3-py315", "pyo3-ffi/abi3-py315"]
+
+# Use the free-threaded limited API. See https://www.python.org/dev/peps/pep-803/ for more.
+abi3t = ["pyo3-build-config/abi3t", "pyo3-ffi/abi3t"]
+
+# With abi3t, we can manually set the minimum Python version.
+abi3t-py315 = ["abi3t", "pyo3-build-config/abi3t-py315"]
 
 # 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`:

noxfile.py

@@ -85,10 +85,10 @@ def _supported_interpreter_versions(
 
 
 PY_VERSIONS = _supported_interpreter_versions("cpython")
-# We don't yet support abi3-py315 but do support cp315 and cp315t
-# version-specific builds
 ABI3_PY_VERSIONS = [p for p in PY_VERSIONS if not p.endswith("t")]
-ABI3_PY_VERSIONS.remove("3.15")
+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")
 
 
@@ -127,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)
         ):
@@ -146,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:
@@ -1128,22 +1138,23 @@ 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)
 
-        assert "3.16" not in PY_VERSIONS
-        config_file.set("CPython", "3.16")
+        assert "3.17" not in PY_VERSIONS
+        config_file.set("CPython", "3.17")
         _run_cargo(session, "check", env=env, expect_error=True)
 
-        # 3.16 CPython should build if abi3 is explicitly requested
+        # 3.17 CPython should build if abi3 is explicitly requested
         _run_cargo(session, "check", "--features=pyo3/abi3", env=env)
 
-        # 3.15 CPython should build with forward compatibility
-        # TODO: check on 3.16 when adding abi3-py315 support
-        config_file.set("CPython", "3.15")
+        # 3.16 CPython should build with forward compatibility
+        # TODO: check on 3.17 when adding abi3-py316 support
+        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"]
 
         assert "3.10" not in PYPY_VERSIONS
         config_file.set("PyPy", "3.10")
@@ -1157,6 +1168,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)
@@ -1178,7 +1206,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}"
     )
@@ -1342,6 +1370,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",
@@ -1355,20 +1387,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:
@@ -1397,6 +1446,7 @@ def check_feature_powerset(session: nox.Session):
     features_to_skip = [
         *(EXCLUDED_FROM_FULL),
         *abi3_version_features,
+        *abi3t_version_features,
     ]
 
     # deny warnings
@@ -1409,17 +1459,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")
@@ -1508,6 +1559,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}")
 
 

pyo3-build-config/Cargo.toml

@@ -38,7 +38,12 @@ abi3-py310 = ["abi3-py311"]
 abi3-py311 = ["abi3-py312"]
 abi3-py312 = ["abi3-py313"]
 abi3-py313 = ["abi3-py314"]
-abi3-py314 = ["abi3"]
+abi3-py314 = ["abi3-py315"]
+abi3-py315 = ["abi3"]
+
+# These features are enabled by pyo3 when building free-threaded Stable ABI extension modules.
+abi3t = []
+abi3t-py315 = ["abi3t"]
 
 [package.metadata.docs.rs]
 features = ["resolve-config"]