From 46c5cd0f6e22bdfbdd3f0b18f1d01eda754e7e11 Mon Sep 17 00:00:00 2001
From: Matthias Bussonnier <bussonniermatthias@gmail.com>
Date: Mon, 11 Jun 2018 22:08:16 +0200
Subject: [PATCH] bpo-33582: Emit deprecation warning for `formatargspec`
 (GH-6994)

---
 Lib/inspect.py                                   | 16 ++++++++++++++--
 Lib/test/test_inspect.py                         | 10 ++++++----
 .../2018-05-19-15-58-14.bpo-33582.qBZPmF.rst     |  1 +
 3 files changed, 21 insertions(+), 6 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Library/2018-05-19-15-58-14.bpo-33582.qBZPmF.rst

diff --git a/Lib/inspect.py b/Lib/inspect.py
index 8dad817b292..238a36821c7 100644
--- a/Lib/inspect.py
+++ b/Lib/inspect.py
@@ -18,7 +18,7 @@ Here are some of the useful functions provided by this module:
 
     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 35e86b5748e..cda8d5cf73e 100644
--- a/Lib/test/test_inspect.py
+++ b/Lib/test/test_inspect.py
@@ -712,8 +712,9 @@ class TestClassesAndFunctions(unittest.TestCase):
         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 @@ class TestClassesAndFunctions(unittest.TestCase):
         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 00000000000..3471c0e7f0b
--- /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