Consider deprecating a bunch of `inspect` functions

[sobolevn (Nikita Sobolev)]

We have multiple APIs related to callables and signatures in inspect. Some of them even documented to exist only to match Python2 behavior. Plus, using some of them can lead to potential errors.

Separate issues: I suspect the same would be true of any stdlib code using either getargs or getfullargspec. We should probably deprecate and remove getargs and maybe eventually getfullargspec.

Originally suggested by @tjreedy

Problems

While working on `turtle.teleport` has incorrect-ish signature · Issue #107805 · python/cpython · GitHub I’ve noticed that inspect.getargs does not correctly handle:

1. pos-only params
2. kw-only params
3. some defaults
4. annotations

This was leading to a bug in callable generation, because some kw-only params were implicitly translated into regular ones.

List of functions to deprecate

So, I’ve strated looking into inspect’s API closer. Here’s a list of things that I find problematic:

• 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? · Issue #64637 · python/cpython · GitHub
  • Undeprecated: Undeprecate inspect.getfullargspec() · Issue #71359 · python/cpython · GitHub
  • Suggested to be deprecated again: Deprecate legacy introspection APIs in the inspect module · Issue #76371 · python/cpython · GitHub

  More history by @vstinner Deprecate legacy introspection APIs in the inspect module · Issue #76371 · python/cpython · GitHub

  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

Code search

Internal:

• getargs(): only in turtle.py, will be fixed in `turtle.teleport` has incorrect-ish signature · Issue #107805 · python/cpython · GitHub
• getargvalues(): not used
• getcallargs(): not used
• getfullargspec(): not used

All of these functions are used in the 3rd party projects:

• getargs(): https://github.com/search?type=code&q=inspect.getargs(
• getargvalues(): https://github.com/search?type=code&q=inspect.getargvalues(
• getcallargs(): https://github.com/search?type=code&q=inspect.getcallargs(
• getfullargspec(): https://github.com/search?type=code&q=inspect.getfullargspec(

Proposal

I propose to:

1. Provide modern alternatives to getargs and getargvalues
2. Deprecating these 4 functions above with a DeprecationWarning in 3.13 with no particular removal date

I can send PRs with new functions and deprecations, if we agree on this.

Please, share your feedback.

[gpshead (Gregory P. Smith)]

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.

[gpshead (Gregory P. Smith)]

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.

[vstinner (Victor Stinner)]

inspect.signature() is available since Python 3.3. Is it hard to migrate existing code to inspect.signature()? Would documentation and/or tooling help migrating?

[sobolevn (Nikita Sobolev)]

GH issue: Add modern alternatives to `inspect` module, deprecate old incorrect APIs · Issue #108901 · python/cpython · GitHub