Merge pull request #9968 from timhoffm/deprecate-pyplot.axes-ax

tacaswell · web-flow · commit 1d1d23e580ee · 2017-12-12T22:47:26.000-05:00
API: Deprecate pyplot.axes with an Axes argument
diff --git a/doc/api/api_changes/2017-12-10-TH.rst b/doc/api/api_changes/2017-12-10-TH.rst
@@ -0,0 +1,6 @@
+Deprecations
+````````````
+
+Using `.pyplot.axes` with an `.Axes` as argument is deprecated. This sets
+the current axes, i.e. it has the same effect as `.pyplot.sca`. For clarity
+``plt.sca(ax)`` should be preferred over ``plt.axes(ax)``.
diff --git a/examples/images_contours_and_fields/multi_image.py b/examples/images_contours_and_fields/multi_image.py
@@ -8,7 +8,7 @@
 It also illustrates colorbar tick labelling with a multiplier.
 """
 
-from matplotlib.pyplot import figure, show, axes, sci
+from matplotlib.pyplot import figure, show, sca, sci
 from matplotlib import cm, colors
 from matplotlib.font_manager import FontProperties
 import numpy as np
@@ -77,7 +77,7 @@ def __call__(self, leader):
 # We need the following only if we want to run this interactively and
 # modify the colormap:
 
-axes(ax[0])     # Return the current axes to the first one,
+sca(ax[0])     # Return the current axes to the first one,
 sci(images[0])  # because the current image must be in current axes.
 
 show()
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -34,7 +34,7 @@
 from matplotlib import _pylab_helpers, interactive
 from matplotlib.cbook import dedent, silent_list, is_numlike
 from matplotlib.cbook import _string_to_bool
-from matplotlib.cbook import deprecated
+from matplotlib.cbook import deprecated, warn_deprecated
 from matplotlib import docstring
 from matplotlib.backend_bases import FigureCanvasBase
 from matplotlib.figure import Figure, figaspect
@@ -883,6 +883,9 @@ def axes(arg=None, **kwargs):
           axes to *arg*. Note: This implicitly changes the current figure to
           the parent of *arg*.
 
+          .. note:: The use of an Axes as an argument is deprecated and will be
+                    removed in v3.0. Please use `.pyplot.sca` instead.
+
     Other Parameters
     ----------------
     **kwargs :
@@ -927,6 +930,10 @@ def axes(arg=None, **kwargs):
         return subplot(111, **kwargs)
 
     if isinstance(arg, Axes):
+        warn_deprecated("2.2",
+                        message="Using pyplot.axes(ax) with ax an Axes "
+                                "argument is deprecated. Please use "
+                                "pyplot.sca(ax) instead.")
         ax = arg
         sca(ax)
         return ax
