[docs] [issue32190] Separate out legacy introspection APIs in the inspect docs

[Nick Coghlan]

New submission from Nick Coghlan <ncoghlan at gmail.com>:

(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.

----------
assignee: docs at python
components: Documentation
messages: 307362
nosy: brett.cannon, docs at python, ncoghlan
priority: normal
severity: normal
stage: needs patch
status: open
title: Separate out legacy introspection APIs in the inspect docs
type: enhancement
versions: Python 3.6, Python 3.7

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue32190>
_______________________________________