Add modern alternatives to `inspect` module, deprecate old incorrect APIs

[sobolevn]

Feature or enhancement

Proposal:

I propose to provide modern alternatives to and deprecate these inspect members:

• getargs() undocumented helper used in getargvalues. It works with __code__ objects. Can it be replaced with modern tooling? Not yet: we have an internal helper to get signatures from __code__ objects: https://github.com/python/cpython/blob/39ef93edb9802dccdb6555d4209ac2e60875a011/Lib/inspect.py#L2423-L2488 But, some refactoring is required

• getargvalues() only works with frame objects, but it does not work correctly with pos-only and kw-only parameters. Bug: inspect.getargvalues does not work correctly for pos-only and kw-only arguments · Issue #107833 · python/cpython · GitHub Can it be replaced with modern tooling? No, I propose adding inspect.Signature.from_frame method

Notice: formatargvalues should also be deprecated, because the only way to use is together with getargvalues.

There was a reverted attempt to depracate them in 3.5

• getcallargs() was documented as deprecated for a long time, it also has known bugs with pos-only params (inspect.getcallargs does not raise TypeError for pos-only passed as keywords · Issue #107831 · python/cpython · GitHub). Can it be replaced with modern tooling? Yes: inspect.Signature.bind

• getfullargspec() is documented as

  Note that signature() and Signature Object provide the recommended API for callable introspection, and support additional behaviours (like positional-only arguments) that are sometimes encountered in extension module APIs. This function is retained primarily for use in code that needs to maintain compatibility with the Python 2 inspect module API.

It has a rich history of deprecation / undeprecation:

• Deprecated: inspect: Deprecate getfullargspec? #64637
• Undeprecated: Undeprecate inspect.getfullargspec() #71359
• Suggested to be deprecated again: Deprecate legacy introspection APIs in the inspect module #76371

More history: #76371 (comment)

It is broken in a sense that it does not differentiate pos-only from pos-or-keyword parameters.

Can it be replaced with modern tooling? Partially: inspect.signature has some differences. But, getfullargspec() uses signature() internally

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/consider-deprecating-a-bunch-of-inspect-functions/31369

CC @gpshead

Linked PRs

• gh-108901: Add Signature.from_code method #108902
• gh-108901: Deprecate inspect.getcallargs and slate it for removal #112236
• gh-108901: Deprecate inspect.getargs, slate it for removal in 3.15 #112279
• gh-108901: Deprecate inspect.getfullargspec and slate it for removal in 3.15 #112314
• gh-108901: Deprecate inspect.getargvalues and inspect.formatargvalues, provide modern alternative #112639
• gh-108901: Add inspect.Signature.from_frame #116537
• gh-108901: Add bound_arg to Signature.from_callable() and signature() #116559

[sobolevn]

The important thing is having modern fully capable alternatives in place that can satisfy the needs of users of the existing APIs. Without that, deprecating these only causes pain as no functional alternatives exist. So overall, agreed: Succeed in doing #1 (modern alternatives) and #2 (open ended deprecation) can actually be started.

I think that we should do it on a per-function basis. So, we can work incrementally on it.

It is also worth considering if the replacement can be done such that it is usable Python 3.8-3.12 as a PyPI package so that existing users of the APIs could go ahead and move off everywhere.

Good idea!

[vstinner]

I propose to provide modern alternatives to and deprecate these inspect members

Why not just using inspect.singature()? Would you mind to elaborate what are signature() issues? Its design allowed to support smoothly positional only arguments.

[sobolevn]

Why not just using inspect.singature()?

I am using inspect.Signature.from_code :)
But, right now it was impossible to use Signature created from CodeType.
My PR solves that, so there's now no need to use getargs() at all.

[hugovk]

For each of these (#112236, #112279, #112314), please can you add documentation either to Porting to Python 3.13 (and/or their relevant docs pages) that shows examples of code using the old API, and the recommended replacement?

This will help people upgrade.

[sobolevn]

Sure! I will update all PRs soon.