gh-108901: Add Signature.from_code method

[sobolevn]

• Issue: Add modern alternatives to inspect module, deprecate old incorrect APIs #108901

---

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

[sobolevn]

Failures are not related: #108888

[vstinner]

Please restrict this PR to add from_code(). Once it's merged, you can write a PR to deprecate.

[vstinner]

I like your overall change, here is a first review.

[sobolevn]

I moved my code, so there should be no unrelated diffs now :)

[vstinner]

LGTM, but I would prefer a second core dev review, since I don't know well this module.

[vstinner]

@pablogsal @AlexWaygood @1st1: Would you be interested to review this change?

[AlexWaygood]

A few nits:

[AlexWaygood]

Well, I worry that the reason this wasn't implemented in the original PEP-362 implementation is because the signatures produced for func1, func2 and func5 here are all incorrect, due to the fact that certain parameters have default values but this isn't reflected in the produced signatures :/

inspect.getargs() is used a fair bit in third-party projects. In the vast majority of these uses, they already have access to the function object, so they should probably just use Signature.from_callable() instead of this new method. But there are a few uses where they don't have access to the function object -- so I agree that something like this new method is probably needed, as a replacement for those uses:

• https://github.com/0compute/xtraceback/blob/5f4ae11cf21e6eea830d79aed66d3cd91bd013cd/xtraceback/xtracebackframe.py#L53-L55
• https://github.com/ponyorm/pony/blob/6f7620c9e66a4b8d4f7f7ba4a456b733aab9f374/pony/orm/decompiling.py#L793-L798
• https://github.com/parrt/lolviz/blob/301779d39934937795b71ad5d9d62d8a45f7bee1/lolviz.py#L297-L303

[AlexWaygood]

the signatures produced for func1, func2 and func5 here are all incorrect

Hmmm... well, they are actually valid signatures for the code object, since if you pass the code object to exec(), it doesn't take any notice of whether the original function had a default value or not:

>>> def foo(x=42): print(x)
...
>>> foo()
42
>>> c = foo.__code__
>>> exec(c)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: foo() missing 1 required positional argument: 'x'

Why anybody would care what the signature of the code object itself is, though, I'm not sure -- ISTM that everybody trying to get the signature from a code object is just using the code object as the next-best-thing for the function the code object belongs to. I don't think many people are passing code objects directly to exec() It's not even really possible to pass a parameter to a code object you're calling via exec() AFAIK.

[AlexWaygood]

Maybe we just need to flag more forcefully in the docs the limitations of this new constructor method. I can offer some suggestions once you've addressed the review comments I've already posted 👍

[sobolevn]

I added a .. note:: notation to highlight it even better.

[AlexWaygood]

The more I think about this, the more concerned I am :/

The existing getargs() function that we have in inspect gives accurate information. It doesn't claim to be able to tell you everything about the signature: it only claims to be able to tell you some information about the signature:

• It gives you a list of argument names
• It tells you the name of the *vararg argument, if there is one
• It tells you the name of the **kwarg argument, if there is one

This new function, however, claims to be able to give you a complete and accurate signature from a code object (in that it constructs a Signature object from a code object). That's impossible, since code objects don't have information about which arguments have default values, and so the function gives you inaccurate information.

I'm not sure having a prominent note in the docs is sufficient to fix this issue: adding a new constructor that we know gives inaccurate results seems very troubling to me. Perhaps a better solution would be to document getargs and promote it to public API?

[AlexWaygood]

True. This new API would provide helpful information that is not currently offered by getargs.

However. Does it make sense to think of code objects even having a "signature"? Functions have signatures, and you can construct functions from code objects. But as your snippet above demonstrates, you can't directly call code objects (except via exec(), but nobody does that really) -- you have to create a new function from the code object in order to get something that can be called.

Which "signature" are we trying to get here? The signature of the function from which the code object originally came (if it came from a code object), or the signature a new function object would have if we created one from the code object? Getting a "signature from a code object" feels like quite a confusing concept to me.

[AlexWaygood]

Another option: we could document that if people want to get "signature information" from a code object co, they just need to do this:

inspect.signature(types.FunctionType(co, {}))

That way, they are forced to be explicit that code objects don't really have a "signature": you need to construct a new function from the code object in order to get a code object that actually has a signature

[sobolevn]

>>> import types, inspect
>>> def a(x: int, /, *, y: str = '') -> None: ...
... 
>>> inspect.signature(types.FunctionType(a.__code__, {}))
<Signature (x, /, *, y)>

It is up to you to decide whether or not we should do it. I consider this PR done from my side.

[AlexWaygood]

Currently, I'm leaning towards not adding this alternative constructor, and just documenting that people should call inspect.signature(types.FunctionType(co, {})) if they need to get signature information from a code object co, and the function object is not available for whatever reason.

One of the third-party projects that uses getargs is Quora: https://github.com/quora/qcore/blob/e12a4929c8e75ec2dd878c06270cedcac72a643e/qcore/inspection.py#L130-L148. I'd be curious to know if @JelleZijlstra has any thoughts on whether getargs should be documented or deprecated and, if the latter, whether we should add this Signature.from_code() method or just add documentation along the lines of my sugestion.

[JelleZijlstra]

Any code using that qcore function should really be migrated to use inspect.signature directly. As the docstring notes, the function doesn't deal correctly with kwonly arguments.

I think we don't need Signature.from_code. My experience is that it is rare that you have only a code object without a function it came from, and code that manipulates code objects directly should generally be migrated to a more modern inspect API.

[AlexWaygood]

Thanks for the PR, @sobolevn -- it was well done. But I think adding a constructor that implies you can construct a complete Signature from a code object is too misleading. Let's go with documenting that you should call inspect.signature(types.FunctionType(co, {})) in the rare cases that you don't have access to the original function object.