Deprecate "hold" kwarg and machinery.

efiring · efiring · commit 65a10b9c00b4 · 2016-11-25T16:18:11.000-10:00
diff --git a/boilerplate.py b/boilerplate.py
@@ -50,15 +50,19 @@
 @_autogen_docstring(Axes.%(func)s)
 def %(func)s(%(argspec)s):
     %(ax)s = gca()
-    # allow callers to override the hold state by passing hold=True|False
-    %(washold)s = %(ax)s.ishold()
+    # Deprecated: allow callers to override the hold state
+    # by passing hold=True|False
+    %(washold)s = %(ax)s._hold
 %(sethold)s
     if hold is not None:
-        %(ax)s.hold(hold)
+        %(ax)s._hold = hold
+        from matplotlib.cbook import mplDeprecation
+        warnings.warn("The 'hold' kwarg is deprecated since 2.0.",
+                      mplDeprecation)
     try:
         %(ret)s = %(ax)s.%(func)s(%(call)s)
     finally:
-        %(ax)s.hold(%(washold)s)
+        %(ax)s._hold = %(washold)s
 %(mappable)s
     return %(ret)s
 """
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -1665,7 +1665,7 @@ def acorr(self, x, **kwargs):
 
         x : sequence of scalar
 
-        hold : boolean, optional, default: True
+        hold : boolean, optional, *deprecated*, default: True
 
         detrend : callable, optional, default: `mlab.detrend_none`
             x is detrended by the `detrend` callable. Default is no
@@ -1713,6 +1713,8 @@ def acorr(self, x, **kwargs):
         .. plot:: mpl_examples/pylab_examples/xcorr_demo.py
 
         """
+        if "hold" in kwargs:
+            warnings.warn("the 'hold' kwarg is deprecated", mplDeprecation)
         return self.xcorr(x, x, **kwargs)
 
     @unpack_labeled_data(replace_names=["x", "y"], label_namer="y")
@@ -1730,7 +1732,7 @@ def xcorr(self, x, y, normed=True, detrend=mlab.detrend_none,
 
         y : sequence of scalars of length n
 
-        hold : boolean, optional, default: True
+        hold : boolean, optional, *deprecated*, default: True
 
         detrend : callable, optional, default: `mlab.detrend_none`
             x is detrended by the `detrend` callable. Default is no
@@ -1769,6 +1771,8 @@ def xcorr(self, x, y, normed=True, detrend=mlab.detrend_none,
         The cross correlation is performed with :func:`numpy.correlate` with
         `mode` = 2.
         """
+        if "hold" in kwargs:
+            warnings.warn("the 'hold' kwarg is deprecated", mplDeprecation)
 
         Nx = len(x)
         if Nx != len(y):
@@ -2136,7 +2140,7 @@ def make_iterable(x):
             patches.append(r)
 
         holdstate = self._hold
-        self.hold(True)  # ensure hold is on before plotting errorbars
+        self._hold = True  # ensure hold is on before plotting errorbars
 
         if xerr is not None or yerr is not None:
             if orientation == 'vertical':
@@ -2158,7 +2162,7 @@ def make_iterable(x):
         else:
             errorbar = None
 
-        self.hold(holdstate)  # restore previous hold state
+        self._hold = holdstate  # restore previous hold state
 
         if adjust_xlim:
             xmin, xmax = self.dataLim.intervalx
@@ -2380,7 +2384,7 @@ def stem(self, *args, **kwargs):
         remember_hold = self._hold
         if not self._hold:
             self.cla()
-        self.hold(True)
+        self._hold = True
 
         # Assume there's at least one data array
         y = np.asarray(args[0])
@@ -2464,7 +2468,7 @@ def stem(self, *args, **kwargs):
                               color=basecolor, linestyle=basestyle,
                               marker=basemarker, label="_nolegend_")
 
-        self.hold(remember_hold)
+        self._hold = remember_hold
 
         stem_container = StemContainer((markerline, stemlines, baseline),
                                        label=label)
@@ -3786,7 +3790,7 @@ def dopatch(xs, ys, **kwargs):
             setlabels(datalabels)
 
         # reset hold status
-        self.hold(holdStatus)
+        self._hold=holdStatus
 
         return dict(whiskers=whiskers, caps=caps, boxes=boxes,
                     medians=medians, fliers=fliers, means=means)
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -1191,14 +1191,25 @@ def set_color_cycle(self, clist):
         else:
             self.set_prop_cycle('color', clist)
 
+    @cbook.deprecated("2.0")
     def ishold(self):
-        """return the HOLD status of the axes"""
+        """return the HOLD status of the axes
+
+        The `hold` mechanism is deprecated and will be removed in
+        v3.0.
+        """
+
         return self._hold
 
+    @cbook.deprecated("2.0")
     def hold(self, b=None):
         """
         Set the hold state
 
+        The ``hold`` mechanism is deprecated and will be removed in
+        v3.0.  The behavior will remain consistent with the
+        long-time default value of True.
+
         If *hold* is *None* (default), toggle the *hold* state.  Else
         set the *hold* state to boolean value *b*.
 
@@ -1223,6 +1234,7 @@ def hold(self, b=None):
         else:
             self._hold = b
 
+
     def get_aspect(self):
         return self._aspect
 
diff --git a/lib/matplotlib/colorbar.py b/lib/matplotlib/colorbar.py
@@ -501,10 +501,10 @@ def _add_solids(self, X, Y, C):
         # Save, set, and restore hold state to keep pcolor from
         # clearing the axes. Ordinarily this will not be needed,
         # since the axes object should already have hold set.
-        _hold = self.ax.ishold()
-        self.ax.hold(True)
+        _hold = self.ax._hold
+        self.ax._hold = True
         col = self.ax.pcolormesh(*args, **kw)
-        self.ax.hold(_hold)
+        self.ax._hold = _hold
         #self.add_observer(col) # We should observe, not be observed...
 
         if self.solids is not None:
@@ -1262,8 +1262,8 @@ def _add_solids(self, X, Y, C):
         # Save, set, and restore hold state to keep pcolor from
         # clearing the axes. Ordinarily this will not be needed,
         # since the axes object should already have hold set.
-        _hold = self.ax.ishold()
-        self.ax.hold(True)
+        _hold = self.ax._hold
+        self.ax._hold = True
 
         kw = {'alpha': self.alpha, }
 
@@ -1309,7 +1309,7 @@ def _add_solids(self, X, Y, C):
                     linewidths=(0.5 * mpl.rcParams['axes.linewidth'],))
             self.ax.add_collection(self.dividers)
 
-        self.ax.hold(_hold)
+        self.ax._hold = _hold
 
 
 def colorbar_factory(cax, mappable, **kwargs):
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -569,6 +569,7 @@ def set_canvas(self, canvas):
         """
         self.canvas = canvas
 
+    @cbook.deprecated("2.0")
     def hold(self, b=None):
         """
         Set the hold state.  If hold is None (default), toggle the
@@ -579,6 +580,8 @@ def hold(self, b=None):
             hold()      # toggle hold
             hold(True)  # hold is on
             hold(False) # hold is off
+
+        All "hold" machinery is deprecated.
         """
         if b is None:
             self._hold = not self._hold
@@ -1591,7 +1594,7 @@ def colorbar(self, mappable, cax=None, ax=None, use_gridspec=True, **kw):
                 cax, kw = cbar.make_axes_gridspec(ax, **kw)
             else:
                 cax, kw = cbar.make_axes(ax, **kw)
-        cax.hold(True)
+        cax._hold = True
         cb = cbar.colorbar_factory(cax, mappable, **kw)
 
         self.sca(current_ax)
diff --git a/lib/matplotlib/pylab.py b/lib/matplotlib/pylab.py
@@ -49,14 +49,12 @@
   getp      - get a graphics property
   grid     - set whether gridding is on
   hist     - make a histogram
-  hold     - set the axes hold state
   ioff     - turn interaction mode off
   ion      - turn interaction mode on
   isinteractive - return True if interaction mode is on
   imread   - load image file into array
   imsave   - save array as an image file
   imshow   - plot image data
-  ishold   - return the hold state of the current axes
   legend   - make an axes legend
   locator_params - adjust parameters used in locating axis ticks
   loglog   - a log log plot
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
diff --git a/matplotlibrc.template b/matplotlibrc.template
