From a59c45f6c05afbc83759cebd8634e1cd51b977e5 Mon Sep 17 00:00:00 2001
From: David Hewitt <mail@davidhewitt.dev>
Date: Mon, 4 Mar 2024 21:18:42 +0000
Subject: [PATCH] add `experimental-async` feature

---
 Cargo.toml                        | 6 +++++-
 guide/src/features.md             | 6 ++++++
 newsfragments/3931.added.md       | 1 +
 pyo3-macros-backend/Cargo.toml    | 3 +++
 pyo3-macros-backend/src/method.rs | 7 +++++++
 pyo3-macros/Cargo.toml            | 1 +
 src/impl_.rs                      | 2 +-
 src/lib.rs                        | 2 +-
 tests/test_coroutine.rs           | 2 +-
 9 files changed, 26 insertions(+), 4 deletions(-)
 create mode 100644 newsfragments/3931.added.md

diff --git a/Cargo.toml b/Cargo.toml
index e7364a7c9f5..fad4bfca98c 100644
--- a/Cargo.toml
+++ b/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 = []
@@ -116,8 +119,9 @@ full = [
     "chrono",
     "chrono-tz",
     "either",
-    "experimental-inspect",
+    "experimental-async",
     "experimental-declarative-modules",
+    "experimental-inspect",
     "eyre",
     "hashbrown",
     "indexmap",
diff --git a/guide/src/features.md b/guide/src/features.md
index 43124e0076e..118284959d6 100644
--- a/guide/src/features.md
+++ b/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.
diff --git a/newsfragments/3931.added.md b/newsfragments/3931.added.md
new file mode 100644
index 00000000000..b532adeeae5
--- /dev/null
+++ b/newsfragments/3931.added.md
@@ -0,0 +1 @@
+Add `experimental-async` feature.
diff --git a/pyo3-macros-backend/Cargo.toml b/pyo3-macros-backend/Cargo.toml
index 0e83cc29fd4..665c8c3510d 100644
--- a/pyo3-macros-backend/Cargo.toml
+++ b/pyo3-macros-backend/Cargo.toml
@@ -26,3 +26,6 @@ features = ["derive", "parsing", "printing", "clone-impls", "full", "extra-trait
 
 [lints]
 workspace = true
+
+[features]
+experimental-async = []
diff --git a/pyo3-macros-backend/src/method.rs b/pyo3-macros-backend/src/method.rs
index 1d2d22b236b..9a8cb828b22 100644
--- a/pyo3-macros-backend/src/method.rs
+++ b/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);
 
diff --git a/pyo3-macros/Cargo.toml b/pyo3-macros/Cargo.toml
index a0368a5f364..97d2de07cba 100644
--- a/pyo3-macros/Cargo.toml
+++ b/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]
diff --git a/src/impl_.rs b/src/impl_.rs
index 77f9ff4ea1f..ea71b257c0e 100644
--- a/src/impl_.rs
+++ b/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;
diff --git a/src/lib.rs b/src/lib.rs
index 26d2ec55da1..c2c7d96a40a 100644
--- a/src/lib.rs
+++ b/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)]
diff --git a/tests/test_coroutine.rs b/tests/test_coroutine.rs
index db79c72a233..17539fa113e 100644
--- a/tests/test_coroutine.rs
+++ b/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};