[Python-checkins] cpython (3.6): Issue #27172: Undeprecate inspect.getfullargspec()

[nick.coghlan]

https://hg.python.org/cpython/rev/14c2d93ffcb3
changeset:   105415:14c2d93ffcb3
branch:      3.6
parent:      105405:c9f68150cf90
user:        Nick Coghlan <ncoghlan at gmail.com>
date:        Fri Dec 02 20:29:57 2016 +1000
summary:
  Issue #27172: Undeprecate inspect.getfullargspec()

This is still useful for single source Python 2/3 code
migrating away from inspect.getargspec(), but that wasn't
clear with the documented deprecation in place.

files:
  Doc/library/inspect.rst |  54 +++++++++++++++++++---------
  Doc/whatsnew/3.6.rst    |   7 +++
  Lib/inspect.py          |  46 ++++++++++++++----------
  Misc/NEWS               |   5 ++
  4 files changed, 76 insertions(+), 36 deletions(-)


diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -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 <inspect-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 <inspect-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 <inspect-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
--- a/Doc/whatsnew/3.6.rst
+++ b/Doc/whatsnew/3.6.rst
@@ -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 --git a/Lib/inspect.py b/Lib/inspect.py
--- a/Lib/inspect.py
+++ b/Lib/inspect.py
@@ -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 --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -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.
 

-- 
Repository URL: https://hg.python.org/cpython