youknowone · Sep 24, 2026 · Sep 24, 2026 · Sep 24, 2026 · Sep 24, 2026 · coderabbitai
diff --git a/.cspell.dict/rust-more.txt b/.cspell.dict/rust-more.txt
@@ -60,6 +60,7 @@ powf
 powi
 prepended
 punct
+qself
 replacen
 retag
 rmatch

diff --git a/Lib/test/test_inspect/test_inspect.py b/Lib/test/test_inspect/test_inspect.py
@@ -1363,7 +1363,6 @@ def test(): pass
         spec = inspect.getfullargspec(test)
         self.assertEqual(test.__annotations__, spec.annotations)
 
-    @unittest.expectedFailure  # TODO: RUSTPYTHON; os.stat signature is generated as (path, dir_fd, follow_symlinks, /)
     @unittest.skipIf(MISSING_C_DOCSTRINGS,
                      "Signature information for builtins requires docstrings")
     def test_getfullargspec_builtin_methods(self):

diff --git a/Lib/test/test_pydoc/test_pydoc.py b/Lib/test/test_pydoc/test_pydoc.py
@@ -1573,7 +1573,6 @@ def test_bound_builtin_method(self):
             "dump(obj, /) method of _pickle.Pickler instance")
 
     # this should *never* include self!
-    @unittest.expectedFailure  # TODO: RUSTPYTHON; os.stat signature is generated as (path, dir_fd, follow_symlinks, /)
     @requires_docstrings
     def test_module_level_callable(self):
         self.assertEqual(self._get_summary_line(os.stat),

diff --git a/crates/derive-impl/Cargo.toml b/crates/derive-impl/Cargo.toml
@@ -14,7 +14,7 @@ rustpython-compiler-core = { workspace = true }
 rustpython-doc = { workspace = true }
 
 itertools = { workspace = true }
-syn = { workspace = true, features = ["full", "extra-traits"] }
+syn = { workspace = true, features = ["full", "extra-traits", "visit", "visit-mut"] }
 
 proc-macro2 = { workspace = true }
 quote = { workspace = true }

diff --git a/crates/derive-impl/src/from_args.rs b/crates/derive-impl/src/from_args.rs
@@ -2,7 +2,7 @@ use proc_macro2::TokenStream;
 use quote::{ToTokens, quote};
 use syn::ext::IdentExt;
 use syn::meta::ParseNestedMeta;
-use syn::{Attribute, Data, DeriveInput, Expr, Field, Ident, Result, Token, parse_quote};
+use syn::{Attribute, Data, DeriveInput, Expr, Field, Ident, Lit, Result, Token, parse_quote};
 
 /// The kind of the python parameter, this corresponds to the value of Parameter.kind
 /// (https://docs.python.org/3/library/inspect.html#inspect.Parameter.kind)
@@ -37,6 +37,7 @@ struct ArgAttribute {
     name: Option<String>,
     kind: ParameterKind,
     default: Option<DefaultValue>,
+    py_default: Option<String>,
     error_msg: Option<String>,
 }
 
@@ -64,6 +65,7 @@ impl ArgAttribute {
                         name: None,
                         kind,
                         default: None,
+                        py_default: None,
                         error_msg: None,
                     });
                     return Ok(());
@@ -91,6 +93,13 @@ impl ArgAttribute {
             if self.default.is_none() {
                 self.default = Some(None);
             }
+        // Text-only signature default. See the `FromArgs` derive docs.
+        } else if meta.path.is_ident("py_default") {
+            if self.py_default.is_some() {
+                return Err(meta.error("py_default already set"));
+            }
+            let val = meta.value()?.parse::<syn::LitStr>()?;
+            self.py_default = Some(val.value());
         } else if meta.path.is_ident("name") {
             if self.name.is_some() {
                 return Err(meta.error("already have a name"));
@@ -212,6 +221,96 @@ fn generate_field((i, field): (usize, &Field)) -> Result<TokenStream> {
     Ok(file_output)
 }
 
+fn is_phantom(field: &Field) -> bool {
+    field
+        .ident
+        .as_ref()
+        .is_some_and(|ident| ident.unraw().to_string().starts_with("_phantom"))
+}
+
+fn python_str_repr(s: &str) -> String {
+    let mut out = String::from("'");
+    for c in s.chars() {
+        match c {
+            '\\' => out.push_str("\\\\"),
+            '\'' => out.push_str("\\'"),
+            '\n' => out.push_str("\\n"),
+            '\r' => out.push_str("\\r"),
+            '\t' => out.push_str("\\t"),
+            _ => out.push(c),
+        }
+    }
+    out.push('\'');
+    out
+}
+
+fn python_default_repr(default: Option<&DefaultValue>, py_default: Option<&str>) -> Option<String> {
+    if let Some(py_default) = py_default {
+        return Some(py_default.to_owned());
+    }
+    match default {
+        None => None,
+        Some(None) => Some("<unrepresentable>".to_owned()),
+        Some(Some(expr)) => match expr {
+            Expr::Lit(syn::ExprLit { lit, .. }) => match lit {
+                Lit::Bool(b) => Some(if b.value {
+                    "True".to_owned()
+                } else {
+                    "False".to_owned()
+                }),
+                Lit::Int(i) => Some(i.base10_digits().to_owned()),
+                Lit::Float(f) => Some(f.base10_digits().to_owned()),
+                Lit::Str(s) => Some(python_str_repr(&s.value())),
+                _ => Some("<unrepresentable>".to_owned()),
+            },
+            Expr::Path(path) if path.qself.is_none() && path.path.is_ident("None") => {
+                Some("None".to_owned())
+            }
+            _ => Some("<unrepresentable>".to_owned()),
+        },
-        Some(Some(expr)) => match expr {
-            Expr::Lit(syn::ExprLit { lit, .. }) => match lit {
-                Lit::Bool(b) => Some(if b.value {
-                    "True".to_owned()
-                } else {
-                    "False".to_owned()
-                }),
-                Lit::Int(i) => Some(i.base10_digits().to_owned()),
-                Lit::Float(f) => Some(f.base10_digits().to_owned()),
-                Lit::Str(s) => Some(python_str_repr(&s.value())),
-                _ => Some("<unrepresentable>".to_owned()),
-            },
-            Expr::Path(path) if path.qself.is_none() && path.path.is_ident("None") => {
-                Some("None".to_owned())
-            }
-            _ => Some("<unrepresentable>".to_owned()),
-        },
+        Some(Some(expr)) => match expr {
+            Expr::Lit(syn::ExprLit { lit, .. }) => match lit {
+                Lit::Bool(b) => Some(if b.value {
+                    "True".to_owned()
+                } else {
+                    "False".to_owned()
+                }),
+                Lit::Int(i) => Some(i.base10_digits().to_owned()),
+                Lit::Float(f) => Some(f.base10_digits().to_owned()),
+                Lit::Str(s) => Some(python_str_repr(&s.value())),
+                _ => Some("<unrepresentable>".to_owned()),
+            },
+            Expr::Path(path) if path.qself.is_none() && path.path.is_ident("None") => {
+                Some("None".to_owned())
+            }
+            Expr::Unary(syn::ExprUnary {
+                op: syn::UnOp::Neg(_),
+                expr: inner,
+                ..
+            }) => match &**inner {
+                Expr::Lit(syn::ExprLit { lit: Lit::Int(i), .. }) => {
+                    Some(format!("-{}", i.base10_digits()))
+                }
+                Expr::Lit(syn::ExprLit { lit: Lit::Float(f), .. }) => {
+                    Some(format!("-{}", f.base10_digits()))
+                }
+                _ => Some("<unrepresentable>".to_owned()),
+            },
+            Expr::Paren(syn::ExprParen { expr: inner, .. })
+            | Expr::Group(syn::ExprGroup { expr: inner, .. }) => {
+                python_default_repr(Some(&Some((**inner).clone())), None)
+            }
+            _ => Some("<unrepresentable>".to_owned()),
+        },
-        Some(Some(expr)) => match expr {
-            Expr::Lit(syn::ExprLit { lit, .. }) => match lit {
-                Lit::Bool(b) => Some(if b.value {
-                    "True".to_owned()
-                } else {
-                    "False".to_owned()
-                }),
-                Lit::Int(i) => Some(i.base10_digits().to_owned()),
-                Lit::Float(f) => Some(f.base10_digits().to_owned()),
-                Lit::Str(s) => Some(python_str_repr(&s.value())),
-                _ => Some("<unrepresentable>".to_owned()),
-            },
-            Expr::Path(path) if path.qself.is_none() && path.path.is_ident("None") => {
-                Some("None".to_owned())
-            }
-            _ => Some("<unrepresentable>".to_owned()),
-        },
+        Some(Some(expr)) => match expr {
+            Expr::Lit(syn::ExprLit { lit, .. }) => match lit {
+                Lit::Bool(b) => Some(if b.value {
+                    "True".to_owned()
+                } else {
+                    "False".to_owned()
+                }),
+                Lit::Int(i) => Some(i.base10_digits().to_owned()),
+                Lit::Float(f) => Some(f.base10_digits().to_owned()),
+                Lit::Str(s) => Some(python_str_repr(&s.value())),
+                _ => Some("<unrepresentable>".to_owned()),
+            },
+            Expr::Path(path) if path.qself.is_none() && path.path.is_ident("None") => {
+                Some("None".to_owned())
+            }
+            Expr::Unary(syn::ExprUnary {
+                op: syn::UnOp::Neg(_),
+                expr: inner,
+                ..
+            }) => match &**inner {
+                Expr::Lit(syn::ExprLit { lit: Lit::Int(i), .. }) => {
+                    Some(format!("-{}", i.base10_digits()))
+                }
+                Expr::Lit(syn::ExprLit { lit: Lit::Float(f), .. }) => {
+                    Some(format!("-{}", f.base10_digits()))
+                }
+                _ => Some("<unrepresentable>".to_owned()),
+            },
+            Expr::Paren(syn::ExprParen { expr: inner, .. })
+            | Expr::Group(syn::ExprGroup { expr: inner, .. }) => {
+                python_default_repr(Some(&Some((**inner).clone())), None)
+            }
+            _ => Some("<unrepresentable>".to_owned()),
+        },
+    }
+}
+
+fn param_token(field: &Field, attr: &ArgAttribute) -> Result<TokenStream> {
+    if let ParameterKind::Flatten = attr.kind {
+        let ty = &field.ty;
+        return Ok(quote! {
+            ::rustpython_vm::function::Param::flatten(
+                <#ty as ::rustpython_vm::function::FromArgs>::PARAMS
+            )
+        });
+    }
+
+    let name = field.ident.as_ref().map(|ident| ident.unraw().to_string());
+    let pyname = attr
+        .name
+        .clone()
+        .or(name)
+        .ok_or_else(|| err_span!(field, "field in tuple struct must have name attribute"))?;
+    let default = python_default_repr(attr.default.as_ref(), attr.py_default.as_deref());
+    let default_tok = match &default {
+        Some(default) => quote!(Some(#default)),
+        None => quote!(None),
+    };
+    let kind = match attr.kind {
+        ParameterKind::PositionalOnly => {
+            quote!(::rustpython_vm::function::ParamKind::PositionalOnly)
+        }
+        ParameterKind::PositionalOrKeyword => {
+            quote!(::rustpython_vm::function::ParamKind::PositionalOrKeyword)
+        }
+        ParameterKind::KeywordOnly => quote!(::rustpython_vm::function::ParamKind::KeywordOnly),
+        ParameterKind::Flatten => unreachable!(),
+    };
+    Ok(quote! {
+        ::rustpython_vm::function::Param {
+            name: #pyname,
+            kind: #kind,
+            default: #default_tok,
+        }
+    })
+}
+
 fn compute_arity_bounds(field_attrs: &[ArgAttribute]) -> (usize, usize) {
     let positional_fields = field_attrs.iter().filter(|attr| {
         matches!(
@@ -230,27 +329,40 @@ fn compute_arity_bounds(field_attrs: &[ArgAttribute]) -> (usize, usize) {
 }
 
 pub(crate) fn impl_from_args(input: DeriveInput) -> Result<TokenStream> {
-    let (fields, field_attrs) = match input.data {
-        Data::Struct(syn::DataStruct { fields, .. }) => (
-            fields
-                .iter()
-                .enumerate()
-                .map(generate_field)
-                .collect::<Result<TokenStream>>()?,
-            fields
-                .iter()
-                .filter_map(|field| field.try_into().ok())
-                .collect::<Vec<ArgAttribute>>(),
-        ),
-        _ => bail_span!(input, "FromArgs input must be a struct"),
+    let Data::Struct(syn::DataStruct {
+        fields: struct_fields,
+        ..
+    }) = input.data
+    else {
+        bail_span!(input, "FromArgs input must be a struct")
     };
 
+    let fields = struct_fields
+        .iter()
+        .enumerate()
+        .map(generate_field)
+        .collect::<Result<TokenStream>>()?;
+    let field_attrs = struct_fields
+        .iter()
+        .map(ArgAttribute::try_from)
+        .collect::<Result<Vec<_>>>()?;
     let (min_arity, max_arity) = compute_arity_bounds(&field_attrs);
 
+    let mut params = Vec::new();
+    for field in &struct_fields {
+        if is_phantom(field) {
+            continue;
+        }
+        params.push(param_token(field, &ArgAttribute::try_from(field)?)?);
+    }
+
     let name = input.ident;
     let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl();
     let output = quote! {
         impl #impl_generics ::rustpython_vm::function::FromArgs for #name #ty_generics #where_clause {
+            const PARAMS: Option<&'static [::rustpython_vm::function::Param]> =
+                Some(&[#(#params),*]);
+
             fn arity() -> ::std::ops::RangeInclusive<usize> {
                 #min_arity..=#max_arity
             }

diff --git a/crates/derive-impl/src/pyclass.rs b/crates/derive-impl/src/pyclass.rs
@@ -1,8 +1,8 @@
 use super::Diagnostic;
 use crate::util::{
     ALL_ALLOWED_NAMES, ClassItemMeta, ContentItem, ContentItemInner, ErrorVec, ExceptionItemMeta,
-    ItemMeta, ItemMetaInner, ItemNursery, SimpleItemMeta, format_doc, infer_native_call_flags,
-    pyclass_ident_and_attrs, pyexception_ident_and_attrs, text_signature,
+    ItemMeta, ItemMetaInner, ItemNursery, SimpleItemMeta, infer_native_call_flags,
+    internal_doc_tokens, pyclass_ident_and_attrs, pyexception_ident_and_attrs,
 };
 use core::str::FromStr;
 use proc_macro2::{Delimiter, Group, Span, TokenStream, TokenTree};
@@ -71,6 +71,9 @@ struct ImplContext {
     extend_slots_items: ItemNursery,
     class_extensions: Vec<TokenStream>,
     errors: Vec<syn::Error>,
+    /// Set when the impl has no generic parameters, so `Self` in argument
+    /// types can be replaced before it appears in a nested const.
+    self_ty_subst: Option<syn::Type>,
 }
 
 fn extract_items_into_context<'a, Item>(
@@ -104,6 +107,9 @@ pub(crate) fn impl_pyclass_impl(attr: PunctuatedNestedMeta, item: Item) -> Resul
     let mut context = ImplContext::default();
     let mut tokens = match item {
         Item::Impl(mut imp) => {
+            if imp.generics.params.is_empty() {
+                context.self_ty_subst = Some((*imp.self_ty).clone());
+            }
             extract_items_into_context(&mut context, imp.items.iter_mut());
 
             let (impl_ty, payload_guess) = match imp.self_ty.as_ref() {
@@ -1123,7 +1129,6 @@ where
             }
         };
         let drop_first_typed = usize::from(implicit_self.is_some());
-        let sig_doc = text_signature(func.sig(), &py_name, implicit_self);
         let call_flags = infer_native_call_flags(func.sig(), drop_first_typed);
 
         // Add #[allow(non_snake_case)] for setter methods like set___name__
@@ -1133,11 +1138,14 @@ where
             args.attrs.push(allow_attr);
         }
 
-        let doc = match (sig_doc, args.attrs.doc()) {
-            (Some(sig_doc), Some(doc)) => Some(format_doc(&sig_doc, &doc)),
-            (Some(sig_doc), None) => Some(format_doc(&sig_doc, "")),
-            (None, doc) => doc,
-        };
+        let doc = internal_doc_tokens(
+            func.sig(),
+            &py_name,
+            implicit_self,
+            args.attrs.doc(),
+            args.context.self_ty_subst.as_ref(),
+            None,
+        );
         args.context.method_items.add_item(MethodNurseryItem {
             py_name,
             cfgs: args.cfgs.to_vec(),
@@ -1373,7 +1381,7 @@ struct MethodNurseryItem {
     ident: Ident,
     raw: bool,
     coexist: bool,
-    doc: Option<String>,
+    doc: TokenStream,
     attr_name: AttrName,
     call_flags: TokenStream,
 }
@@ -1401,11 +1409,7 @@ impl ToTokens for MethodNursery {
             let py_name = &item.py_name;
             let ident = &item.ident;
             let cfgs = &item.cfgs;
-            let doc = if let Some(doc) = item.doc.as_ref() {
-                quote! { Some(#doc) }
-            } else {
-                quote! { None }
-            };
+            let doc = &item.doc;
             let binding_flags = match &item.attr_name {
                 AttrName::Method => {
                     quote! { rustpython_vm::function::PyMethodFlags::METHOD }

diff --git a/crates/derive-impl/src/pymodule.rs b/crates/derive-impl/src/pymodule.rs
@@ -2,8 +2,8 @@ use crate::error::Diagnostic;
 use crate::pystructseq::PyStructSequenceMeta;
 use crate::util::{
     ALL_ALLOWED_NAMES, AttrItemMeta, AttributeExt, ClassItemMeta, ContentItem, ContentItemInner,
-    ErrorVec, ItemMeta, ItemNursery, ModuleItemMeta, SimpleItemMeta, format_doc,
-    infer_native_call_flags, iter_use_idents, pyclass_ident_and_attrs, text_signature,
+    ErrorVec, ItemMeta, ItemNursery, ModuleItemMeta, SimpleItemMeta, infer_native_call_flags,
+    internal_doc_tokens, iter_use_idents, pyclass_ident_and_attrs,
 };
 use core::str::FromStr;
 use proc_macro2::{Delimiter, Group, TokenStream, TokenTree};
@@ -524,7 +524,7 @@ struct FunctionNurseryItem {
     py_names: Vec<String>,
     cfgs: Vec<Attribute>,
     ident: Ident,
-    doc: Option<String>,
+    doc: TokenStream,
     call_flags: TokenStream,
 }
 
@@ -556,10 +556,7 @@ impl ToTokens for ValidatedFunctionNursery {
             let cfgs = &item.cfgs;
             let cfgs = quote!(#(#cfgs)*);
             let py_names = &item.py_names;
-            let doc = match &item.doc {
-                Some(doc) => quote!(Some(#doc)),
-                None => quote!(None),
-            };
+            let doc = &item.doc;
             let flags = &item.call_flags;
 
             inner_tokens.extend(quote![
@@ -664,7 +661,6 @@ impl ModuleItem for FunctionItem {
         let item_meta = SimpleItemMeta::from_attr(ident.clone(), &item_attr)?;
 
         let py_name = item_meta.simple_name()?;
-        let sig_doc = text_signature(func.sig(), &py_name, None);
 
         let module = args.module_name();
         // TODO: doc must exist at least one of code or CPython
@@ -673,11 +669,7 @@ impl ModuleItem for FunctionItem {
                 .copied()
                 .map(str::to_owned)
         });
-        let doc = match (sig_doc, doc) {
-            (Some(sig_doc), Some(doc)) => Some(format_doc(&sig_doc, &doc)),
-            (Some(sig_doc), None) => Some(format_doc(&sig_doc, "")),
-            (None, doc) => doc,
-        };
+        let doc = internal_doc_tokens(func.sig(), &py_name, None, doc, None, Some("$module"));
 
         let py_names = {
             if self.py_attrs.is_empty() {
-Original file line number
+Diff line change
@@ Expand Up / @@ -60,6 +60,7 @@ powf @@
     powi
     prepended
     punct
+    qself
     replacen
     retag
     rmatch
@@ Expand Down @@