Merge pull request matplotlib#7516 from efiring/kill_hold_stage2

API: Deprecate "hold" kwarg and machinery.

Author: tacaswell

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' keyword argument 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
 """

doc/api/api_changes.rst

@@ -22,7 +22,6 @@ Color of Axes
 The ``axisbg`` and ``axis_bgcolor`` properties on ``Axes`` have been
 deprecated in favor of ``facecolor``.
 
-
 GTK and GDK backends deprecated
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The GDK and GTK backends have been deprecated. These obsolete backends
@@ -41,6 +40,16 @@ CocoaAgg backend removed
 ~~~~~~~~~~~~~~~~~~~~~~~~
 The deprecated and not fully functional CocoaAgg backend has been removed.
 
+'hold' functionality deprecated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'hold' keyword argument and all functions and methods related
+to it are deprecated, along with the 'axes.hold' `rcParams` entry.
+The behavior will remain consistent with the default ``hold=True``
+state that has long been in place.  Instead of using a function
+or keyword argument (``hold=False``) to change that behavior,
+explicitly clear the axes or figure as needed prior to subsequent
+plotting commands.
+
 
 `Artist.update` has return value
 --------------------------------

lib/matplotlib/__init__.py

@@ -870,8 +870,13 @@ def matplotlib_fname():
     }
 
 _obsolete_set = set(['tk.pythoninspect', 'legend.isaxes'])
+
+# The following may use a value of None to suppress the warning.
+_deprecated_set = set(['axes.hold'])  # do NOT include in _all_deprecated
+
 _all_deprecated = set(chain(_deprecated_ignore_map,
-                            _deprecated_map, _obsolete_set))
+                            _deprecated_map,
+                            _obsolete_set))
 
 
 class RcParams(dict):
@@ -887,6 +892,8 @@ class RcParams(dict):
                     six.iteritems(defaultParams)
                     if key not in _all_deprecated)
     msg_depr = "%s is deprecated and replaced with %s; please use the latter."
+    msg_depr_set = ("%s is deprecated. Please remove it from your "
+                    "matplotlibrc and/or style files.")
     msg_depr_ignore = "%s is deprecated and ignored. Use %s"
     msg_obsolete = ("%s is obsolete. Please remove it from your matplotlibrc "
                     "and/or style files.")
@@ -903,6 +910,8 @@ def __setitem__(self, key, val):
                 warnings.warn(self.msg_depr % (key, alt_key))
                 key = alt_key
                 val = alt_val(val)
+            elif key in _deprecated_set and val is not None:
+                warnings.warn(self.msg_depr_set % key)
             elif key in _deprecated_ignore_map:
                 alt = _deprecated_ignore_map[key]
                 warnings.warn(self.msg_depr_ignore % (key, alt))

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)

lib/matplotlib/axes/_base.py

@@ -540,6 +540,9 @@ def __init__(self, fig, rect,
         self._rasterization_zorder = None
 
         self._hold = rcParams['axes.hold']
+        if self._hold is None:
+            self._hold = True
+
         self._connected = {}  # a dict from events to (id, func)
         self.cla()
         # funcs used to format x and y - fall back on major formatters
@@ -1191,14 +1194,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*.
 

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):

lib/matplotlib/figure.py

@@ -342,6 +342,9 @@ def __init__(self,
         self.patch.set_aa(False)
 
         self._hold = rcParams['axes.hold']
+        if self._hold is None:
+            self._hold = True
+
         self.canvas = None
         self._suptitle = None
 
@@ -569,6 +572,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 +583,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 +1597,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)

lib/matplotlib/mpl-data/stylelib/classic.mplstyle

@@ -174,7 +174,6 @@ mathtext.default : it # The default font to use for math.
 # default face and edge color, default tick sizes,
 # default fontsizes for ticklabels, and so on.  See
 # http://matplotlib.org/api/axes_api.html#module-matplotlib.axes
-axes.hold           : True    # whether to clear the axes by default on
 axes.facecolor      : w       # axes background color
 axes.edgecolor      : k       # axes edge color
 axes.linewidth      : 1.0     # edge linewidth

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