derive: let a function declare its own __text_signature__

#[pyfunction]/#[pymethod] derive __text_signature__ from the Rust parameter list, and a function that takes FuncArgs to check its own arity has no parameters to report, so func_sig emits "(*args, **kwargs)". Every builtin this branch rewrote that way - len, abs, hash, chr, callable, bin, ord, divmod, isinstance, issubclass and the rest of the 27 - stopped reporting the signature that #8512 had just made accurate: inspect.signature(len) (*args, **kwargs) # was (obj, /) Add `text_signature = "..."`, which overrides the derived parameter list, and give the affected builtins CPython's own, verified against CPython 3.14.7. round declares (number, ndigits=None) and so has a signature now, where before its destructuring pattern left it with none; builtin_signature.py keeps sum as the signature-less case and asserts round's instead. The derived signature is still used wherever no override is given, so genuinely variadic builtins such as breakpoint keep reporting (*args, **kwargs). Assisted-by: Claude:Claude Opus 5
JamesClarke7283 · May 29, 2026 · May 29, 2026 · May 29, 2026 · May 31, 2026 · Aug 14, 2026
commit f919d3b32ccbf02b4a74e1edc87859426a34d000
diff --git a/crates/derive-impl/src/pyclass.rs b/crates/derive-impl/src/pyclass.rs
@@ -1077,7 +1077,10 @@ where
         }
 
         let raw = item_meta.raw()?;
-        let sig_doc = text_signature(func.sig(), &py_name);
+        let sig_doc = match item_meta.explicit_text_signature()? {
+            Some(params) => Some(format!("{py_name}{params}")),
+            None => text_signature(func.sig(), &py_name),
+        };
         let has_receiver = func
             .sig()
             .inputs
@@ -1600,7 +1603,7 @@ impl ToTokens for MemberNursery {
 struct MethodItemMeta(ItemMetaInner);
 
 impl ItemMeta for MethodItemMeta {
-    const ALLOWED_NAMES: &'static [&'static str] = &["name", "raw"];
+    const ALLOWED_NAMES: &'static [&'static str] = &["name", "raw", "text_signature"];
 
     fn from_inner(inner: ItemMetaInner) -> Self {
         Self(inner)

diff --git a/crates/derive-impl/src/pymodule.rs b/crates/derive-impl/src/pymodule.rs
@@ -664,7 +664,10 @@ 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);
+        let sig_doc = match item_meta.explicit_text_signature()? {
+            Some(params) => Some(format!("{py_name}{params}")),
+            None => text_signature(func.sig(), &py_name),
+        };
 
         let module = args.module_name();
         // TODO: doc must exist at least one of code or CPython

diff --git a/crates/derive-impl/src/util.rs b/crates/derive-impl/src/util.rs
@@ -296,6 +296,13 @@ pub(crate) trait ItemMeta: Sized {
         self.inner()._optional_str("name").ok().flatten()
     }
 
+    /// An explicitly declared `__text_signature__` parameter list, for a
+    /// function whose Rust arguments cannot describe its Python ones, e.g. one
+    /// that takes `FuncArgs` to check its own arity.
+    fn explicit_text_signature(&self) -> Result<Option<String>> {
+        self.inner()._optional_str("text_signature")
+    }
+
     fn new_meta_error(&self, msg: &str) -> syn::Error {
         let inner = self.inner();
         err_span!(inner.meta_ident, "#[{}] {}", inner.meta_name(), msg)
@@ -304,7 +311,7 @@ pub(crate) trait ItemMeta: Sized {
 pub(crate) struct SimpleItemMeta(pub ItemMetaInner);
 
 impl ItemMeta for SimpleItemMeta {
-    const ALLOWED_NAMES: &'static [&'static str] = &["name"];
+    const ALLOWED_NAMES: &'static [&'static str] = &["name", "text_signature"];
 
     fn from_inner(inner: ItemMetaInner) -> Self {
         Self(inner)

diff --git a/crates/vm/src/stdlib/builtins.rs b/crates/vm/src/stdlib/builtins.rs
@@ -42,7 +42,7 @@ mod builtins {
     const CODEGEN_NOT_SUPPORTED: &str =
         "can't compile() to bytecode when the `codegen` feature of rustpython is disabled";
 
-    #[pyfunction]
+    #[pyfunction(text_signature = "(x, /)")]
     fn abs(func_args: FuncArgs, vm: &VirtualMachine) -> PyResult {
         check_meth_o(vm, "abs", &func_args)?;
         let (x,): (PyObjectRef,) = func_args.bind(vm)?;
@@ -73,14 +73,14 @@ mod builtins {
         obj.ascii(vm)
     }
 
-    #[pyfunction(name = "ascii")]
+    #[pyfunction(name = "ascii", text_signature = "(obj, /)")]
     fn py_ascii(func_args: FuncArgs, vm: &VirtualMachine) -> PyResult<PyStrRef> {
         check_meth_o(vm, "ascii", &func_args)?;
         let (obj,): (PyObjectRef,) = func_args.bind(vm)?;
         ascii(obj, vm)
     }
 
-    #[pyfunction]
+    #[pyfunction(text_signature = "(number, /)")]
     fn bin(func_args: FuncArgs, vm: &VirtualMachine) -> PyResult<String> {
         check_meth_o(vm, "bin", &func_args)?;
         let (x,): (ArgIndex,) = func_args.bind(vm)?;
@@ -93,14 +93,14 @@ mod builtins {
         })
     }
 
-    #[pyfunction]
+    #[pyfunction(text_signature = "(obj, /)")]
     fn callable(func_args: FuncArgs, vm: &VirtualMachine) -> PyResult<bool> {
         check_meth_o(vm, "callable", &func_args)?;
         let (obj,): (PyObjectRef,) = func_args.bind(vm)?;
         Ok(obj.is_callable())
     }
 
-    #[pyfunction]
+    #[pyfunction(text_signature = "(i, /)")]
     fn chr(func_args: FuncArgs, vm: &VirtualMachine) -> PyResult<CodePoint> {
         check_meth_o(vm, "chr", &func_args)?;
         let (i,): (ArgIndex,) = func_args.bind(vm)?;
@@ -431,7 +431,7 @@ mod builtins {
         vm.dir(obj.into_option())
     }
 
-    #[pyfunction]
+    #[pyfunction(text_signature = "(x, y, /)")]
     fn divmod(func_args: FuncArgs, vm: &VirtualMachine) -> PyResult {
         check_no_kwargs(vm, "divmod", &func_args)?;
         check_positional(vm, "divmod", func_args.args.len(), 2, 2)?;
@@ -771,7 +771,7 @@ mod builtins {
         }
     }
 
-    #[pyfunction]
+    #[pyfunction(text_signature = "()")]
     fn globals(func_args: FuncArgs, vm: &VirtualMachine) -> PyResult<PyDictRef> {
         check_noargs(vm, "globals", &func_args)?;
         Ok(vm.current_globals())
@@ -788,7 +788,7 @@ mod builtins {
         Ok(vm.get_attribute_opt(obj, attr)?.is_some())
     }
 
-    #[pyfunction]
+    #[pyfunction(text_signature = "(obj, /)")]
     fn hash(func_args: FuncArgs, vm: &VirtualMachine) -> PyResult<PyHash> {
         check_meth_o(vm, "hash", &func_args)?;
         let (obj,): (PyObjectRef,) = func_args.bind(vm)?;
@@ -806,7 +806,7 @@ mod builtins {
         }
     }
 
-    #[pyfunction]
+    #[pyfunction(text_signature = "(number, /)")]
     fn hex(func_args: FuncArgs, vm: &VirtualMachine) -> PyResult<String> {
         check_meth_o(vm, "hex", &func_args)?;
         let (number,): (ArgIndex,) = func_args.bind(vm)?;
@@ -815,7 +815,7 @@ mod builtins {
         Ok(format!("{n:#x}"))
     }
 
-    #[pyfunction]
+    #[pyfunction(text_signature = "(obj, /)")]
     fn id(func_args: FuncArgs, vm: &VirtualMachine) -> PyResult<usize> {
         check_meth_o(vm, "id", &func_args)?;
         let (obj,): (PyObjectRef,) = func_args.bind(vm)?;
@@ -889,15 +889,15 @@ mod builtins {
         false
     }
 
-    #[pyfunction]
+    #[pyfunction(text_signature = "(obj, class_or_tuple, /)")]
     fn isinstance(func_args: FuncArgs, vm: &VirtualMachine) -> PyResult<bool> {
         check_no_kwargs(vm, "isinstance", &func_args)?;
         check_positional(vm, "isinstance", func_args.args.len(), 2, 2)?;
         let (obj, typ): (PyObjectRef, PyObjectRef) = func_args.bind(vm)?;
         obj.is_instance(&typ, vm)
     }
 
-    #[pyfunction]
+    #[pyfunction(text_signature = "(cls, class_or_tuple, /)")]
     fn issubclass(func_args: FuncArgs, vm: &VirtualMachine) -> PyResult<bool> {
         check_no_kwargs(vm, "issubclass", &func_args)?;
         check_positional(vm, "issubclass", func_args.args.len(), 2, 2)?;
@@ -955,14 +955,14 @@ mod builtins {
         }
     }
 
-    #[pyfunction]
+    #[pyfunction(text_signature = "(obj, /)")]
     fn len(func_args: FuncArgs, vm: &VirtualMachine) -> PyResult<usize> {
         check_meth_o(vm, "len", &func_args)?;
         let (obj,): (PyObjectRef,) = func_args.bind(vm)?;
         obj.length(vm)
     }
 
-    #[pyfunction]
+    #[pyfunction(text_signature = "()")]
     fn locals(func_args: FuncArgs, vm: &VirtualMachine) -> PyResult<ArgMapping> {
         check_noargs(vm, "locals", &func_args)?;
         vm.current_locals()
@@ -1062,7 +1062,7 @@ mod builtins {
             })
     }
 
-    #[pyfunction]
+    #[pyfunction(text_signature = "(number, /)")]
     fn oct(func_args: FuncArgs, vm: &VirtualMachine) -> PyResult {
         check_meth_o(vm, "oct", &func_args)?;
         let (number,): (ArgIndex,) = func_args.bind(vm)?;
@@ -1077,7 +1077,7 @@ mod builtins {
         Ok(vm.ctx.new_str(s).into())
     }
 
-    #[pyfunction]
+    #[pyfunction(text_signature = "(character, /)")]
     // builtin_ord
     fn ord(func_args: FuncArgs, vm: &VirtualMachine) -> PyResult<u32> {
         check_meth_o(vm, "ord", &func_args)?;
@@ -1217,7 +1217,7 @@ mod builtins {
         Ok(())
     }
 
-    #[pyfunction]
+    #[pyfunction(text_signature = "(obj, /)")]
     fn repr(func_args: FuncArgs, vm: &VirtualMachine) -> PyResult<PyStrRef> {
         check_meth_o(vm, "repr", &func_args)?;
         let (obj,): (PyObjectRef,) = func_args.bind(vm)?;
@@ -1252,7 +1252,7 @@ mod builtins {
         ndigits: OptionalOption<PyObjectRef>,
     }
 
-    #[pyfunction]
+    #[pyfunction(text_signature = "(number, ndigits=None)")]
     fn round(func_args: FuncArgs, vm: &VirtualMachine) -> PyResult {
         if func_args.args.is_empty() && !func_args.kwargs.contains_key("number") {
             return Err(vm.new_type_error("round() missing required argument 'number' (pos 1)"));

diff --git a/extra_tests/snippets/builtin_signature.py b/extra_tests/snippets/builtin_signature.py
@@ -47,6 +47,12 @@
 assert str(inspect.signature(issubclass)) == "(cls, class_or_tuple, /)"
 assert str(inspect.signature(aiter)) == "(async_iterable, /)"
 
+# A function that takes FuncArgs to check its own arity has no Rust parameter
+# list to report, so it declares the signature itself.
+assert str(inspect.signature(round)) == "(number, ndigits=None)"
+assert str(inspect.signature(globals)) == "()"
+assert str(inspect.signature(ascii)) == "(obj, /)"
+
 if sys.implementation.name == "rustpython":
     # Functions whose Rust arguments are destructuring patterns rather than
     # plain names get no signature at all, instead of emitting text that is not
@@ -56,7 +62,7 @@
     # We cannot derive them until FromArgs reports the parameters of its own
     # structs, so until then we report no signature, which is at least how
     # CPython behaves for the builtins it has no signature for.
-    for f in (round, sum):
+    for f in (sum,):
         assert f.__text_signature__ is None, f.__name__
         try:
             inspect.signature(f)