Fix issues around crates enabling abi3 and abi3t features

guide/src/bindings.md

@@ -14,25 +14,36 @@ maturin automatically detects pyo3 bindings when it's added as a dependency in `
 
 ### `Py_LIMITED_API`/abi3
 
-The pyo3 bindings supports the Python stable ABI (`Py_LIMITED_API`/abi3/abi3t).
-You can use it by enabling `"abi3"` and/or `"abi3t"` features. We suggest
-picking a minimum supported Python version for both features:
+The pyo3 bindings support the Python stable ABI (`Py_LIMITED_API`/abi3/abi3t).
+You can use it by enabling both `abi3` and `abi3t` features with a minimum
+supported Python version for each:
 
 ```toml
 pyo3 = { version = "0.29.0", features = ["abi3-py310", "abi3t-py315"] }
 ```
 
-When selecting a specific interpreter to build against, this will produce an
-`abi3-py310` wheel for Python 3.14 and older and an `abi3.abi3t-py315` wheel on
-Python 3.15 and newer. If you build with `--find-interpreters`, maturin will
-produce an `abi3-py310`, `cp314t-cp314` and an `abi3.abi3t-py315` wheel. These
-three wheels cover all non-EOL and non-experimental builds of CPython. Other
-python implementations like RustPython may also target the abi3t ABI in the
-future.
-
-An `abi3-py310` wheel supports all GIL-enabled Python
-versions from Python 3.10 to Python 3.14 and the `abi3.abi3t` wheel supports
-Python 3.15 and all newer versions of CPython.
+A single maturin build selects one stable ABI family. If you want to publish
+both a GIL-enabled `abi3` wheel and an `abi3t` wheel, run separate wheel builds
+explicitly, with compatible interpreters:
+
+```console
+maturin build --interpreter python3.10
+maturin build --interpreter python3.15t
+```
+
+A GIL-enabled CPython 3.15 or newer interpreter can also build the `abi3t`
+wheel when using PyO3 0.29 or newer.
+
+An `abi3-py310` wheel supports all GIL-enabled CPython
+versions from Python 3.10 and newer, while the `abi3.abi3t` wheel supports
+Python 3.15 and all newer versions of CPython. Free-threaded CPython 3.14 does
+not support the `abi3t` stable ABI, so maturin builds a version-specific
+`cp314-cp314t` wheel for it instead.
+
+Do not rely on a single build with both `abi3` and `abi3t` Cargo features to
+produce both stable ABI wheels. maturin will choose at most one stable ABI
+family for the build and emit version-specific fallback wheels for interpreters
+that cannot use that family.
 
 > **Note**: Read more about stable ABI support in [pyo3's
 >     documentation](https://pyo3.rs/latest/building-and-distribution#py_limited_apiabi3abi3t). You

src/bridge/detection.rs

@@ -5,7 +5,8 @@
 //! whether abi3 is enabled, and whether `generate-import-lib` is active.
 
 use super::{
-    BridgeModel, PyO3, PyO3Crate, PyO3MetadataRaw, StableAbi, StableAbiKind, StableAbiVersion,
+    ABI3T_MINIMUM_PYTHON_MINOR, BridgeModel, PyO3, PyO3Crate, PyO3MetadataRaw, StableAbi,
+    StableAbiKind, StableAbiVersion,
 };
 use crate::PyProjectToml;
 use crate::pyproject_toml::{FeatureConditionEnv, FeatureSpec};
@@ -123,7 +124,7 @@ pub fn find_bridge(cargo_metadata: &Metadata, bridge: Option<&str>) -> Result<Br
                 }
             }
 
-            return if let Some(stable_abi) = has_stable_abi(&deps, &no_extra_features)? {
+            return if let Some(stable_abi) = has_stable_abi(&deps, &no_extra_features, &[])? {
                 let pyo3 = bridge.pyo3().expect("should be pyo3 bindings");
                 let bindings = PyO3 {
                     crate_name: lib,
@@ -141,33 +142,27 @@ pub fn find_bridge(cargo_metadata: &Metadata, bridge: Option<&str>) -> Result<Br
     Ok(bridge)
 }
 
-/// Upgrade a bridge model to abi3 if conditional pyo3/pyo3-ffi features
-/// from pyproject.toml match at least one of the given interpreters.
+/// Select the stable ABI for a bridge model after interpreter resolution.
 ///
 /// This is the second phase of bridge detection: [`find_bridge`] excludes
-/// conditional features, then after interpreter resolution this function
-/// re-checks whether any conditional abi3 feature applies.
+/// conditional features and picks a conservative default, then after
+/// interpreter resolution this function re-checks plain and conditional
+/// stable ABI features and chooses the single stable ABI family this build
+/// should attempt.
 pub fn upgrade_bridge_stable_abi(
     bridge: BridgeModel,
     cargo_metadata: &Metadata,
     pyproject: Option<&PyProjectToml>,
     interpreters: &[crate::PythonInterpreter],
 ) -> Result<BridgeModel> {
-    // Only relevant for pyo3 bridges without abi3 already set
+    // Only relevant for pyo3 bridges
     let Some(pyo3) = bridge.pyo3() else {
         return Ok(bridge);
     };
-    if pyo3.stable_abi.is_some() {
-        return Ok(bridge);
-    }
-
-    let extra_pyo3_features = pyo3_features_from_conditional(pyproject, interpreters);
-    if extra_pyo3_features.is_empty() {
-        return Ok(bridge);
-    }
 
     let deps = current_crate_dependencies(cargo_metadata)?;
-    if let Some(stable_abi) = has_stable_abi(&deps, &extra_pyo3_features)? {
+    let extra_pyo3_features = pyo3_features_from_conditional(pyproject, interpreters);
+    if let Some(stable_abi) = has_stable_abi(&deps, &extra_pyo3_features, interpreters)? {
         let upgraded = PyO3 {
             stable_abi: Some(stable_abi),
             ..pyo3.clone()
@@ -222,12 +217,27 @@ pub fn has_windows_import_lib_support(cargo_metadata: &Metadata) -> Result<bool>
 fn has_stable_abi(
     deps: &HashMap<&str, &Node>,
     extra_features: &HashMap<&str, Vec<String>>,
+    interpreters: &[crate::PythonInterpreter],
 ) -> Result<Option<StableAbi>> {
     let abi3t = has_stable_abi_from_kind(deps, extra_features, StableAbiKind::Abi3t)?;
-    if abi3t.is_some() {
-        return Ok(abi3t);
-    }
-    has_stable_abi_from_kind(deps, extra_features, StableAbiKind::Abi3)
+    let abi3 = has_stable_abi_from_kind(deps, extra_features, StableAbiKind::Abi3)?;
+
+    let selected = [abi3t, abi3].into_iter().flatten().find(|stable_abi| {
+        interpreters.iter().any(|interpreter| {
+            interpreter.has_stable_api(stable_abi.kind)
+                && stable_abi
+                    .version
+                    .min_version()
+                    .is_none_or(|(major, minor)| {
+                        (interpreter.major as u8, interpreter.minor as u8) >= (major, minor)
+                    })
+        })
+    });
+
+    // If no resolved interpreter can use either stable ABI, keep abi3 as the
+    // conservative project marker when available; the build will fall back to
+    // version-specific wheels for the non-matching interpreters.
+    Ok(selected.or(abi3).or(abi3t))
 }
 
 /// pyo3 supports building stable abi wheels if the unstable-api feature is not selected
@@ -270,6 +280,11 @@ fn has_stable_abi_from_kind(
                 .min();
             match min_stable_abi_version {
                 Some((major, minor)) => {
+                    let (major, minor) = if abi_kind == StableAbiKind::Abi3t {
+                        (major, minor).max((3, ABI3T_MINIMUM_PYTHON_MINOR))
+                    } else {
+                        (major, minor)
+                    };
                     return Ok(Some(StableAbi {
                         kind: abi_kind,
                         version: StableAbiVersion::Version(major, minor),

src/bridge/mod.rs

@@ -12,6 +12,9 @@ use crate::python_interpreter::{
     PythonInterpreter,
 };
 
+/// First CPython minor version that supports PEP 803 stable ABI wheels.
+pub const ABI3T_MINIMUM_PYTHON_MINOR: u8 = 15;
+
 /// pyo3 binding crate
 #[derive(Clone, Copy, PartialEq, Eq)]
 pub enum PyO3Crate {
@@ -207,7 +210,7 @@ pub struct PyO3 {
     pub crate_name: PyO3Crate,
     /// pyo3 bindings crate version
     pub version: semver::Version,
-    /// abi3 support
+    /// Stable ABI support.
     pub stable_abi: Option<StableAbi>,
     /// pyo3 metadata
     pub metadata: Option<PyO3Metadata>,
@@ -376,22 +379,20 @@ impl BridgeModel {
     /// abi3 targets ≥ 3.11) return `false` so that `Py_LIMITED_API` is not
     /// defined and interpreter‑specific linker names are used.
     pub fn is_stable_abi_for_interpreter(&self, interpreter: &PythonInterpreter) -> bool {
-        self.pyo3()
-            .and_then(|pyo3| pyo3.stable_abi.as_ref())
-            .is_some_and(|stable_abi| {
-                if !interpreter.has_stable_api(stable_abi.kind) {
-                    return false;
-                }
-                if matches!(stable_abi.kind, StableAbiKind::Abi3) && interpreter.gil_disabled {
-                    return false;
-                };
-                match stable_abi.version.min_version() {
-                    Some((major, minor)) => {
+        self.stable_abi_for_interpreter(interpreter).is_some()
+    }
+
+    /// Return the stable ABI kind this bridge can use for a specific interpreter.
+    pub fn stable_abi_for_interpreter(&self, interpreter: &PythonInterpreter) -> Option<StableAbi> {
+        self.pyo3()?.stable_abi.filter(|stable_abi| {
+            interpreter.has_stable_api(stable_abi.kind)
+                && stable_abi
+                    .version
+                    .min_version()
+                    .is_none_or(|(major, minor)| {
                         (interpreter.major as u8, interpreter.minor as u8) >= (major, minor)
-                    }
-                    None => true, // CurrentPython → compatible when stable ABI is supported
-                }
-            })
+                    })
+        })
     }
 
     /// free-threaded Python support

src/build_context/builder.rs

@@ -111,24 +111,13 @@ impl BuildContextBuilder {
             })
         });
 
-        // Check whether conditional pyo3/pyo3-ffi features exist in pyproject.toml
-        // AND pyproject features are actually active (not overridden by CLI --features).
-        // When CLI --features is set, pyproject features are ignored at compile time
-        // (see cargo_options.merge_with_pyproject_toml), so bridge inference must
-        // ignore them too to stay in sync.
-        let has_conditional_pyo3_features = pyproject
-            .and_then(|p| p.maturin())
-            .and_then(|m| m.features.as_ref())
-            .is_some_and(|specs| {
-                // Only consider conditional features when pyproject features
-                // were actually adopted (not overridden by CLI).
-                let cli_overrides = !cargo_options.features.is_empty()
-                    && !pyproject_toml_maturin_options.contains(&"features");
-                !cli_overrides
-                    && FeatureSpec::split(specs.clone()).1.iter().any(|c| {
-                        c.feature.starts_with("pyo3/") || c.feature.starts_with("pyo3-ffi/")
-                    })
-            });
+        let cli_overrides_pyproject_features = !cargo_options.features.is_empty()
+            && !pyproject_toml_maturin_options.contains(&"features");
+        let pyproject_for_stable_abi = if cli_overrides_pyproject_features {
+            None
+        } else {
+            pyproject
+        };
 
         // Detect bridge without conditional pyo3 features — those are
         // evaluated after interpreter resolution via upgrade_bridge_stable_abi.
@@ -161,14 +150,15 @@ impl BuildContextBuilder {
             &cargo_metadata,
         )?;
 
-        // Upgrade bridge to abi3 if conditional pyo3 features
-        // (e.g. abi3-py311 gated on python-version>=3.11) match any
-        // of the resolved interpreters.
-        let bridge = if has_conditional_pyo3_features {
-            upgrade_bridge_stable_abi(bridge, &cargo_metadata, pyproject, &interpreter)?
-        } else {
-            bridge
-        };
+        // Select the stable ABI after interpreter resolution. This allows
+        // combined abi3/abi3t feature sets to choose the one stable ABI family
+        // this build can actually produce.
+        let bridge = upgrade_bridge_stable_abi(
+            bridge,
+            &cargo_metadata,
+            pyproject_for_stable_abi,
+            &interpreter,
+        )?;
         debug!("Resolved bridge model: {:?}", bridge);
         if let Some(stable_abi) = bridge.pyo3().and_then(|p| p.stable_abi.as_ref()) {
             match stable_abi.version {