classification
Title: Separate out legacy introspection APIs in the inspect docs
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.7, Python 3.6
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: brett.cannon, docs@python, ncoghlan
Priority: normal Keywords:

Created on 2017-12-01 05:22 by ncoghlan, last changed 2017-12-01 05:22 by ncoghlan.

Messages (1)
msg307362 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-12-01 05:22
(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.
History
Date User Action Args
2017-12-01 05:22:05ncoghlancreate