Use *.pyi stub files as source for the inspect.signature()

[skirpichev]

Feature or enhancement

Proposal:

In the referenced d.p.o thread it was proposed using stub files to get inspect.Signature's for extension modules.

Currently, there is no public interface to provide such data for introspection. There is only private, undocumented __text_signature__ attribute, which parsed by inspect.signature(). This interface also incomplete, e.g. it lacks support for return type annotations.

Lets use stub files as a fallback for extension modules: if callable has no __text_signature__ attribute - the inspect module should take look to stub files for the given module, import relevant stub object (with same import resolution ordering as for type checkers) and take it's signature. Later, the AC can be changed to generate stub files (or take them as input).

PS: Maybe same approach could work to support functions with multiple signatures, if the typing.get_overloads() will fallback to stub files as well.

If this does make sense, I'll provide a draft implementation.

Has this already been discussed elsewhere?

I have already discussed this feature proposal on Discourse

Links to previous discussion of this feature:

https://discuss.python.org/t/type-signatures-for-extension-modules-pep-draft/43914/22

[skirpichev]

CC @zooba

[sobolevn]

This feature requires a lot of little details to get right, since .pyi files right now are not ever executed by Python. And they are a bit special in that regard (for example from __future__ import annotations). Adding topic-typing to be sure that typing maintainers also see this.

[AlexWaygood]

Although pyi files are always guaranteed to parse as valid Python syntax, they often can't be imported at runtime since as @sobolevn says they support forward references in many contexts that runtime Python source files don't. The only way you'd be able to reliably retrieve information from them is by statically analysing their ASTs (which is what type checkers do).

It's possible to figure out which AST node in a stub file corresponds to a given runtime symbol. https://github.com/JelleZijlstra/stubdefaulter and https://github.com/python/mypy/blob/master/mypy/stubtest.py are both examples of projects that compare AST nodes in parsed stub files to corresponding runtime objects. It's a pretty nontrivial task to do it correctly, however, and I'm not sure if it's something the standard library's inspect.signature function should be doing.

[skirpichev]

This feature requires a lot of little details to get right

Probably, so.

And they are a bit special in that regard (for example from future import annotations).

they often can't be imported at runtime since as @sobolevn says they support forward references in many contexts that runtime Python source files don't.

Yeah, I would expect that importing in runtime will be less trivial, but it's possible, isn't? Or did I miss something and there are cases, where above __future__ import is not enough?

If that's true - this is a no-go for the idea (for me).

The only way you'd be able to reliably retrieve information from them is by statically analysing their ASTs

This is something I would like to avoid.

I was thinking that possible objection against is using stub files for different goals, that are overlapping but... I.e. currently signatures of stdlib/builtins don't include typing info, hardly this will be changed. So, stubs shipped with CPython will be more simple. But it's NOT OK if pip install types-foo will break inspect's behaviour for extension foo...

Working with AST could be much more simple, if a decent part of data will be ignored. E.g. current inspect's helper, parsing __text_signature__ - ignores annotations and "complex" default values: https://github.com/python/cpython/blob/c8d2630995fc234f8276e35643a4a43e62224510/Lib/inspect.py#L2193-L2337

Most extensions, probably, aren't too complicated in this regard. For example, for most functions/classes in the gmpy2 introspection capabilities could be added with #101872.

[sobolevn]

Yeah, I would expect that importing in runtime will be less trivial, but it's possible, isn't? Or did I miss something and there are cases, where above future import is not enough?

There might be, where generic types are used which are not really generic in runtime. It might be a rare case, but it might happen.

# some.pyi

Alias = SomeFakeGeneric[int]

There might be cases where stub-only modules or types are used:

• Marked as @typing.type_check_only
• Protected aliases import like in from django.utils.functional import _StrOrPromise in django-stubs
• _typeshed
• etc

[JelleZijlstra]

Yes, it is not possible to run stubs with a standard Python interpreter. I just tried with a few files in typeshed, and got the following problems:

• Importing from _typeshed
• A recursive type alias TraceFunction: TypeAlias = Callable[[FrameType, str, Any], TraceFunction | None] (throws NameError)
• A class returning an instance of itself as a forward reference (this one would be fixed by lazy evaluation of annotations)

This proposal doesn't say much about where the stub files should come from: should CPython ship them? If so, how do they interact with type checkers and with the stubs from typeshed?

I maintain a project https://github.com/JelleZijlstra/typeshed_client that contains functionality for finding stub files, parsing them, and locating names. This could be used to create a "superpowered inspect.signature" that returns a signature as defined in the stub files. But it would be a lot of complexity to add to the standard library.

[skirpichev]

@JelleZijlstra, thanks! For me, this kills the proposal:( I'll keep issue open for a while, maybe Steve could defend this idea.