builtins: generate accurate __text_signature__ - #8512

• Related Malformed builtin __text_signature__ makes inspect.signature(len/sorted/open) raise ValueError #8383
• This PR follows our AI policy

Problem

RustPython's #[pyfunction]s generate a __text_signature__ that isn't comparable to CPython's. Of the 45 builtin functions RustPython shares with CPython 3.14, none reported an identical inspect.signature() before this PR:

• 43 carried a phantom module parameter that doesn't exist.
• None marked their true positional-only parameters as such.
• 2 (round, sum) emitted a signature string that isn't valid Python, so inspect.signature() raised ValueError: builtin has invalid signature. The same applies to os.pathconf, binascii.b2a_base64 and binascii.b2a_uu in the wider stdlib.

Tools that rely on inspect.signature() (unittest.mock.autospec, pydoc, IDE completion) act on this bad metadata.

Scope

This PR fixes everything reachable by changing crates/derive-impl/src/util.rs's signature generator alone, without touching FromArgs or adding new types. The #[derive(FromArgs)] struct case is deliberately left out, so #8383 stays open after this merges.

What changed

• Drop the $module marker. CPython's C functions receive the module as __self__, so inspect strips a leading $module. RustPython's #[pyfunction]s take no module argument, so __self__ is always None and there was nothing to strip. The marker surfaced as a parameter that doesn't exist (len(module, /, obj) instead of len(obj)).
• Mark parameters positional-only. Plain arguments bind through FuncArgs::take_positional, which never consults the keyword map: len(obj=[1, 2]) already raised TypeError, but inspect reported obj as POSITIONAL_OR_KEYWORD. Generated signatures now carry the / marker, except for *args/**kwargs and empty parameter lists, which cannot have one.
• Give up cleanly on unnamed parameters. Some functions bind through a destructuring pattern (e.g. fn round(RoundArgs { number, ndigits }: RoundArgs, ..)). The generator used to stringify the Rust pattern verbatim, producing text that isn't valid Python. inspect.signature() still raises ValueError for these, but now with no signature found for builtin, matching how CPython reports a builtin it has no signature for, rather than builtin has invalid signature.
• Rename 9 parameters to match CPython (bin, ord, divmod, setattr, delattr, hasattr, isinstance, issubclass, aiter). All positional-only, so the name is documentation only and renaming doesn't change behavior.
• Supporting changes. test_module_level_callable_noargs in Lib/test/test_pydoc/test_pydoc.py now passes for real (the phantom module parameter was the cause), so its expectedFailure marker is dropped. The new snippet's "no signature" assertions are guarded to RustPython, since CPython has real Argument Clinic signatures for round/sum.

Before / after

Measured across the 45 builtin functions RustPython and CPython 3.14 share:

The 22 that still differ fall into two groups that need different work.

CPython documents a signature we could match (13). Twelve of these hold their arguments in a type the signature generator can't see into: a #[derive(FromArgs)] struct (__import__, compile, eval, exec, open, pow, print, sorted, and round/sum, which now report no signature at all) or an OptionalArg whose default lives in the function body (format, input). The thirteenth, breakpoint, differs only because CPython names its keyword catch-all **kws and the generator hardcodes **kwargs for every FuncArgs function.

CPython has no signature at all, and RustPython reports one (9). __build_class__, anext, dir, getattr, iter, max, min, next and vars. Teaching FromArgs to report its parameters would not close this gap, since the generated signature is not what's wrong: matching CPython here means deciding to suppress a signature we are able to produce. test_autospec_on_bound_builtin_function stays expectedFailure for exactly this reason, via time.ctime.

Not in this PR

Two follow-ups would close most of the first group above:

• FromArgs reporting its own parameters. Implementors would report the parameters they consume, mirroring how arity() already self-reports parameter count. The information is already there in each field's #[pyarg(...)] attribute; it just isn't reachable from the signature generator today.
• OptionalArg's hidden defaults, which the same mechanism would have to carry.

The second group needs a separate decision about whether RustPython should suppress signatures CPython doesn't publish, which seems worth settling before either follow-up.

Two unrelated problems turned up while investigating, both out of scope here:

• __doc__ carries the raw signature prefix. len.__doc__ is 'len(obj, /)\n--\n\nReturn the number of items in a container.'. get_doc_from_internal_doc (type.rs) strips this, but is only wired to PyType.__doc__, not to builtin_func.rs or descriptor.rs.
• Methods have almost no signatures. pyclass.rs only attaches a generated signature when the method already has a doc comment, so list.append, str.split and dict.get all report __text_signature__ of None. This PR touches the #[pymethod] path only enough to keep it compiling.

Test plan

• New extra_tests/snippets/builtin_signature.py, run under both CPython and RustPython.
• cargo run --release -- -m test test_inspect test_pydoc test_unittest
• cargo test -p rustpython-derive-impl
• prek run --all-files

Developed with assistance from Claude Code (claude-opus-5)

Summary by CodeRabbit

• Bug Fixes

  • Improved builtin function signatures for clearer, more accurate display.
  • Removed phantom module parameters from displayed signatures.
  • Added correct positional-only and variadic parameter formatting.
  • Omitted signatures when they cannot be generated reliably.
  • Preserved documentation accurately when signatures are unavailable or incomplete.

• Tests

  • Added coverage for builtin signature formatting, parameter names, and edge cases.