Re-document __signature__ as a feature #116124
Closed
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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__
are returned as-is by the inspect.signature function__signature__
was not setThat 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/