diff -r 2dd08b5b5ee6 Doc/library/inspect.rst --- a/Doc/library/inspect.rst Tue Nov 29 09:46:26 2016 -0800 +++ b/Doc/library/inspect.rst Thu Dec 01 22:56:14 2016 +1000 @@ -815,45 +815,65 @@ .. 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 -r 2dd08b5b5ee6 Doc/whatsnew/3.6.rst --- a/Doc/whatsnew/3.6.rst Tue Nov 29 09:46:26 2016 -0800 +++ b/Doc/whatsnew/3.6.rst Thu Dec 01 22:56:14 2016 +1000 @@ -1155,6 +1155,13 @@ 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 -r 2dd08b5b5ee6 Lib/inspect.py --- a/Lib/inspect.py Tue Nov 29 09:46:26 2016 -0800 +++ b/Lib/inspect.py Thu Dec 01 22:56:14 2016 +1000 @@ -1019,24 +1019,30 @@ 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. - - 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. + '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. + + 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 @@ '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. - - This function is deprecated, use inspect.signature() instead. + 'annotations' is a dictionary mapping parameter names to annotations. + + 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 -r 2dd08b5b5ee6 Misc/NEWS --- a/Misc/NEWS Tue Nov 29 09:46:26 2016 -0800 +++ b/Misc/NEWS Thu Dec 01 22:56:14 2016 +1000 @@ -21,6 +21,11 @@ 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.