diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index fc815a672ce..de0c301c1e4 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -815,45 +815,65 @@ Classes and functions .. function:: getargspec(func) - Get the names and default values of a Python function's arguments. A + Get the names and default values of a Python function's parameters. A :term:`named tuple` ``ArgSpec(args, varargs, keywords, defaults)`` is - returned. *args* is a list of the argument names. *varargs* and *keywords* - are the names of the ``*`` and ``**`` arguments or ``None``. *defaults* is a + returned. *args* is a list of the parameter names. *varargs* and *keywords* + are the names of the ``*`` and ``**`` parameters or ``None``. *defaults* is a tuple of default argument values or ``None`` if there are no default arguments; if this tuple has *n* elements, they correspond to the last *n* elements listed in *args*. .. deprecated:: 3.0 - Use :func:`signature` and + Use :func:`getfullargspec` for an updated API that is usually a drop-in + replacement, but also correctly handles function annotations and + keyword-only parameters. + + Alternatively, use :func:`signature` and :ref:`Signature Object `, which provide a - better introspecting API for callables. + more structured introspection API for callables. .. function:: getfullargspec(func) - Get the names and default values of a Python function's arguments. A + Get the names and default values of a Python function's parameters. A :term:`named tuple` is returned: ``FullArgSpec(args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations)`` - *args* is a list of the argument names. *varargs* and *varkw* are the names - of the ``*`` and ``**`` arguments or ``None``. *defaults* is an *n*-tuple - of the default values of the last *n* arguments, or ``None`` if there are no - default arguments. *kwonlyargs* is a list of - keyword-only argument names. *kwonlydefaults* is a dictionary mapping names - from kwonlyargs to defaults. *annotations* is a dictionary mapping argument - names to annotations. + *args* is a list of the positional parameter names. + *varargs* is the name of the ``*`` parameter or ``None`` if arbitrary + positional arguments are not accepted. + *varkw* is the name of the ``**`` parameter or ``None`` if arbitrary + keyword arguments are not accepted. + *defaults* is an *n*-tuple of default argument values corresponding to the + last *n* positional parameters, or ``None`` if there are no such defaults + defined. + *kwonlyargs* is a list of keyword-only parameter names. + *kwonlydefaults* is a dictionary mapping parameter names from *kwonlyargs* + to the default values used if no argument is supplied. + *annotations* is a dictionary mapping parameter names to annotations. + The special key ``"return"`` is used to report the function return value + annotation (if any). + + Note that :func:`signature` and + :ref:`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. .. versionchanged:: 3.4 This function is now based on :func:`signature`, but still ignores ``__wrapped__`` attributes and includes the already bound first parameter in the signature output for bound methods. - .. deprecated:: 3.5 - Use :func:`signature` and - :ref:`Signature Object `, which provide a - better introspecting API for callables. + .. versionchanged:: 3.6 + This method was previously documented as deprecated in favour of + :func:`signature` in Python 3.5, but that decision has been reversed + in order to restore a clearly supported standard interface for + single-source Python 2/3 code migrating away from the legacy + :func:`getargspec` API. .. function:: getargvalues(frame) diff --git a/Doc/whatsnew/3.6.rst b/Doc/whatsnew/3.6.rst index 3beea09c646..5b5884d46d3 100644 --- a/Doc/whatsnew/3.6.rst +++ b/Doc/whatsnew/3.6.rst @@ -1155,6 +1155,13 @@ implicit ``.0`` parameters generated by the compiler for comprehension and generator expression scopes as if they were positional-only parameters called ``implicit0``. (Contributed by Jelle Zijlstra in :issue:`19611`.) +To reduce code churn when upgrading from Python 2.7 and the legacy +:func:`inspect.getargspec` API, the previously documented deprecation of +:func:`inspect.getfullargspec` has been reversed. While this function is +convenient for single/source Python 2/3 code bases, the richer +:func:`inspect.signature` interface remains the recommended approach for new +code. (Contributed by Nick Coghlan in :issue:`27172`) + json ---- diff --git a/Lib/inspect.py b/Lib/inspect.py index 6640375263f..e08e9f578ee 100644 --- a/Lib/inspect.py +++ b/Lib/inspect.py @@ -1019,24 +1019,30 @@ def _getfullargs(co): ArgSpec = namedtuple('ArgSpec', 'args varargs keywords defaults') def getargspec(func): - """Get the names and default values of a function's arguments. + """Get the names and default values of a function's parameters. A tuple of four things is returned: (args, varargs, keywords, defaults). 'args' is a list of the argument names, including keyword-only argument names. - 'varargs' and 'keywords' are the names of the * and ** arguments or None. - 'defaults' is an n-tuple of the default values of the last n arguments. + 'varargs' and 'keywords' are the names of the * and ** parameters or None. + 'defaults' is an n-tuple of the default values of the last n parameters. - Use the getfullargspec() API for Python 3 code, as annotations - and keyword arguments are supported. getargspec() will raise ValueError - if the func has either annotations or keyword arguments. + This function is deprecated, as it does not support annotations or + keyword-only parameters and will raise ValueError if either is present + on the supplied callable. + + For a more structured introspection API, use inspect.signature() instead. + + Alternatively, use getfullargspec() for an API with a similar namedtuple + based interface, but full support for annotations and keyword-only + parameters. """ warnings.warn("inspect.getargspec() is deprecated, " - "use inspect.signature() instead", DeprecationWarning, - stacklevel=2) + "use inspect.signature() or inspect.getfullargspec()", + DeprecationWarning, stacklevel=2) args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, ann = \ getfullargspec(func) if kwonlyargs or ann: - raise ValueError("Function has keyword-only arguments or annotations" + raise ValueError("Function has keyword-only parameters or annotations" ", use getfullargspec() API which can support them") return ArgSpec(args, varargs, varkw, defaults) @@ -1044,18 +1050,20 @@ FullArgSpec = namedtuple('FullArgSpec', 'args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations') def getfullargspec(func): - """Get the names and default values of a callable object's arguments. + """Get the names and default values of a callable object's parameters. A tuple of seven things is returned: - (args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults annotations). - 'args' is a list of the argument names. - 'varargs' and 'varkw' are the names of the * and ** arguments or None. - 'defaults' is an n-tuple of the default values of the last n arguments. - 'kwonlyargs' is a list of keyword-only argument names. + (args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations). + 'args' is a list of the parameter names. + 'varargs' and 'varkw' are the names of the * and ** parameters or None. + 'defaults' is an n-tuple of the default values of the last n parameters. + 'kwonlyargs' is a list of keyword-only parameter names. 'kwonlydefaults' is a dictionary mapping names from kwonlyargs to defaults. - 'annotations' is a dictionary mapping argument names to annotations. + 'annotations' is a dictionary mapping parameter names to annotations. - This function is deprecated, use inspect.signature() instead. + Notable differences from inspect.signature(): + - the "self" parameter is always reported, even for bound methods + - wrapper chains defined by __wrapped__ *not* unwrapped automatically """ try: diff --git a/Misc/NEWS b/Misc/NEWS index 97b159722e2..c0f3dc53c82 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -21,6 +21,11 @@ Core and Builtins Library ------- +- Issue #27172: To assist with upgrades from 2.7, the previously documented + deprecation of ``inspect.getfullargspec()`` has been reversed. This decision + may be revisited again after the Python 2.7 branch is no longer officially + supported. + - Issue #24142: Reading a corrupt config file left configparser in an invalid state. Original patch by Florian Höch.