gh-81677: WIP: provide __signature__ attribute for builtins (Signature object built from the PEP 7-like "signature line")

[skirpichev]

• add support for parsing annotations from __text_signature__ properties. Mostly naive and minimal implementation: there could be some validation of parsed annotations (e.g. to exclude something like print(1)).
  But I doubt, that this is required. In fact, probably the whole method could be refactored to do first parsing the program string, then do ast transformation (RewriteSymbolics) for defaults, then do ast.unparse(), eval its output and use _signature_from_function() helper to get the final result.
• relax requirements for specification of text signatures in the PyDoc_STRVAR. Before - only ([<python-style parameter_list>]) was accepted. Now it permits everything till the end marker (\n--\n\n), that allows us to
  specify return annotations. (A first step to something like Support return annotation in signature for Argument Clinic #76120.)

This doesn't touch public interfaces: the __text_signature__ property is undocumented (but see #93865). So, no news entry.

• Issue: Support annotations in signature strings. #81677

[skirpichev]

@sobolevn, maybe you could review this (at least the inspect part)?

[sobolevn]

Thanks for working on this!

Couple of thoughts:

1. Does anyone actually use __text_annotations__? (I am asking because I don't know). I assume people use it, is it a breaking change for them?
2. How well does your solution support more complex annotations that require (a) typing imports, what we might need from there? (b) forward references and https://peps.python.org/pep-0649/

Other than that - I don't really have an opinion on this feature. Because I don't any real use-cases for it.

[skirpichev]

Does anyone actually use __text_annotations__?

I can't find any example outside of the CPython, and it's not documented (as the __signature__ property, which is used, e.g. in the SymPy). There is an issue, which is more or less a feature request: #93865

Clearly, it might be useful for extensions.

I assume people use it, is it a breaking change for them?

No, I don't think so. Previously, the return annotation was just ignored and if there were parameter annotations - an exception was raised.

How well does your solution support more complex annotations that require (a) typing imports, what we might need from there? (b) forward references

This solution does assume application in the stdlib modules and simple extensions (e.g. I've tested this on the gmpy2), so
nothing fancy yet. If this does make sense at all (see the subject on a different approach) - then I'll think about extending
it to a more complex annotations.

Because I don't any real use-cases for it.

Any example of using __text_signature__ property in the stdlib. In most cases, however, this will require
support from the AC (not sure if this should be a part of this PR). But some functions/methods add now signatures
without using the AC, e.g. the math.gcd.

[skirpichev]

@1st1, you are listed as an expert for the inspect module. Maybe you could review this little pr?

[skirpichev]

@vstinner, maybe you could review this? I would guess something like this should be a first step on solving #76120 (your issue). It seems some external projects already depend on this pr, so I would appreciate any feedback.

[skirpichev]

https://discuss.python.org/t/43914

[skirpichev]

PEP waiting for a sponsor: skirpichev/peps#2