add experimental-async feature

Cargo.toml

@@ -65,6 +65,9 @@ pyo3-build-config = { path = "pyo3-build-config", version = "=0.21.0-dev", featu
 [features]
 default = ["macros"]
 
+# Enables support for `async fn` for `#[pyfunction]` and `#[pymethods]`.
+experimental-async = ["macros", "pyo3-macros/experimental-async"]
+
 # Enables pyo3::inspect module and additional type information on FromPyObject
 # and IntoPy traits
 experimental-inspect = []
@@ -115,8 +118,9 @@ full = [
  "chrono",
  "chrono-tz",
  "either",
- "experimental-inspect",
+ "experimental-async",
  "experimental-declarative-modules",
+ "experimental-inspect",
  "eyre",
  "hashbrown",
  "indexmap",

guide/src/async-await.md

@@ -6,6 +6,7 @@
 
 ```rust
 # #![allow(dead_code)]
+# #[cfg(feature = "experimental-async")] {
 use std::{thread, time::Duration};
 use futures::channel::oneshot;
 use pyo3::prelude::*;
@@ -20,6 +21,7 @@ async fn sleep(seconds: f64, result: Option<PyObject>) -> Option<PyObject> {
  rx.await.unwrap();
  result
 }
+# }
 ```
 
 *Python awaitables instantiated with this method can only be awaited in *asyncio* context. Other Python async runtime may be supported in the future.*
@@ -72,6 +74,7 @@ Cancellation on the Python side can be caught using [`CancelHandle`]({{#PYO3_DOC
 
 ```rust
 # #![allow(dead_code)]
+# #[cfg(feature = "experimental-async")] {
 use futures::FutureExt;
 use pyo3::prelude::*;
 use pyo3::coroutine::CancelHandle;
@@ -83,11 +86,12 @@ async fn cancellable(#[pyo3(cancel_handle)] mut cancel: CancelHandle) {
  _ = cancel.cancelled().fuse() => println!("cancelled"),
  }
 }
+# }
 ```
 
 ## 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). 
+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).
 
 Each `coroutine.send` call is translated to a `Future::poll` call. If a [`CancelHandle`]({{#PYO3_DOCS_URL}}/pyo3/coroutine/struct.CancelHandle.html) parameter is declared, the exception passed to `coroutine.throw` call is stored in it and can be retrieved with [`CancelHandle::cancelled`]({{#PYO3_DOCS_URL}}/pyo3/coroutine/struct.CancelHandle.html#method.cancelled); otherwise, it cancels the Rust future, and the exception is reraised;
 

guide/src/features.md

@@ -51,6 +51,12 @@ If you do not enable this feature, you should call `pyo3::prepare_freethreaded_p
 
 ## Advanced Features
 
+### `experimental-async`
+
+This feature adds support for `async fn` in `#[pyfunction]` and `#[pymethods]`.
+
+The feature has some unfinished refinements and performance improvements. To help finish this off, see [issue #1632](https://github.com/PyO3/pyo3/issues/1632) and its associated draft PRs.
+
 ### `experimental-inspect`
 
 This feature adds the `pyo3::inspect` module, as well as `IntoPy::type_output` and `FromPyObject::type_input` APIs to produce Python type "annotations" for Rust types.

newsfragments/3931.added.md

@@ -0,0 +1 @@
+Add `experimental-async` feature.

pyo3-macros-backend/Cargo.toml

@@ -26,3 +26,6 @@ features = ["derive", "parsing", "printing", "clone-impls", "full", "extra-trait
 
 [lints]
 workspace = true
+
+[features]
+experimental-async = []

pyo3-macros-backend/src/method.rs

@@ -512,6 +512,13 @@ impl<'a> FnSpec<'a> {
  }
  }
 
+ if self.asyncness.is_some() {
+ ensure_spanned!(
+ cfg!(feature = "experimental-async"),
+ self.asyncness.span() => "async functions are only supported with the `experimental-async` feature"
+ );
+ }
+
  let rust_call = |args: Vec<TokenStream>, holders: &mut Vec<TokenStream>| {
  let self_arg = self.tp.self_arg(cls, ExtractErrorMode::Raise, holders, ctx);
 

pyo3-macros/Cargo.toml

@@ -15,6 +15,7 @@ proc-macro = true
 
 [features]
 multiple-pymethods = []
+experimental-async = ["pyo3-macros-backend/experimental-async"]
 experimental-declarative-modules = []
 
 [dependencies]

src/impl_.rs

@@ -6,7 +6,7 @@
 //! APIs may may change at any time without documentation in the CHANGELOG and without
 //! breaking semver guarantees.
 
-#[cfg(feature = "macros")]
+#[cfg(feature = "experimental-async")]
 pub mod coroutine;
 pub mod deprecations;
 pub mod extract_argument;

src/lib.rs

@@ -418,7 +418,7 @@ pub mod buffer;
 pub mod callback;
 pub mod conversion;
 mod conversions;
-#[cfg(feature = "macros")]
+#[cfg(feature = "experimental-async")]
 pub mod coroutine;
 #[macro_use]
 #[doc(hidden)]

tests/test_compile_error.rs

@@ -27,7 +27,8 @@ fn test_compile_errors() {
  t.compile_fail("tests/ui/wrong_aspyref_lifetimes.rs");
  t.compile_fail("tests/ui/invalid_pyfunctions.rs");
  t.compile_fail("tests/ui/invalid_pymethods.rs");
- #[cfg(Py_LIMITED_API)]
+ // output changes with async feature
+ #[cfg(all(Py_LIMITED_API, feature = "experimental-async"))]
  t.compile_fail("tests/ui/abi3_nativetype_inheritance.rs");
  t.compile_fail("tests/ui/invalid_intern_arg.rs");
  t.compile_fail("tests/ui/invalid_frozen_pyclass_borrow.rs");
@@ -48,4 +49,6 @@ fn test_compile_errors() {
  t.compile_fail("tests/ui/invalid_pymodule_trait.rs");
  #[cfg(feature = "experimental-declarative-modules")]
  t.compile_fail("tests/ui/invalid_pymodule_two_pymodule_init.rs");
+ #[cfg(feature = "experimental-async")]
+ t.compile_fail("tests/ui/invalid_cancel_handle.rs");
 }

tests/test_coroutine.rs

@@ -1,4 +1,4 @@
-#![cfg(feature = "macros")]
+#![cfg(feature = "experimental-async")]
 #![cfg(not(target_arch = "wasm32"))]
 use std::{task::Poll, thread, time::Duration};
 

tests/ui/invalid_argument_attributes.rs

@@ -15,29 +15,4 @@ fn from_py_with_value_not_a_string(#[pyo3(from_py_with = func)] param: String) {
 #[pyfunction]
 fn from_py_with_repeated(#[pyo3(from_py_with = "func", from_py_with = "func")] param: String) {}
 
-#[pyfunction]
-async fn from_py_with_value_and_cancel_handle(
- #[pyo3(from_py_with = "func", cancel_handle)] _param: String,
-) {
-}
-
-#[pyfunction]
-async fn cancel_handle_repeated(#[pyo3(cancel_handle, cancel_handle)] _param: String) {}
-
-#[pyfunction]
-async fn cancel_handle_repeated2(
- #[pyo3(cancel_handle)] _param: String,
- #[pyo3(cancel_handle)] _param2: String,
-) {
-}
-
-#[pyfunction]
-fn cancel_handle_synchronous(#[pyo3(cancel_handle)] _param: String) {}
-
-#[pyfunction]
-async fn cancel_handle_wrong_type(#[pyo3(cancel_handle)] _param: String) {}
-
-#[pyfunction]
-async fn missing_cancel_handle_attribute(_param: pyo3::coroutine::CancelHandle) {}
-
 fn main() {}

tests/ui/invalid_argument_attributes.stderr

@@ -27,82 +27,3 @@ error: `from_py_with` may only be specified once per argument
  |
 16 | fn from_py_with_repeated(#[pyo3(from_py_with = "func", from_py_with = "func")] param: String) {}
  | ^^^^^^^^^^^^
-
-error: `from_py_with` and `cancel_handle` cannot be specified together
- --> tests/ui/invalid_argument_attributes.rs:20:35
- |
-20 | #[pyo3(from_py_with = "func", cancel_handle)] _param: String,
- | ^^^^^^^^^^^^^
-
-error: `cancel_handle` may only be specified once per argument
- --> tests/ui/invalid_argument_attributes.rs:25:55
- |
-25 | async fn cancel_handle_repeated(#[pyo3(cancel_handle, cancel_handle)] _param: String) {}
- | ^^^^^^^^^^^^^
-
-error: `cancel_handle` may only be specified once
- --> tests/ui/invalid_argument_attributes.rs:30:28
- |
-30 | #[pyo3(cancel_handle)] _param2: String,
- | ^^^^^^^
-
-error: `cancel_handle` attribute can only be used with `async fn`
- --> tests/ui/invalid_argument_attributes.rs:35:53
- |
-35 | fn cancel_handle_synchronous(#[pyo3(cancel_handle)] _param: String) {}
- | ^^^^^^
-
-error[E0308]: mismatched types
- --> tests/ui/invalid_argument_attributes.rs:37:1
- |
-37 | #[pyfunction]
- | ^^^^^^^^^^^^^
- | |
- | expected `String`, found `CancelHandle`
- | arguments to this function are incorrect
- |
-note: function defined here
- --> tests/ui/invalid_argument_attributes.rs:38:10
- |
-38 | async fn cancel_handle_wrong_type(#[pyo3(cancel_handle)] _param: String) {}
- | ^^^^^^^^^^^^^^^^^^^^^^^^ --------------
- = note: this error originates in the attribute macro `pyfunction` (in Nightly builds, run with -Z macro-backtrace for more info)
-
-error[E0277]: the trait bound `CancelHandle: PyClass` is not satisfied
- --> tests/ui/invalid_argument_attributes.rs:41:50
- |
-41 | async fn missing_cancel_handle_attribute(_param: pyo3::coroutine::CancelHandle) {}
- | ^^^^ the trait `PyClass` is not implemented for `CancelHandle`
- |
- = help: the trait `PyClass` is implemented for `pyo3::coroutine::Coroutine`
- = note: required for `CancelHandle` to implement `FromPyObject<'_>`
- = note: required for `CancelHandle` to implement `PyFunctionArgument<'_, '_>`
-note: required by a bound in `extract_argument`
- --> src/impl_/extract_argument.rs
- |
- | pub fn extract_argument<'a, 'py, T>(
- | ---------------- required by a bound in this function
-...
- | T: PyFunctionArgument<'a, 'py>,
- | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `extract_argument`
-
-error[E0277]: the trait bound `CancelHandle: Clone` is not satisfied
- --> tests/ui/invalid_argument_attributes.rs:41:50
- |
-41 | async fn missing_cancel_handle_attribute(_param: pyo3::coroutine::CancelHandle) {}
- | ^^^^ the trait `Clone` is not implemented for `CancelHandle`
- |
- = help: the following other types implement trait `PyFunctionArgument<'a, 'py>`:
- &'a pyo3::Bound<'py, T>
- &'a pyo3::coroutine::Coroutine
- &'a mut pyo3::coroutine::Coroutine
- = note: required for `CancelHandle` to implement `FromPyObject<'_>`
- = note: required for `CancelHandle` to implement `PyFunctionArgument<'_, '_>`
-note: required by a bound in `extract_argument`
- --> src/impl_/extract_argument.rs
- |
- | pub fn extract_argument<'a, 'py, T>(
- | ---------------- required by a bound in this function
-...
- | T: PyFunctionArgument<'a, 'py>,
- | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `extract_argument`

tests/ui/invalid_cancel_handle.rs

@@ -0,0 +1,22 @@
+use pyo3::prelude::*;
+
+#[pyfunction]
+async fn cancel_handle_repeated(#[pyo3(cancel_handle, cancel_handle)] _param: String) {}
+
+#[pyfunction]
+async fn cancel_handle_repeated2(
+ #[pyo3(cancel_handle)] _param: String,
+ #[pyo3(cancel_handle)] _param2: String,
+) {
+}
+
+#[pyfunction]
+fn cancel_handle_synchronous(#[pyo3(cancel_handle)] _param: String) {}
+
+#[pyfunction]
+async fn cancel_handle_wrong_type(#[pyo3(cancel_handle)] _param: String) {}
+
+#[pyfunction]
+async fn missing_cancel_handle_attribute(_param: pyo3::coroutine::CancelHandle) {}
+
+fn main() {}

tests/ui/invalid_cancel_handle.stderr

@@ -0,0 +1,72 @@
+error: `cancel_handle` may only be specified once per argument
+ --> tests/ui/invalid_cancel_handle.rs:4:55
+ |
+4 | async fn cancel_handle_repeated(#[pyo3(cancel_handle, cancel_handle)] _param: String) {}
+ | ^^^^^^^^^^^^^
+
+error: `cancel_handle` may only be specified once
+ --> tests/ui/invalid_cancel_handle.rs:9:28
+ |
+9 | #[pyo3(cancel_handle)] _param2: String,
+ | ^^^^^^^
+
+error: `cancel_handle` attribute can only be used with `async fn`
+ --> tests/ui/invalid_cancel_handle.rs:14:53
+ |
+14 | fn cancel_handle_synchronous(#[pyo3(cancel_handle)] _param: String) {}
+ | ^^^^^^
+
+error[E0308]: mismatched types
+ --> tests/ui/invalid_cancel_handle.rs:16:1
+ |
+16 | #[pyfunction]
+ | ^^^^^^^^^^^^^
+ | |
+ | expected `String`, found `CancelHandle`
+ | arguments to this function are incorrect
+ |
+note: function defined here
+ --> tests/ui/invalid_cancel_handle.rs:17:10
+ |
+17 | async fn cancel_handle_wrong_type(#[pyo3(cancel_handle)] _param: String) {}
+ | ^^^^^^^^^^^^^^^^^^^^^^^^ --------------
+ = note: this error originates in the attribute macro `pyfunction` (in Nightly builds, run with -Z macro-backtrace for more info)
+
+error[E0277]: the trait bound `CancelHandle: PyClass` is not satisfied
+ --> tests/ui/invalid_cancel_handle.rs:20:50
+ |
+20 | async fn missing_cancel_handle_attribute(_param: pyo3::coroutine::CancelHandle) {}
+ | ^^^^ the trait `PyClass` is not implemented for `CancelHandle`
+ |
+ = help: the trait `PyClass` is implemented for `pyo3::coroutine::Coroutine`
+ = note: required for `CancelHandle` to implement `FromPyObject<'_>`
+ = note: required for `CancelHandle` to implement `PyFunctionArgument<'_, '_>`
+note: required by a bound in `extract_argument`
+ --> src/impl_/extract_argument.rs
+ |
+ | pub fn extract_argument<'a, 'py, T>(
+ | ---------------- required by a bound in this function
+...
+ | T: PyFunctionArgument<'a, 'py>,
+ | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `extract_argument`
+
+error[E0277]: the trait bound `CancelHandle: Clone` is not satisfied
+ --> tests/ui/invalid_cancel_handle.rs:20:50
+ |
+20 | async fn missing_cancel_handle_attribute(_param: pyo3::coroutine::CancelHandle) {}
+ | ^^^^ the trait `Clone` is not implemented for `CancelHandle`
+ |
+ = help: the following other types implement trait `PyFunctionArgument<'a, 'py>`:
+ &'a pyo3::Bound<'py, T>
+ &'a pyo3::coroutine::Coroutine
+ &'a mut pyo3::coroutine::Coroutine
+ = note: required for `CancelHandle` to implement `FromPyObject<'_>`
+ = note: required for `CancelHandle` to implement `PyFunctionArgument<'_, '_>`
+note: required by a bound in `extract_argument`
+ --> src/impl_/extract_argument.rs
+ |
+ | pub fn extract_argument<'a, 'py, T>(
+ | ---------------- required by a bound in this function
+...
+ | T: PyFunctionArgument<'a, 'py>,
+ | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `extract_argument`