GeezerVison

The mechanism looks right: has_internal_doc_signature follows find_signature + skip_signature in Objects/typeobject.c (the doc must start with name(, the scan looks for )\n--\n\n, and it gives up at a blank line). These four objects get their text signatures from hand-written docstring headers in CPython as well. A few things should change before merging, though.

Observed before → after

Before: a build of 45a012cda (main at the time). After: the values asserted in this PR's snippet, which match CPython 3.15.

In practice this changes raw metadata only. The only inspect-visible difference is the receiver name of the unbound __prepare__.

1. Drop "legacy" from the naming; one comment is factually wrong

The feature is "an explicit internal-doc signature in the docstring is used as-is", and has_internal_doc_signature already says that. "Legacy" in the title, branch, code comment, test name and snippet comment does not describe it:

• The comment in signature.rs, "Explicit Clinic headers cover legacy signatures that are not Python parameter lists", is wrong for __prepare__: ($cls, name, bases, /, **kwds) is an ordinary parameter list. Only the deque headers use optional groups. Something like: "A doc that starts with a complete name(...)\n--\n\n header supplies its own text signature."
• explicit_internal_doc_preserves_legacy_signatures → e.g. explicit_internal_doc_signature_is_kept.
• Snippet comment "Legacy Clinic headers …" and the legacy signature should remain unrepresentable message → describe them as explicit internal-doc signatures.
• PR title → e.g. "Honor explicit internal-doc signatures for deque, timezone and type.prepare".

#9757 went through the same rename (legacy_signature → signature_from_flags) for the same reason.

2. The header is used implicitly and never checked against the Rust binding

Any /// doc that happens to be header-shaped now silently replaces the generated signature, and nothing checks the hand-written header against the real arguments. The drift is already there: deque.index binds needle in Rust, while the header says value. The displayed text is correct today, but a later change to the Rust signature would go unnoticed.

#9757 takes the opposite approach: an explicit #[pyfunction(signature_from_flags)] opt-in, plus const assertions that reject a mismatched arity at compile time. CPython does not validate hand-written headers either, so this is not a parity bug. It is still inconsistent within RustPython. Please consider at least a const check that the header's positional arity agrees with the binding metadata, or an explicit opt-in so the override cannot happen by accident.

3. Docs are now split between two sources

Because a /// doc overrides the crates/doc DB entry, the bodies of these four docstrings are now hard-coded in Rust, and regenerating crates/doc/src/data.inc.rs will no longer update them. crates/doc/generate.py stores only __doc__, which has the header stripped. A broader fix would be to have the generator also capture __text_signature__. That can be a follow-up, but it should be acknowledged here.

4. Conflict with #9757

Both PRs append to crates/vm/src/function/signature.rs and to the end of extra_tests/snippets/builtin_signature.py, so whichever lands second needs a rebase.

— commented by Claude