__signature__ in the inspect module

[Gouvernathor]

Documentation

The __signature__ attribute is treated by inspect.signature (and inspect.Signature.from_callable) as an override which is returned instead of computing the signature through the ordinary process. __text_signature__ serves a similar purpose but containing a string version of the signature.
That's for the implementation.

None of the two are mentioned in the signature or Signature sections of the inspect module's doc page. However, the inspect.unwrap function's doc entry mentions, in an example, that inspect.signature does recognize the __signature__ attribute, without saying what it does with it.
This is the only mention of __signature__ or __text_signature__ in the doc, excluding changelogs, whatsnew, and the Argument clinic section which is overtly implementation-dependent.
However, it is also mentioned in the PEP 362 which introduced Signature, albeit in the Implementation section.

It should be clarified whether what __signature__ does is documented or not. It's a very useful feature to be able to cache or lie about a function's signature, and I think it should be supported.
If not, then inspect.unwrap should stop mentioning it and use another example.

Linked PRs

• gh-106310 - document the __signature__ attribute #106311
• [3.12] gh-106310 - document the __signature__ attribute (GH-106311) #111145
• [3.11] gh-106310 - document the __signature__ attribute (GH-106311) #111146