Merge branch 'main' into once-cell-ext

Author: davidhewitt

.github/workflows/ci.yml

@@ -415,9 +415,11 @@ jobs:
       - uses: Swatinem/rust-cache@v2
         with:
           save-if: ${{ github.ref == 'refs/heads/main' || contains(github.event.pull_request.labels.*.name, 'CI-save-pr-cache') }}
-      - uses: dtolnay/rust-toolchain@nightly
+      - uses: dtolnay/rust-toolchain@master
         with:
           components: rust-src
+          # FIXME: unpin once https://github.com/rust-lang/rust/issues/145437 is resolved
+          toolchain: nightly-2025-08-14
       - uses: taiki-e/install-action@cargo-careful
       - run: python -m pip install --upgrade pip && pip install nox
       - run: nox -s test-rust -- careful skip-full
@@ -437,9 +439,11 @@ jobs:
       - uses: Swatinem/rust-cache@v2
         with:
           save-if: ${{ github.ref == 'refs/heads/main' || contains(github.event.pull_request.labels.*.name, 'CI-save-pr-cache') }}
-      - uses: dtolnay/rust-toolchain@nightly
+      - uses: dtolnay/rust-toolchain@master
         with:
           components: rust-src
+          # FIXME: unpin once https://github.com/rust-lang/rust/issues/145437 is resolved
+          toolchain: nightly-2025-08-14
       - run: cargo rustdoc --lib --no-default-features --features full,jiff-02 -Zunstable-options --config "build.rustdocflags=[\"--cfg\", \"docsrs\"]"
 
   emscripten:

.github/workflows/gh-pages.yml

@@ -28,11 +28,6 @@ jobs:
 
       - uses: dtolnay/rust-toolchain@nightly
 
-      - name: Use nightly
-        run: |
-          rustup update nightly
-          rustup default nightly
-
       - name: Setup mdBook
         uses: taiki-e/install-action@v2
         with:
@@ -46,19 +41,39 @@ jobs:
           args: --version
           lycheeVersion: nightly
 
-      - name: Get current PyO3 version
-        run: |
-          PYO3_VERSION=$(cargo search pyo3 --limit 1 | head -1 | tr -s ' ' | cut -d ' ' -f 3 | tr -d '"')
-          echo "PYO3_VERSION=${PYO3_VERSION}" >> $GITHUB_ENV
-
       - name: Prepare tag
         id: prepare_tag
         run: |
           TAG_NAME="${GITHUB_REF##*/}"
           echo "tag_name=${TAG_NAME}" >> $GITHUB_OUTPUT
 
-      # Build the site
-      - name: Prepare the versioned guide entries
+      # This builds the book in target/guide/.
+      - name: Build the guide
+        run: |
+          python -m pip install --upgrade pip && pip install nox
+          nox -s ${{ github.event_name == 'release' && 'build-guide' || 'check-guide' }}
+        env:
+          PYO3_VERSION_TAG: ${{ steps.prepare_tag.outputs.tag_name }}
+          # allows lychee to get better rate limits from github
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      # We store the versioned guides on GitHub's gh-pages branch for convenience
+      # (the full gh-pages branch is pulled in the build-netlify-site step)
+      - name: Deploy the guide
+        if: ${{ github.event_name == 'release' }}
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./target/guide/
+          destination_dir: ${{ steps.prepare_tag.outputs.tag_name }}
+          full_commit_message: "Upload documentation for ${{ steps.prepare_tag.outputs.tag_name }}"
+
+      - name: Get current PyO3 version
+        run: |
+          PYO3_VERSION=$(cargo search pyo3 --limit 1 | head -1 | tr -s ' ' | cut -d ' ' -f 3 | tr -d '"')
+          echo "PYO3_VERSION=${PYO3_VERSION}" >> $GITHUB_ENV
+
+      - name: Build the site
         run: |
           python -m pip install --upgrade pip && pip install nox towncrier requests
           nox -s build-netlify-site -- ${{ (github.ref != 'refs/heads/main' && '--preview') || '' }}

.github/workflows/netlify-build.yml

@@ -236,9 +236,12 @@ about this topic.
 
 ## Articles and other media
 
+- [(Video) Using Rust in Free-Threaded vs Regular Python 3.13](https://www.youtube.com/watch?v=J7phN_M4GLM) - Jun 4, 2025
+- [(Video) Techniques learned from five years finding the way for Rust in Python](https://www.youtube.com/watch?v=KTQn_PTHNCw) - Feb 26, 2025
+- [(Podcast) Bridging Python and Rust: An Interview with PyO3 Maintainer David Hewitt](https://www.youtube.com/watch?v=P47JUMSQagU) - Aug 30, 2024
 - [(Video) PyO3: From Python to Rust and Back Again](https://www.youtube.com/watch?v=UmL_CA-v3O8) - Jul 3, 2024
 - [Parsing Python ASTs 20x Faster with Rust](https://www.gauge.sh/blog/parsing-python-asts-20x-faster-with-rust) - Jun 17, 2024
-- [(Video) How Python Harnesses Rust through PyO3](https://www.youtube.com/watch?v=UkZ_m3Wj2hA) - May 18, 2024
+- [(Video) How Python Harnesses Rust through PyO3](https://www.youtube.com/watch?v=UilujdubqVU) - May 18, 2024
 - [(Video) Combining Rust and Python: The Best of Both Worlds?](https://www.youtube.com/watch?v=lyG6AKzu4ew) - Mar 1, 2024
 - [(Video) Extending Python with Rust using PyO3](https://www.youtube.com/watch?v=T45ZEmSR1-s) - Dec 16, 2023
 - [A Week of PyO3 + rust-numpy (How to Speed Up Your Data Pipeline X Times)](https://terencezl.github.io/blog/2023/06/06/a-week-of-pyo3-rust-numpy/) - Jun 6, 2023
@@ -250,7 +253,7 @@ about this topic.
 - [Calling Rust from Python using PyO3](https://saidvandeklundert.net/learn/2021-11-18-calling-rust-from-python-using-pyo3/) - Nov 18, 2021
 - [davidhewitt's 2021 talk at Rust Manchester meetup](https://www.youtube.com/watch?v=-XyWG_klSAw&t=320s) - Aug 19, 2021
 - [Incrementally porting a small Python project to Rust](https://blog.waleedkhan.name/port-python-to-rust/) - Apr 29, 2021
-- [Vortexa - Integrating Rust into Python](https://www.vortexa.com/insight/integrating-rust-into-python) - Apr 12, 2021
+- [Vortexa - Integrating Rust into Python](https://www.vortexa.com/blog/integrating-rust-into-python) - Apr 12, 2021
 - [Writing and publishing a Python module in Rust](https://blog.yossarian.net/2020/08/02/Writing-and-publishing-a-python-module-in-rust) - Aug 2, 2020
 
 ## Contributing

README.md

@@ -13,7 +13,7 @@ use pyo3::prelude::*;
 
 #[pyfunction]
 #[pyo3(signature=(seconds, result=None))]
-async fn sleep(seconds: f64, result: Option<PyObject>) -> Option<PyObject> {
+async fn sleep(seconds: f64, result: Option<Py<PyAny>>) -> Option<Py<PyAny>> {
     let (tx, rx) = oneshot::channel();
     thread::spawn(move || {
         thread::sleep(Duration::from_secs_f64(seconds));

guide/src/async-await.md

@@ -413,7 +413,7 @@ impl SubSubClass {
     }
 
     #[staticmethod]
-    fn factory_method(py: Python<'_>, val: usize) -> PyResult<PyObject> {
+    fn factory_method(py: Python<'_>, val: usize) -> PyResult<Py<PyAny>> {
         let base = PyClassInitializer::from(BaseClass::new());
         let sub = base.add_subclass(SubClass { val2: val });
         if val % 2 == 0 {
@@ -748,7 +748,7 @@ To create a constructor which takes a positional class argument, you can combine
 # use pyo3::prelude::*;
 # use pyo3::types::PyType;
 # #[pyclass]
-# struct BaseClass(PyObject);
+# struct BaseClass(Py<PyAny>);
 #
 #[pymethods]
 impl BaseClass {
@@ -1385,7 +1385,12 @@ unsafe impl pyo3::type_object::PyTypeInfo for MyClass {
     #[inline]
     fn type_object_raw(py: pyo3::Python<'_>) -> *mut pyo3::ffi::PyTypeObject {
         <Self as pyo3::impl_::pyclass::PyClassImpl>::lazy_type_object()
-            .get_or_init(py)
+            .get_or_try_init(py)
+            .unwrap_or_else(|e| pyo3::impl_::pyclass::type_object_init_failed(
+                py,
+                e,
+                <Self as pyo3::type_object::PyTypeInfo>::NAME
+            ))
             .as_type_ptr()
     }
 }

guide/src/class.md

@@ -417,7 +417,7 @@ Let's create that helper function. The signature has to be `fn(&Bound<'_, PyAny>
 
 ```rust,no_run
 # #![allow(dead_code)]
-use std::os::raw::c_ulong;
+use std::ffi::c_ulong;
 use pyo3::prelude::*;
 use pyo3::ffi;
 

guide/src/class/numeric.md

@@ -59,7 +59,7 @@ given signatures should be interpreted as follows:
     #[pymethods]
     impl NotHashable {
         #[classattr]
-        const __hash__: Option<PyObject> = None;
+        const __hash__: Option<Py<PyAny>> = None;
     }
     ```
     </details>
@@ -162,15 +162,15 @@ use std::sync::Mutex;
 
 #[pyclass]
 struct MyIterator {
-    iter: Mutex<Box<dyn Iterator<Item = PyObject> + Send>>,
+    iter: Mutex<Box<dyn Iterator<Item = Py<PyAny>> + Send>>,
 }
 
 #[pymethods]
 impl MyIterator {
     fn __iter__(slf: PyRef<'_, Self>) -> PyRef<'_, Self> {
         slf
     }
-    fn __next__(slf: PyRefMut<'_, Self>) -> Option<PyObject> {
+    fn __next__(slf: PyRefMut<'_, Self>) -> Option<Py<PyAny>> {
         slf.iter.lock().unwrap().next()
     }
 }
@@ -283,7 +283,7 @@ Use the `#[pyclass(sequence)]` annotation to instruct PyO3 to fill the `sq_lengt
     #[pymethods]
     impl NoContains {
         #[classattr]
-        const __contains__: Option<PyObject> = None;
+        const __contains__: Option<Py<PyAny>> = None;
     }
     ```
     </details>
@@ -439,7 +439,7 @@ use pyo3::gc::PyVisit;
 
 #[pyclass]
 struct ClassWithGCSupport {
-    obj: Option<PyObject>,
+    obj: Option<Py<PyAny>>,
 }
 
 #[pymethods]

guide/src/class/protocols.md

@@ -1,6 +1,6 @@
 ## Mapping of Rust types to Python types
 
-When writing functions callable from Python (such as a `#[pyfunction]` or in a `#[pymethods]` block), the trait `FromPyObject` is required for function arguments, and `IntoPy<PyObject>` is required for function return values.
+When writing functions callable from Python (such as a `#[pyfunction]` or in a `#[pymethods]` block), the trait `FromPyObject` is required for function arguments, and `IntoPyObject` is required for function return values.
 
 Consult the tables in the following section to find the Rust types provided by PyO3 which implement these traits.
 
@@ -54,7 +54,6 @@ It is also worth remembering the following special types:
 | `Python<'py>`    | A GIL token, used to pass to PyO3 constructors to prove ownership of the GIL. |
 | `Bound<'py, T>`  | A Python object connected to the GIL lifetime. This provides access to most of PyO3's APIs. |
 | `Py<T>`          | A Python object isolated from the GIL lifetime. This can be sent to other threads. |
-| `PyObject`       | An alias for `Py<PyAny>`              |
 | `PyRef<T>`       | A `#[pyclass]` borrowed immutably.    |
 | `PyRefMut<T>`    | A `#[pyclass]` borrowed mutably.      |
 

guide/src/conversions/tables.md

@@ -580,7 +580,7 @@ forward the implementation to the inner type.
 
 // newtype tuple structs are implicitly `transparent`
 #[derive(IntoPyObject)]
-struct TransparentTuple(PyObject);
+struct TransparentTuple(Py<PyAny>);
 
 #[derive(IntoPyObject)]
 #[pyo3(transparent)]
@@ -599,7 +599,7 @@ For `enum`s each variant is converted according to the rules for `struct`s above
 
 #[derive(IntoPyObject)]
 enum Enum<'a, 'py, K: Hash + Eq, V> { // enums are supported and convert using the same
-    TransparentTuple(PyObject),       // rules on the variants as the structs above
+    TransparentTuple(Py<PyAny>),       // rules on the variants as the structs above
     #[pyo3(transparent)]
     TransparentStruct { inner: Bound<'py, PyAny> },
     Tuple(&'a str, HashMap<K, V>),
@@ -645,7 +645,7 @@ demonstrated below.
 ```rust,no_run
 # use pyo3::prelude::*;
 # #[allow(dead_code)]
-struct MyPyObjectWrapper(PyObject);
+struct MyPyObjectWrapper(Py<PyAny>);
 
 impl<'py> IntoPyObject<'py> for MyPyObjectWrapper {
     type Target = PyAny; // the Python type
@@ -741,7 +741,6 @@ In the example above we used `BoundObject::into_any` and `BoundObject::unbind` t
 [`FromPyObject`]: {{#PYO3_DOCS_URL}}/pyo3/conversion/trait.FromPyObject.html
 [`IntoPyObject`]: {{#PYO3_DOCS_URL}}/pyo3/conversion/trait.IntoPyObject.html
 [`IntoPyObjectExt`]: {{#PYO3_DOCS_URL}}/pyo3/conversion/trait.IntoPyObjectExt.html
-[`PyObject`]: {{#PYO3_DOCS_URL}}/pyo3/type.PyObject.html
 
 [`PyRef`]: {{#PYO3_DOCS_URL}}/pyo3/pycell/struct.PyRef.html
 [`PyRefMut`]: {{#PYO3_DOCS_URL}}/pyo3/pycell/struct.PyRefMut.html