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

(cherry picked from commit 46c5cd0f6e22bdfbdd3f0b18f1d01eda754e7e11)

Co-authored-by: Matthias Bussonnier <bussonniermatthias@gmail.com>

1 files changed, 14 insertions, 2 deletions

diff --git a/Lib/inspect.py b/Lib/inspect.py
index 022cc19..8e242e8 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: