Stub generation & introspection: emit async keyword for async functions (#5731)

* Introspection: emit async keyword for async functions

* Add newsfragment & fix formatting

* fix

* Remove unnecessary feature gate

Author: stijndcl

newsfragments/5731.added.md

@@ -0,0 +1 @@
+Stub generation & introspection: emit `async` keyword for async functions.

noxfile.py

@@ -1120,7 +1120,7 @@ def test_introspection(session: nox.Session):
         "-m",
         "./pytests/Cargo.toml",
         "--features",
-        "experimental-inspect",
+        "experimental-async,experimental-inspect",
         *options,
     )
     # We look for the built library

pyo3-introspection/src/introspection.rs

@@ -151,8 +151,11 @@ fn convert_members<'a>(
                 arguments,
                 parent: _,
                 decorators,
+                is_async,
                 returns,
-            } => functions.push(convert_function(name, arguments, decorators, returns)),
+            } => functions.push(convert_function(
+                name, arguments, decorators, returns, *is_async,
+            )),
             Chunk::Attribute {
                 name,
                 id: _,
@@ -225,6 +228,7 @@ fn convert_function(
     arguments: &ChunkArguments,
     decorators: &[ChunkExpr],
     returns: &Option<ChunkTypeHint>,
+    is_async: bool,
 ) -> Function {
     Function {
         name: name.into(),
@@ -243,6 +247,7 @@ fn convert_function(
                 .map(convert_variable_length_argument),
         },
         returns: returns.as_ref().map(convert_type_hint),
+        is_async,
     }
 }
 
@@ -475,6 +480,8 @@ enum Chunk {
         decorators: Vec<ChunkExpr>,
         #[serde(default)]
         returns: Option<ChunkTypeHint>,
+        #[serde(default, rename = "async")]
+        is_async: bool,
     },
     Attribute {
         #[serde(default)]

pyo3-introspection/src/model.rs

@@ -26,6 +26,7 @@ pub struct Function {
     pub arguments: Arguments,
     /// return type
     pub returns: Option<TypeHint>,
+    pub is_async: bool,
 }
 
 #[derive(Debug, Eq, PartialEq, Clone, Hash)]

pyo3-introspection/src/stubs.rs

@@ -85,6 +85,7 @@ fn module_stubs(module: &Module, parents: &[&str]) -> String {
                     }),
                     attr: "Incomplete".into(),
                 })),
+                is_async: false,
             },
             &imports,
         ));
@@ -187,6 +188,10 @@ fn function_stubs(function: &Function, imports: &Imports) -> String {
         imports.serialize_expr(decorator, &mut buffer);
         buffer.push('\n');
     }
+    if function.is_async {
+        buffer.push_str("async ");
+    }
+
     buffer.push_str("def ");
     buffer.push_str(&function.name);
     buffer.push('(');
@@ -633,6 +638,7 @@ mod tests {
                 }),
             },
             returns: Some(TypeHint::Plain("list[str]".into())),
+            is_async: false,
         };
         assert_eq!(
             "def func(posonly, /, arg, *varargs, karg: str, **kwarg: str) -> list[str]: ...",
@@ -665,13 +671,35 @@ mod tests {
                 kwarg: None,
             },
             returns: None,
+            is_async: false,
         };
         assert_eq!(
             "def afunc(posonly=1, /, arg=True, *, karg: str = \"foo\"): ...",
             function_stubs(&function, &Imports::default())
         )
     }
 
+    #[test]
+    fn test_function_async() {
+        let function = Function {
+            name: "foo".into(),
+            decorators: Vec::new(),
+            arguments: Arguments {
+                positional_only_arguments: Vec::new(),
+                arguments: Vec::new(),
+                vararg: None,
+                keyword_only_arguments: Vec::new(),
+                kwarg: None,
+            },
+            returns: None,
+            is_async: true,
+        };
+        assert_eq!(
+            "async def foo(): ...",
+            function_stubs(&function, &Imports::default())
+        )
+    }
+
     #[test]
     fn test_import() {
         let big_type = Expr::Subscript {
@@ -776,6 +804,7 @@ mod tests {
                         kwarg: None,
                     },
                     returns: Some(TypeHint::Ast(big_type.clone())),
+                    is_async: false,
                 }],
                 attributes: Vec::new(),
                 incomplete: true,

pyo3-macros-backend/src/introspection.rs

@@ -92,11 +92,13 @@ pub fn function_introspection_code(
     first_argument: Option<&'static str>,
     returns: ReturnType,
     decorators: impl IntoIterator<Item = PythonTypeHint>,
+    is_async: bool,
     parent: Option<&Type>,
 ) -> TokenStream {
     let mut desc = HashMap::from([
         ("type", IntrospectionNode::String("function".into())),
         ("name", IntrospectionNode::String(name.into())),
+        ("async", IntrospectionNode::Bool(is_async)),
         (
             "arguments",
             arguments_introspection_data(signature, first_argument, parent),

pyo3-macros-backend/src/pyclass.rs

@@ -1610,6 +1610,7 @@ fn generate_protocol_slot(
                         Some("self"),
                         parse_quote!(-> #returns),
                         [],
+                        spec.asyncness.is_some(),
                         Some(cls),
                     )
                 })
@@ -1954,6 +1955,7 @@ fn descriptors_to_items(
                     Some("self"),
                     parse_quote!(-> #return_type),
                     vec![PythonTypeHint::builtin("property")],
+                    false,
                     Some(&parse_quote!(#cls)),
                 ));
             }
@@ -2006,6 +2008,7 @@ fn descriptors_to_items(
                         ),
                         "setter",
                     )],
+                    false,
                     Some(&parse_quote!(#cls)),
                 ));
             }

pyo3-macros-backend/src/pyfunction.rs

@@ -396,6 +396,7 @@ pub fn impl_wrap_pyfunction(
         None,
         func.sig.output.clone(),
         empty(),
+        func.sig.asyncness.is_some(),
         None,
     );
     #[cfg(not(feature = "experimental-inspect"))]

pyo3-macros-backend/src/pyimpl.rs

@@ -463,6 +463,7 @@ fn method_introspection_code(spec: &FnSpec<'_>, parent: &syn::Type, ctx: &Ctx) -
         first_argument,
         return_type,
         decorators,
+        spec.asyncness.is_some(),
         Some(parent),
     )
 }

pytests/Cargo.toml

@@ -8,6 +8,7 @@ publish = false
 rust-version = "1.83"
 
 [features]
+experimental-async = ["pyo3/experimental-async"]
 experimental-inspect = ["pyo3/experimental-inspect"]
 
 [dependencies]