Deprecate legacy introspection APIs in the inspect module

[ncoghlan]

BPO	32190
Nosy	@brettcannon, @ncoghlan

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2017-12-01.05:22:05.533>
labels = ['type-feature', '3.7', 'docs']
title = 'Separate out legacy introspection APIs in the inspect docs'
updated_at = <Date 2017-12-01.05:22:05.533>
user = 'https://github.com/ncoghlan'

bugs.python.org fields:

activity = <Date 2017-12-01.05:22:05.533>
actor = 'ncoghlan'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2017-12-01.05:22:05.533>
creator = 'ncoghlan'
dependencies = []
files = []
hgrepos = []
issue_num = 32190
keywords = []
message_count = 1.0
messages = ['307362']
nosy_count = 3.0
nosy_names = ['brett.cannon', 'ncoghlan', 'docs@python']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue32190'
versions = ['Python 3.6', 'Python 3.7']

[ncoghlan]

(Follow up to https://bugs.python.org/issue27172)

The deprecation notice on inspect.getfullargspec has been removed, since we want folks porting from Python 2 to rely on it as part of the porting process, rather than feeling they need to upgrade to using inspect.signature() immediately.

At the same time, we really don't want folks relying on it for *new* code, since it has some inherent limitations (like failing to distinguish positional-only args from positional-and-keyword ones), and some odd historical quirks (like reporting the bound arg as part of the signature for already bound methods).

The subprocess modules clearly separates out the "Older high-level API" https://docs.python.org/3/library/subprocess.html#older-high-level-api to help make it clear that new code should use "subprocess.run" instead.

We could potentially add a similar final section to the inspect documentation for "Legacy introspection APIs".

That would also be useful if https://bugs.python.org/issue31230 is eventually implemented - the current generator and coroutine specific APIs could be moved down to the legacy section for backwards compatibility maintenance, with the type independent API being preferred for new code.

[iritkatriel]

Repurposing this issue to re-deprecate these APIs instead.

[vstinner]

My notes on "Python 3.11: remove inspect.getargspec()":

• inspect.signature() added to Python 3.3
• inspect.getfullargspec() is still there
• Remove inspect.getargspec() and inspect.formatargspec()

Part 1:

• https://bugs.python.org/issue20438
• Deprecate: https://hg.python.org/cpython/rev/3a5fec5e025d
• Remove deprecation: 0899b98

Part 2:

• https://bugs.python.org/issue25486
• Remove: https://hg.python.org/cpython/rev/a565aad5d6e1
• Add again: https://hg.python.org/cpython/rev/32c8bdcd66cc

Part 3:

• https://bugs.python.org/issue45320
• Remove: d89fb9a

Broken project (1):

• sqlalchemy:

  • https://src.fedoraproject.org/rpms/python-sqlalchemy/pull-request/2#request_diff
  • https://bugzilla.redhat.com/show_bug.cgi?id=1591353

[vstinner]

IMO it's fine to deprecate inspect.getfullargspec(), but don't plan its removal yet. Maybe even add a comment (to avoid people who like removing deprecated functions, like me!) that this deprecated function should be kept for now, since it's still widely used (just add a link to this issue).

The main advantage of inspect.signature(), compared to getfullargspec(), is that it handles positional-only arguments.

inspect.signature() exists since Python 3.3. More and more projects are requiring a minimum Python version of Python 3.7, or Python 3.6 in the worst case. So it's fine to use inspect.signature().