From 945fff44c496c3d918d42b148087faf73008c85d Mon Sep 17 00:00:00 2001
From: Yury Selivanov <yselivanov@sprymix.com>
Date: Fri, 22 May 2015 16:28:05 -0400
Subject: [PATCH] Issue 20438: Add a note about deprecating old inspect APIs to
 whatsnew.

Also, deprecate formatargspec, formatargvalues, and getargvalues
functions.  Since we are deprecating 'getfullargspec' function in
3.5 (documentation only, no DeprecationWarning), it makes sense
to also deprecate functions designed to be directly used with it.

In 3.6 we will remove 'getargsspec' function (was deprecated since
Python 3.0), and start raising DeprecationWarnings in other
'getarg*' family of functions.  We can remove them in 3.7 or later.

Also, it is worth noting, that Signature API does not provide 100%
of functionality that deprecated APIs have.  It is important to do
a soft deprecation of outdated APIs in 3.5 to gather users feedback,
and improve Signature object.
---
 Doc/library/inspect.rst | 21 +++++++++++++++++++--
 Doc/whatsnew/3.5.rst    | 10 ++++++++++
 2 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index 6543da974d5..2eefcf2f700 100644
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -793,8 +793,10 @@ Classes and functions
    *n* elements listed in *args*.
 
    .. deprecated:: 3.0
-      Use :func:`getfullargspec` instead, which provides information about
-      keyword-only arguments and annotations.
+      Use :func:`signature` and
+      :ref:`Signature Object <inspect-signature-object>`, which provide a
+      better introspecting API for callables.  This function will be removed
+      in Python 3.6.
 
 
 .. function:: getfullargspec(func)
@@ -834,6 +836,11 @@ Classes and functions
    are the names of the ``*`` and ``**`` arguments or ``None``.  *locals* is the
    locals dictionary of the given frame.
 
+   .. deprecated:: 3.5
+      Use :func:`signature` and
+      :ref:`Signature Object <inspect-signature-object>`, which provide a
+      better introspecting API for callables.
+
 
 .. function:: formatargspec(args[, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations[, formatarg, formatvarargs, formatvarkw, formatvalue, formatreturns, formatannotations]])
 
@@ -856,6 +863,11 @@ Classes and functions
    >>> formatargspec(*getfullargspec(f))
    '(a: int, b: float)'
 
+   .. deprecated:: 3.5
+      Use :func:`signature` and
+      :ref:`Signature Object <inspect-signature-object>`, which provide a
+      better introspecting API for callables.
+
 
 .. function:: formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])
 
@@ -863,6 +875,11 @@ Classes and functions
    :func:`getargvalues`.  The format\* arguments are the corresponding optional
    formatting functions that are called to turn names and values into strings.
 
+   .. deprecated:: 3.5
+      Use :func:`signature` and
+      :ref:`Signature Object <inspect-signature-object>`, which provide a
+      better introspecting API for callables.
+
 
 .. function:: getmro(cls)
 
diff --git a/Doc/whatsnew/3.5.rst b/Doc/whatsnew/3.5.rst
index 672e1fbc717..0a179691c16 100644
--- a/Doc/whatsnew/3.5.rst
+++ b/Doc/whatsnew/3.5.rst
@@ -815,6 +815,16 @@ Deprecated Python modules, functions and methods
   :meth:`inspect.Signature.from_callable` instead. (Contributed by Yury
   Selivanov in :issue:`24248`.)
 
+* :func:`inspect.getargspec` is deprecated and scheduled to be removed in
+  Python 3.6.  (See :issue:`20438` for details.)
+
+* :func:`~inspect.getfullargspec`, :func:`~inspect.getargvalues`,
+  :func:`~inspect.getcallargs`, :func:`~inspect.getargvalues`,
+  :func:`~inspect.formatargspec`, and :func:`~inspect.formatargvalues` are
+  deprecated in favor of :func:`inspect.signature` API.  (See :issue:`20438`
+  for details.)
+
+
 Deprecated functions and types of the C API
 -------------------------------------------