feat: support anyio with a Cargo feature

Cargo.toml

@@ -69,6 +69,9 @@ default = ["macros"]
 # Enables support for `async fn` for `#[pyfunction]` and `#[pymethods]`.
 experimental-async = ["macros", "pyo3-macros/experimental-async"]
 
+# Switch coroutine implementation to anyio instead of asyncio
+anyio = ["experimental-async"]
+
 # Enables pyo3::inspect module and additional type information on FromPyObject
 # and IntoPy traits
 experimental-inspect = []

guide/src/SUMMARY.md

@@ -6,35 +6,36 @@
 
 - [Getting started](getting-started.md)
 - [Using Rust from Python](rust-from-python.md)
-  - [Python modules](module.md)
-  - [Python functions](function.md)
-    - [Function signatures](function/signature.md)
-    - [Error handling](function/error-handling.md)
-  - [Python classes](class.md)
-    - [Class customizations](class/protocols.md)
-      - [Basic object customization](class/object.md)
-      - [Emulating numeric types](class/numeric.md)
-      - [Emulating callable objects](class/call.md)
+    - [Python modules](module.md)
+    - [Python functions](function.md)
+        - [Function signatures](function/signature.md)
+        - [Error handling](function/error-handling.md)
+    - [Python classes](class.md)
+        - [Class customizations](class/protocols.md)
+            - [Basic object customization](class/object.md)
+            - [Emulating numeric types](class/numeric.md)
+            - [Emulating callable objects](class/call.md)
 - [Calling Python from Rust](python-from-rust.md)
-  - [Python object types](types.md)
-  - [Python exceptions](exception.md)
-  - [Calling Python functions](python-from-rust/function-calls.md)
-  - [Executing existing Python code](python-from-rust/calling-existing-code.md)
+    - [Python object types](types.md)
+    - [Python exceptions](exception.md)
+    - [Calling Python functions](python-from-rust/function-calls.md)
+    - [Executing existing Python code](python-from-rust/calling-existing-code.md)
 - [Type conversions](conversions.md)
-  - [Mapping of Rust types to Python types](conversions/tables.md)
-  - [Conversion traits](conversions/traits.md)
+    - [Mapping of Rust types to Python types](conversions/tables.md)
+    - [Conversion traits](conversions/traits.md)
 - [Using `async` and `await`](async-await.md)
+    - [Awaiting Python awaitables](async-await/awaiting_python_awaitables)
 - [Parallelism](parallelism.md)
 - [Debugging](debugging.md)
 - [Features reference](features.md)
 - [Memory management](memory.md)
 - [Performance](performance.md)
 - [Advanced topics](advanced.md)
 - [Building and distribution](building-and-distribution.md)
-  - [Supporting multiple Python versions](building-and-distribution/multiple-python-versions.md)
+    - [Supporting multiple Python versions](building-and-distribution/multiple-python-versions.md)
 - [Useful crates](ecosystem.md)
-  - [Logging](ecosystem/logging.md)
-  - [Using `async` and `await`](ecosystem/async-await.md)
+    - [Logging](ecosystem/logging.md)
+    - [Using `async` and `await`](ecosystem/async-await.md)
 - [FAQ and troubleshooting](faq.md)
 
 ---

guide/src/async-await.md

@@ -24,8 +24,6 @@ async fn sleep(seconds: f64, result: Option<PyObject>) -> Option<PyObject> {
 # }
 ```
 
-*Python awaitables instantiated with this method can only be awaited in *asyncio* context. Other Python async runtime may be supported in the future.*
-
 ## `Send + 'static` constraint
 
 Resulting future of an `async fn` decorated by `#[pyfunction]` must be `Send + 'static` to be embedded in a Python object.
@@ -93,6 +91,13 @@ async fn cancellable(#[pyo3(cancel_handle)] mut cancel: CancelHandle) {
 # }
 ```
 
+## *asyncio* vs. *anyio*
+
+By default, Python awaitables instantiated with `async fn` can only be awaited in *asyncio* context. 
+
+PyO3 can also target [*anyio*](https://github.com/agronholm/anyio) with the dedicated `anyio` Cargo feature. With it enabled, `async fn` become awaitable both in *asyncio* or [*trio*](https://github.com/python-trio/trio) context.
+However, it requires to have the [*sniffio*](https://github.com/python-trio/sniffio) (or *anyio*) library installed.
+
 ## The `Coroutine` type
 
 To make a Rust future awaitable in Python, PyO3 defines a [`Coroutine`]({{#PYO3_DOCS_URL}}/pyo3/coroutine/struct.Coroutine.html) type, which implements the Python [coroutine protocol](https://docs.python.org/3/library/collections.abc.html#collections.abc.Coroutine).

guide/src/async-await/awaiting_python_awaitables.md

@@ -0,0 +1,62 @@
+# Awaiting Python awaitables
+
+Python awaitable can be awaited on Rust side
+using [`await_in_coroutine`]({{#PYO3_DOCS_URL}}/pyo3/coroutine/function.await_in_coroutine).
+
+```rust
+# # ![allow(dead_code)]
+# #[cfg(feature = "experimental-async")] {
+use pyo3::{prelude::*, coroutine::await_in_coroutine};
+
+#[pyfunction]
+async fn wrap_awaitable(awaitable: PyObject) -> PyResult<PyObject> {
+    Python::with_gil(|gil| await_in_coroutine(awaitable.bind(gil)))?.await
+}
+# }
+```
+
+Behind the scene, `await_in_coroutine` calls the `__await__` method of the Python awaitable (or `__iter__` for
+generator-based coroutine).
+
+## Restrictions
+
+As the name suggests, `await_in_coroutine` resulting future can only be awaited in coroutine context. Otherwise, it
+panics.
+
+```rust
+# # ![allow(dead_code)]
+# #[cfg(feature = "experimental-async")] {
+use pyo3::{prelude::*, coroutine::await_in_coroutine};
+
+#[pyfunction]
+fn block_on(awaitable: PyObject) -> PyResult<PyObject> {
+    let future = Python::with_gil(|gil| await_in_coroutine(awaitable.bind(gil)))?;
+    futures::executor::block_on(future) // ERROR: PyFuture must be awaited in coroutine context
+}
+# }
+```
+
+The future must also be the only one to be awaited at a time; it means that it's forbidden to await it in a `select!`.
+Otherwise, it panics.
+
+```rust
+# # ![allow(dead_code)]
+# #[cfg(feature = "experimental-async")] {
+use futures::FutureExt;
+use pyo3::{prelude::*, coroutine::await_in_coroutine};
+
+#[pyfunction]
+async fn select(awaitable: PyObject) -> PyResult<PyObject> {
+    let future = Python::with_gil(|gil| await_in_coroutine(awaitable.bind(gil)))?;
+    futures::select_biased! {
+        _ = std::future::pending::<()>().fuse() => unreachable!(),
+        res = future.fuse() => res, // ERROR: Python awaitable mixed with Rust future
+    }
+}
+# }
+```
+
+These restrictions exist because awaiting a `await_in_coroutine` future strongly binds it to the
+enclosing coroutine. The coroutine will then delegate its `send`/`throw`/`close` methods to the
+awaited future. If it was awaited in a `select!`, `Coroutine::send` would no able to know if
+the value passed would have to be delegated or not.

guide/src/building-and-distribution.md

@@ -62,6 +62,7 @@ There are many ways to go about this: it is possible to use `cargo` to build the
 PyO3 has some Cargo features to configure projects for building Python extension modules:
  - The `extension-module` feature, which must be enabled when building Python extension modules.
  - The `abi3` feature and its version-specific `abi3-pyXY` companions, which are used to opt-in to the limited Python API in order to support multiple Python versions in a single wheel.
+- The `anyio` feature, making PyO3 coroutines target [*anyio*](https://github.com/agronholm/anyio) instead of *asyncio*; either [*sniffio*](https://github.com/python-trio/sniffio) or *anyio* should be added as dependency of the Python extension.
 
 This section describes each of these packaging tools before describing how to build manually without them. It then proceeds with an explanation of the `extension-module` feature. Finally, there is a section describing PyO3's `abi3` features.
 

newsfragments/3610.added.md

@@ -0,0 +1 @@
+Add `#[pyo3(allow_threads)]` to release the GIL in (async) functions

newsfragments/3611.added.md

@@ -0,0 +1 @@
+Add `coroutine::await_in_coroutine` to await awaitables in coroutine context

newsfragments/3612.added.md

@@ -0,0 +1 @@
+Support anyio with a Cargo feature

pyo3-ffi/src/abstract_.rs

@@ -129,7 +129,11 @@ extern "C" {
     pub fn PyIter_Next(arg1: *mut PyObject) -> *mut PyObject;
     #[cfg(all(not(PyPy), Py_3_10))]
     #[cfg_attr(PyPy, link_name = "PyPyIter_Send")]
-    pub fn PyIter_Send(iter: *mut PyObject, arg: *mut PyObject, presult: *mut *mut PyObject);
+    pub fn PyIter_Send(
+        iter: *mut PyObject,
+        arg: *mut PyObject,
+        presult: *mut *mut PyObject,
+    ) -> c_int;
 
     #[cfg_attr(PyPy, link_name = "PyPyNumber_Check")]
     pub fn PyNumber_Check(o: *mut PyObject) -> c_int;

pyo3-macros-backend/src/attributes.rs

@@ -9,6 +9,7 @@ use syn::{
 };
 
 pub mod kw {
+    syn::custom_keyword!(allow_threads);
     syn::custom_keyword!(annotation);
     syn::custom_keyword!(attribute);
     syn::custom_keyword!(cancel_handle);

pyo3-macros-backend/src/method.rs

@@ -6,6 +6,7 @@ use syn::{ext::IdentExt, spanned::Spanned, Ident, Result};
 
 use crate::utils::Ctx;
 use crate::{
+    attributes,
     attributes::{FromPyWithAttribute, TextSignatureAttribute, TextSignatureAttributeValue},
     deprecations::{Deprecation, Deprecations},
     params::{impl_arg_params, Holders},
@@ -379,6 +380,7 @@ pub struct FnSpec<'a> {
     pub asyncness: Option<syn::Token![async]>,
     pub unsafety: Option<syn::Token![unsafe]>,
     pub deprecations: Deprecations<'a>,
+    pub allow_threads: Option<attributes::kw::allow_threads>,
 }
 
 pub fn parse_method_receiver(arg: &syn::FnArg) -> Result<SelfType> {
@@ -416,6 +418,7 @@ impl<'a> FnSpec<'a> {
             text_signature,
             name,
             signature,
+            allow_threads,
             ..
         } = options;
 
@@ -461,6 +464,7 @@ impl<'a> FnSpec<'a> {
             asyncness: sig.asyncness,
             unsafety: sig.unsafety,
             deprecations,
+            allow_threads,
         })
     }
 
@@ -603,6 +607,21 @@ impl<'a> FnSpec<'a> {
                 bail_spanned!(name.span() => "`cancel_handle` may only be specified once");
             }
         }
+        if let Some(FnArg::Py(py_arg)) = self
+            .signature
+            .arguments
+            .iter()
+            .find(|arg| matches!(arg, FnArg::Py(_)))
+        {
+            ensure_spanned!(
+                self.asyncness.is_none(),
+                py_arg.ty.span() => "GIL token cannot be passed to async function"
+            );
+            ensure_spanned!(
+                self.allow_threads.is_none(),
+                py_arg.ty.span() => "GIL cannot be held in function annotated with `allow_threads`"
+            );
+        }
 
         if self.asyncness.is_some() {
             ensure_spanned!(
@@ -612,8 +631,21 @@ impl<'a> FnSpec<'a> {
         }
 
         let rust_call = |args: Vec<TokenStream>, holders: &mut Holders| {
-            let mut self_arg = || self.tp.self_arg(cls, ExtractErrorMode::Raise, holders, ctx);
-
+            let allow_threads = self.allow_threads.is_some();
+            let mut self_arg = || {
+                let self_arg = self.tp.self_arg(cls, ExtractErrorMode::Raise, holders, ctx);
+                if self_arg.is_empty() {
+                    self_arg
+                } else {
+                    let self_checker = holders.push_gil_refs_checker(self_arg.span());
+                    quote! {
+                        #pyo3_path::impl_::deprecations::inspect_type(#self_arg &#self_checker),
+                    }
+                }
+            };
+            let arg_names = (0..args.len())
+                .map(|i| format_ident!("arg_{}", i))
+                .collect::<Vec<_>>();
             let call = if self.asyncness.is_some() {
                 let throw_callback = if cancel_handle.is_some() {
                     quote! { Some(__throw_callback) }
@@ -625,9 +657,6 @@ impl<'a> FnSpec<'a> {
                     Some(cls) => quote!(Some(<#cls as #pyo3_path::PyTypeInfo>::NAME)),
                     None => quote!(None),
                 };
-                let arg_names = (0..args.len())
-                    .map(|i| format_ident!("arg_{}", i))
-                    .collect::<Vec<_>>();
                 let future = match self.tp {
                     FnType::Fn(SelfType::Receiver { mutable: false, .. }) => {
                         quote! {{
@@ -645,18 +674,7 @@ impl<'a> FnSpec<'a> {
                     }
                     _ => {
                         let self_arg = self_arg();
-                        if self_arg.is_empty() {
-                            quote! { function(#(#args),*) }
-                        } else {
-                            let self_checker = holders.push_gil_refs_checker(self_arg.span());
-                            quote! {
-                                function(
-                                    // NB #self_arg includes a comma, so none inserted here
-                                    #pyo3_path::impl_::deprecations::inspect_type(#self_arg &#self_checker),
-                                    #(#args),*
-                                )
-                            }
-                        }
+                        quote!(function(#self_arg #(#args),*))
                     }
                 };
                 let mut call = quote! {{
@@ -665,6 +683,7 @@ impl<'a> FnSpec<'a> {
                         #pyo3_path::intern!(py, stringify!(#python_name)),
                         #qualname_prefix,
                         #throw_callback,
+                        #allow_threads,
                         async move { #pyo3_path::impl_::wrap::OkWrap::wrap(future.await) },
                     )
                 }};
@@ -676,20 +695,21 @@ impl<'a> FnSpec<'a> {
                     }};
                 }
                 call
-            } else {
+            } else if allow_threads {
                 let self_arg = self_arg();
-                if self_arg.is_empty() {
-                    quote! { function(#(#args),*) }
+                let (self_arg_name, self_arg_decl) = if self_arg.is_empty() {
+                    (quote!(), quote!())
                 } else {
-                    let self_checker = holders.push_gil_refs_checker(self_arg.span());
-                    quote! {
-                        function(
-                            // NB #self_arg includes a comma, so none inserted here
-                            #pyo3_path::impl_::deprecations::inspect_type(#self_arg &#self_checker),
-                            #(#args),*
-                        )
-                    }
-                }
+                    (quote!(__self,), quote! { let (__self,) = (#self_arg); })
+                };
+                quote! {{
+                    #self_arg_decl
+                    #(let #arg_names = #args;)*
+                    py.allow_threads(|| function(#self_arg_name #(#arg_names),*))
+                }}
+            } else {
+                let self_arg = self_arg();
+                quote!(function(#self_arg #(#args),*))
             };
             quotes::map_result_into_ptr(quotes::ok_wrap(call, ctx), ctx)
         };

pyo3-macros-backend/src/pyclass.rs

@@ -1174,6 +1174,7 @@ fn complex_enum_struct_variant_new<'a>(
         asyncness: None,
         unsafety: None,
         deprecations: Deprecations::new(ctx),
+        allow_threads: None,
     };
 
     crate::pymethod::impl_py_method_def_new(&variant_cls_type, &spec, ctx)
@@ -1199,6 +1200,7 @@ fn complex_enum_variant_field_getter<'a>(
         asyncness: None,
         unsafety: None,
         deprecations: Deprecations::new(ctx),
+        allow_threads: None,
     };
 
     let property_type = crate::pymethod::PropertyType::Function {