This seeks to re-resolve #106310, and improve #116086 in resolving #115937.

The original pull request for #106310, #106311, documented the behavior as the original PEP362 described it : any object found in __signature__ and not None would be returned by inspect.signature. But in fact, since 2014 apparently, a type guard allowing only instances of Signature to pass, or else raise an exception. The documentation was in fact inaccurate as a result.

Other changes to the inspect.signature function occurred through #100039 where it gained implementation-detail support for strings and callables to be set as __signature__, something which I'm trying to roll back. Regardless, the latest change to the documentation which sought to address the discrepancies between the doc and the implementation, #115937, demoted the Signature-in-__signature__ behavior from a feature to a vague implementation detail.

My proposition is to document things the following way:

• Signature objects in __signature__ are returned as-is by the inspect.signature function
• None is ignored and the behavior is as if __signature__ was not set
• Behavior for any other value is an implementation detail.

That way, uses of __signature__ as a cache or as a way to hide undocumented parameters remains guaranteed, while allowing the strings and callables support to be decided and to evolve separately.

I kept the "consult the source code for current semantics" line in an effort to limit changes to a minimum, but I would be in favor of removing it.

📚 Documentation preview 📚: https://cpython-previews--116124.org.readthedocs.build/