[Python-checkins] bpo-33582: Emit deprecation warning for `formatargspec` (GH-6994)

[Ned Deily]

https://github.com/python/cpython/commit/46c5cd0f6e22bdfbdd3f0b18f1d01eda754e7e11
commit: 46c5cd0f6e22bdfbdd3f0b18f1d01eda754e7e11
branch: master
author: Matthias Bussonnier <bussonniermatthias at gmail.com>
committer: Ned Deily <nad at python.org>
date: 2018-06-11T16:08:16-04:00
summary:

bpo-33582: Emit deprecation warning for `formatargspec` (GH-6994)

files:
A Misc/NEWS.d/next/Library/2018-05-19-15-58-14.bpo-33582.qBZPmF.rst
M Lib/inspect.py
M Lib/test/test_inspect.py

diff --git a/Lib/inspect.py b/Lib/inspect.py
index 8dad817b292d..238a36821c73 100644
--- a/Lib/inspect.py
+++ b/Lib/inspect.py
@@ -18,7 +18,7 @@
 
     getargvalues(), getcallargs() - get info about function arguments
     getfullargspec() - same, with support for Python 3 features
-    formatargspec(), formatargvalues() - format an argument spec
+    formatargvalues() - format an argument spec
     getouterframes(), getinnerframes() - get info about frames
     currentframe() - get the current stack frame
     stack(), trace() - get info about frames on the stack or in a traceback
@@ -1211,7 +1211,19 @@ def formatargspec(args, varargs=None, varkw=None, defaults=None,
     kwonlyargs, kwonlydefaults, annotations).  The other five arguments
     are the corresponding optional formatting functions that are called to
     turn names and values into strings.  The last argument is an optional
-    function to format the sequence of arguments."""
+    function to format the sequence of arguments.
+
+    Deprecated since Python 3.5: use the `signature` function and `Signature`
+    objects.
+    """
+
+    from warnings import warn
+
+    warn("`formatargspec` is deprecated since Python 3.5. Use `signature` and "
+         " the `Signature` object directly",
+         DeprecationWarning,
+         stacklevel=2)
+
     def formatargandannotation(arg):
         result = formatarg(arg)
         if arg in annotations:
diff --git a/Lib/test/test_inspect.py b/Lib/test/test_inspect.py
index 35e86b5748e7..cda8d5cf73ef 100644
--- a/Lib/test/test_inspect.py
+++ b/Lib/test/test_inspect.py
@@ -712,8 +712,9 @@ def assertArgSpecEquals(self, routine, args_e, varargs_e=None,
         self.assertEqual(varkw, varkw_e)
         self.assertEqual(defaults, defaults_e)
         if formatted is not None:
-            self.assertEqual(inspect.formatargspec(args, varargs, varkw, defaults),
-                             formatted)
+            with self.assertWarns(DeprecationWarning):
+                self.assertEqual(inspect.formatargspec(args, varargs, varkw, defaults),
+                                 formatted)
 
     def assertFullArgSpecEquals(self, routine, args_e, varargs_e=None,
                                     varkw_e=None, defaults_e=None,
@@ -729,8 +730,9 @@ def assertFullArgSpecEquals(self, routine, args_e, varargs_e=None,
         self.assertEqual(kwonlydefaults, kwonlydefaults_e)
         self.assertEqual(ann, ann_e)
         if formatted is not None:
-            self.assertEqual(inspect.formatargspec(args, varargs, varkw, defaults,
-                                                    kwonlyargs, kwonlydefaults, ann),
+            with self.assertWarns(DeprecationWarning):
+                self.assertEqual(inspect.formatargspec(args, varargs, varkw, defaults,
+                                                       kwonlyargs, kwonlydefaults, ann),
                              formatted)
 
     def test_getargspec(self):
diff --git a/Misc/NEWS.d/next/Library/2018-05-19-15-58-14.bpo-33582.qBZPmF.rst b/Misc/NEWS.d/next/Library/2018-05-19-15-58-14.bpo-33582.qBZPmF.rst
new file mode 100644
index 000000000000..3471c0e7f0b8
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2018-05-19-15-58-14.bpo-33582.qBZPmF.rst
@@ -0,0 +1 @@
+Emit a deprecation warning for inspect.formatargspec