Merge branch 'main' into rwlockext_trait

Author: Tom Dyas

.github/workflows/build.yml

@@ -126,12 +126,10 @@ jobs:
         if: ${{ endsWith(inputs.python-version, '-dev') || (steps.ffi-changes.outputs.changed == 'true' && inputs.rust == 'stable' && !startsWith(inputs.python-version, 'graalpy') && !(inputs.python-version == 'pypy3.9' && contains(inputs.os, 'windows'))) }}
         run: nox -s ffi-check
 
-      - if: ${{ github.event_name != 'merge_group' }}
-        name: Install cargo-llvm-cov
+      - name: Install cargo-llvm-cov
         uses: taiki-e/install-action@cargo-llvm-cov
 
-      - if: ${{ github.event_name != 'merge_group' }}
-        name: Prepare coverage environment
+      - name: Prepare coverage environment
         run: |
           cargo llvm-cov clean --workspace --profraw-only
           nox -s set-coverage-env
@@ -148,8 +146,7 @@ jobs:
         env:
           CARGO_TARGET_DIR: ${{ github.workspace }}/target
 
-      - if: ${{ github.event_name != 'merge_group' }}
-        name: Generate coverage report
+      - name: Generate coverage report
         # needs investigation why llvm-cov fails on windows-11-arm
         continue-on-error: ${{ inputs.os == 'windows-11-arm' }}
         run: cargo llvm-cov
@@ -160,8 +157,7 @@ jobs:
           --package=pyo3-ffi
           report --codecov --output-path coverage.json
 
-      - if: ${{ github.event_name != 'merge_group' }}
-        name: Upload coverage report
+      - name: Upload coverage report
         uses: codecov/codecov-action@v5
         # needs investigation why llvm-cov fails on windows-11-arm
         continue-on-error: ${{ inputs.os == 'windows-11-arm' }}

.github/workflows/ci.yml

@@ -145,7 +145,7 @@ jobs:
       fail-fast: ${{ !contains(github.event.pull_request.labels.*.name, 'CI-no-fail-fast') }}
       matrix:
         rust: [stable]
-        python-version: ["3.13"]
+        python-version: ["3.14"]
         platform:
           [
             {
@@ -159,7 +159,7 @@ jobs:
               rust-target: "x86_64-unknown-linux-gnu",
             },
             {
-              os: "ubuntu-22.04-arm",
+              os: "ubuntu-24.04-arm",
               python-architecture: "arm64",
               rust-target: "aarch64-unknown-linux-gnu",
             },
@@ -173,12 +173,17 @@ jobs:
               python-architecture: "x86",
               rust-target: "i686-pc-windows-msvc",
             },
+            {
+              os: "windows-11-arm",
+              python-architecture: "arm64",
+              rust-target: "aarch64-pc-windows-msvc",
+            },
           ]
         include:
           # Test nightly Rust on PRs so that PR authors have a chance to fix nightly
           # failures, as nightly does not block merge.
           - rust: nightly
-            python-version: "3.13"
+            python-version: "3.14"
             platform:
               {
                 os: "ubuntu-latest",
@@ -188,25 +193,7 @@ jobs:
           # Also test free-threaded Python just for latest Python version, on ubuntu
           # (run for all OSes on build-full)
           - rust: stable
-            python-version: "3.13t"
-            platform:
-              {
-                os: "ubuntu-latest",
-                python-architecture: "x64",
-                rust-target: "x86_64-unknown-linux-gnu",
-              }
-          # As we approach 3.14 release date, let's also have testing for 3.14 and 3.14t
-          # on linux
-          - rust: stable
-            python-version: "3.14-dev"
-            platform:
-              {
-                os: "ubuntu-latest",
-                python-architecture: "x64",
-                rust-target: "x86_64-unknown-linux-gnu",
-              }
-          - rust: stable
-            python-version: "3.14t-dev"
+            python-version: "3.14t"
             platform:
               {
                 os: "ubuntu-latest",
@@ -243,8 +230,8 @@ jobs:
             "3.12",
             "3.13",
             "3.13t",
-            "3.14-dev",
-            "3.14t-dev",
+            "3.14",
+            "3.14t",
             "pypy3.9",
             "pypy3.10",
             "pypy3.11",
@@ -271,7 +258,7 @@ jobs:
         include:
           # Test minimal supported Rust version
           - rust: ${{ needs.resolve.outputs.MSRV }}
-            python-version: "3.13"
+            python-version: "3.14"
             platform:
               {
                 os: "ubuntu-latest",
@@ -281,7 +268,7 @@ jobs:
 
           # Test the `nightly` feature
           - rust: nightly
-            python-version: "3.13"
+            python-version: "3.14"
             platform:
               {
                 os: "ubuntu-latest",
@@ -291,7 +278,7 @@ jobs:
 
           # Run rust beta to help catch toolchain regressions
           - rust: beta
-            python-version: "3.13"
+            python-version: "3.14"
             platform:
               {
                 os: "ubuntu-latest",
@@ -301,15 +288,15 @@ jobs:
 
           # Test 32-bit Windows and x64 macOS only with the latest Python version
           - rust: stable
-            python-version: "3.13"
+            python-version: "3.14"
             platform:
               {
                 os: "windows-latest",
                 python-architecture: "x86",
                 rust-target: "i686-pc-windows-msvc",
               }
           - rust: stable
-            python-version: "3.13"
+            python-version: "3.14"
             platform:
               {
                 os: "macos-latest",
@@ -337,17 +324,17 @@ jobs:
           #       python-architecture: "x64",
           #       rust-target: "x86_64-apple-darwin",
           #     }
-          # arm64 Linux runner is in public preview, so test 3.13 on it
+          # test latest Python on arm64 linux & windows runners
           - rust: stable
-            python-version: "3.13"
+            python-version: "3.14"
             platform:
               {
-                os: "ubuntu-22.04-arm",
+                os: "ubuntu-24.04-arm",
                 python-architecture: "arm64",
                 rust-target: "aarch64-unknown-linux-gnu",
               }
           - rust: stable
-            python-version: "3.13"
+            python-version: "3.14"
             platform:
               {
                 os: "windows-11-arm",
@@ -701,6 +688,21 @@ jobs:
     env:
       CARGO_BUILD_TARGET: ${{ matrix.platform.rust-target }}
 
+  test-introspection-pr:
+    needs: [fmt]
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'CI-build-full') && github.event_name == 'pull_request' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rust-src
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: python -m pip install --upgrade pip && pip install nox[uv]
+      - run: nox -s test-introspection
+
   conclusion:
     needs:
       - fmt

.github/workflows/coverage-pr-base.yml

@@ -21,7 +21,7 @@ jobs:
         uses: ./.github/actions/fetch-merge-base
         with:
           base_ref: "refs/heads/${{ github.event.pull_request.base.ref }}"
-          head_ref: "refs/pull/${{ github.event.pull_request.number }}/merge"
+          head_ref: "refs/pull/${{ github.event.pull_request.number }}/head"
       - name: Set PR base on codecov
         run: |
           pip install codecov-cli

Cargo.toml

@@ -48,12 +48,13 @@ chrono = { version = "0.4.25", default-features = false, optional = true }
 chrono-tz = { version = ">= 0.10, < 0.11", default-features = false, optional = true }
 either = { version = "1.9", optional = true }
 eyre = { version = ">= 0.6.8, < 0.7", optional = true }
-hashbrown = { version = ">= 0.15.0, < 0.16", optional = true, default-features = false }
+hashbrown = { version = ">= 0.15.0, < 0.17", optional = true, default-features = false }
 indexmap = { version = ">= 2.5.0, < 3", optional = true }
 jiff-02 = { package = "jiff", version = "0.2", optional = true }
-num-bigint = { version = "0.4.2", optional = true }
+num-bigint = { version = "0.4.4", optional = true }
 num-complex = { version = ">= 0.4.6, < 0.5", optional = true }
 num-rational = { version = "0.4.1", optional = true }
+num-traits = { version = "0.2.16", optional = true }
 ordered-float = { version = "5.0.0", default-features = false, optional = true }
 rust_decimal = { version = "1.15", default-features = false, optional = true }
 time = { version = "0.3.38", default-features = false, optional = true }
@@ -135,10 +136,12 @@ py-clone = []
 parking_lot = ["dep:parking_lot", "lock_api"]
 arc_lock = ["lock_api", "lock_api/arc_lock", "parking_lot?/arc_lock"]
 
+num-bigint = ["dep:num-bigint", "dep:num-traits"]
 bigdecimal = ["dep:bigdecimal", "num-bigint"]
 
 chrono-local = ["chrono/clock", "dep:iana-time-zone"]
 
+
 # Optimizes PyObject to Vec conversion and so on.
 nightly = []
 
@@ -203,6 +206,9 @@ let_unit_value = "warn"
 manual_assert = "warn"
 manual_ok_or = "warn"
 todo = "warn"
+# TODO: make this "warn"
+# https://github.com/PyO3/pyo3/issues/5487
+undocumented_unsafe_blocks = "allow"
 unnecessary_wraps = "warn"
 useless_transmute = "warn"
 used_underscore_binding = "warn"

Contributing.md

@@ -184,7 +184,7 @@ PyO3 supports all officially supported Python versions, as well as the latest Py
 If you plan to add support for a pre-release version of CPython, here's a (non-exhaustive) checklist:
 
  - [ ] Wait until the last alpha release (usually alpha7), since ABI is not guaranteed until the first beta release
- - [ ] Add prerelease_ver-dev (e.g. `3.14-dev`) to `‎.github/workflows/ci.yml`, and bump version in `noxfile.py`, `pyo3-ffi/Cargo.toml` under `max-version` within  `[package.metadata.cpython]`, and `max` within `pyo3-ffi/build.rs`
+ - [ ] Add prerelease_ver-dev (e.g. `3.14-dev`) to `.github/workflows/ci.yml`, and bump version in `noxfile.py`, `pyo3-ffi/Cargo.toml` under `max-version` within  `[package.metadata.cpython]`, and `max` within `pyo3-ffi/build.rs`
 - [ ] Add a new abi3-prerelease feature for the version (e.g. `abi3-py314`)
    - In `pyo3-build-config/Cargo.toml`, set abi3-most_current_stable to ["abi3-prerelease"] and abi3-prerelease to ["abi3"]
    - In `pyo3-ffi/Cargo.toml`, set abi3-most_current_stable to ["abi3-prerelease", "pyo3-build-config/abi3-most_current_stable"] and abi3-prerelease to ["abi3", "pyo3-build-config/abi3-prerelease"]

README.md

@@ -77,21 +77,18 @@ pyo3 = { version = "0.26.0", features = ["extension-module"] }
 **`src/lib.rs`**
 
 ```rust
-use pyo3::prelude::*;
-
-/// Formats the sum of two numbers as string.
-#[pyfunction]
-fn sum_as_string(a: usize, b: usize) -> PyResult<String> {
-    Ok((a + b).to_string())
-}
-
-/// A Python module implemented in Rust. The name of this function must match
+/// A Python module implemented in Rust. The name of this module must match
 /// the `lib.name` setting in the `Cargo.toml`, else Python will not be able to
 /// import the module.
-#[pymodule]
-fn string_sum(m: &Bound<'_, PyModule>) -> PyResult<()> {
-    m.add_function(wrap_pyfunction!(sum_as_string, m)?)?;
-    Ok(())
+#[pyo3::pymodule]
+mod string_sum {
+  use pyo3::prelude::*;
+
+  /// Formats the sum of two numbers as string.
+  #[pyfunction]
+  fn sum_as_string(a: usize, b: usize) -> PyResult<String> {
+    Ok((a + b).to_string())
+  }
 }
 ```
 

emscripten/pybuilddir.txt

@@ -9,6 +9,7 @@
 | `eq_int` | Implements `__eq__` using `__int__` for simple enums. |
 | <span style="white-space: pre">`extends = BaseType`</span>  | Use a custom baseclass. Defaults to [`PyAny`][params-1] |
 | <span style="white-space: pre">`freelist = N`</span> |  Implements a [free list][params-2] of size N. This can improve performance for types that are often created and deleted in quick succession. Profile your code to see whether `freelist` is right for you.  |
+| `from_py_object` | Implement `FromPyObject` for this pyclass. Requires the pyclass to be `Clone`. |
 | <span style="white-space: pre">`frozen`</span> | Declares that your pyclass is immutable. It removes the borrow checker overhead when retrieving a shared reference to the Rust struct, but disables the ability to get a mutable reference. |
 | `generic` | Implements runtime parametrization for the class following [PEP 560](https://peps.python.org/pep-0560/). |
 | `get_all` | Generates getters for all fields of the pyclass. |
@@ -21,6 +22,7 @@
 | `rename_all = "renaming_rule"` | Applies renaming rules to every getters and setters of a struct, or every variants of an enum. Possible values are: "camelCase", "kebab-case", "lowercase", "PascalCase", "SCREAMING-KEBAB-CASE", "SCREAMING_SNAKE_CASE", "snake_case", "UPPERCASE". |
 | `sequence` |  Inform PyO3 that this class is a [`Sequence`][params-sequence], and so leave its C-API mapping length slot empty. |
 | `set_all` | Generates setters for all fields of the pyclass. |
+| `skip_from_py_object` | Prevents this PyClass from participating in the `FromPyObject: PyClass + Clone` blanket implementation. This allows a custom `FromPyObject` impl, even if `self` is `Clone`. |
 | `str` | Implements `__str__` using the `Display` implementation of the underlying Rust datatype or by passing an optional format string `str="<format string>"`. *Note: The optional format string is only allowed for structs.  `name` and `rename_all` are incompatible with the optional format string.  Additional details can be found in the discussion on this [PR](https://github.com/PyO3/pyo3/pull/4233).* |
 | `subclass` | Allows other Python classes and `#[pyclass]` to inherit from this class. Enums cannot be subclassed. |
 | `unsendable` | Required if your struct is not [`Send`][params-3]. Rather than using `unsendable`, consider implementing your struct in a thread-safe way by e.g. substituting [`Rc`][params-4] with [`Arc`][params-5]. By using `unsendable`, your class will panic when accessed by another thread. Also note the Python's GC is multi-threaded and while unsendable classes will not be traversed on foreign threads to avoid UB, this can lead to memory leaks. |

guide/pyclass-parameters.md

@@ -464,7 +464,7 @@ enum RustyEnum {
 ```
 
 If the input is neither a string nor an integer, the error message will be:
-`"'<INPUT_TYPE>' cannot be converted to 'str | int'"`.
+`"'<INPUT_TYPE>' cannot be cast as 'str | int'"`.
 
 #### `#[derive(FromPyObject)]` Container Attributes
 - `pyo3(transparent)`
@@ -535,6 +535,31 @@ struct RustyStruct {
 # }
 ```
 
+#### ⚠ Phase-Out of `FromPyObject` blanket implementation for cloneable PyClasses ⚠
+Historically PyO3 has provided a blanket implementation for `#[pyclass]` types that also implement `Clone`, to allow extraction of such types by value. Over time this has turned out problematic for a few reasons, the major one being the prevention of custom conversions by downstream crates if their type is `Clone`. Over the next few releases the blanket implementation is gradually phased out, and eventually replaced by an opt-in option. As a first step of this migration a new `skip_from_py_object` option for `#[pyclass]` was introduced, to opt-out of the blanket implementation and allow downstream users to provide their own implementation:
+```rust
+# #![allow(dead_code)]
+# use pyo3::prelude::*;
+
+#[pyclass(skip_from_py_object)] // opt-out of the PyO3 FromPyObject blanket
+#[derive(Clone)]
+struct Number(i32);
+
+impl<'py> FromPyObject<'_, 'py> for Number {
+    type Error = PyErr;
+
+    fn extract(obj: pyo3::Borrowed<'_, 'py, pyo3::PyAny>) -> Result<Self, Self::Error> {
+        if let Ok(obj) = obj.cast::<Self>() { // first try extraction via class object
+            Ok(obj.borrow().clone())
+        } else {
+            obj.extract::<i32>().map(Self) // otherwise try integer directly
+        }
+    }
+}
+```
+
+As a second step the `from_py_object` option was introduced. This option also opts-out of the blanket implementation and instead generates a custom `FromPyObject` implementation for the pyclass which is functionally equivalent to the blanket.
+
 ### `IntoPyObject`
 The [`IntoPyObject`] trait defines the to-python conversion for a Rust type. All types in PyO3 implement this trait,
 as does a `#[pyclass]` which doesn't use `extends`.

guide/src/conversions/traits.md

@@ -172,6 +172,7 @@ Adds a dependency on [jiff@0.2](https://docs.rs/jiff/0.2) and requires MSRV 1.70
 - [DateTime](https://docs.rs/jiff/0.2/jiff/civil/struct.DateTime.html) -> [`PyDateTime`]({{#PYO3_DOCS_URL}}/pyo3/types/struct.PyDateTime.html)
 - [Zoned](https://docs.rs/jiff/0.2/jiff/struct.Zoned.html) -> [`PyDateTime`]({{#PYO3_DOCS_URL}}/pyo3/types/struct.PyDateTime.html)
 - [Timestamp](https://docs.rs/jiff/0.2/jiff/struct.Timestamp.html) -> [`PyDateTime`]({{#PYO3_DOCS_URL}}/pyo3/types/struct.PyDateTime.html)
+- [ISOWeekDate](https://docs.rs/jiff/0.2/jiff/civil/struct.ISOWeekDate.html) -> [`PyDate`]({{#PYO3_DOCS_URL}}/pyo3/types/struct.PyDate.html)
 
 ### `lock_api`