Skip to content

Commit 8251436

Browse files
tacaswelltacaswell
authored
Merge pull request #7516 from efiring/kill_hold_stage2
API: Deprecate "hold" kwarg and machinery.
2 parents 5546552 + 0cc0f57 commit 8251436

File tree

15 files changed

+537
-273
lines changed

15 files changed

+537
-273
lines changed

‎boilerplate.py

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -50,15 +50,19 @@
5050
@_autogen_docstring(Axes.%(func)s)
5151
def %(func)s(%(argspec)s):
5252
%(ax)s = gca()
53-
# allow callers to override the hold state by passing hold=True|False
54-
%(washold)s = %(ax)s.ishold()
53+
# Deprecated: allow callers to override the hold state
54+
# by passing hold=True|False
55+
%(washold)s = %(ax)s._hold
5556
%(sethold)s
5657
if hold is not None:
57-
%(ax)s.hold(hold)
58+
%(ax)s._hold = hold
59+
from matplotlib.cbook import mplDeprecation
60+
warnings.warn("The 'hold' keyword argument is deprecated since 2.0.",
61+
mplDeprecation)
5862
try:
5963
%(ret)s = %(ax)s.%(func)s(%(call)s)
6064
finally:
61-
%(ax)s.hold(%(washold)s)
65+
%(ax)s._hold = %(washold)s
6266
%(mappable)s
6367
return %(ret)s
6468
"""

‎doc/api/api_changes.rst

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,6 @@ Color of Axes
2222
The ``axisbg`` and ``axis_bgcolor`` properties on ``Axes`` have been
2323
deprecated in favor of ``facecolor``.
2424

25-
2625
GTK and GDK backends deprecated
2726
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2827
The GDK and GTK backends have been deprecated. These obsolete backends
@@ -41,6 +40,16 @@ CocoaAgg backend removed
4140
~~~~~~~~~~~~~~~~~~~~~~~~
4241
The deprecated and not fully functional CocoaAgg backend has been removed.
4342

43+
'hold' functionality deprecated
44+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
45+
The 'hold' keyword argument and all functions and methods related
46+
to it are deprecated, along with the 'axes.hold' `rcParams` entry.
47+
The behavior will remain consistent with the default ``hold=True``
48+
state that has long been in place. Instead of using a function
49+
or keyword argument (``hold=False``) to change that behavior,
50+
explicitly clear the axes or figure as needed prior to subsequent
51+
plotting commands.
52+
4453

4554
`Artist.update` has return value
4655
--------------------------------

‎lib/matplotlib/__init__.py

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -870,8 +870,13 @@ def matplotlib_fname():
870870
}
871871

872872
_obsolete_set = set(['tk.pythoninspect', 'legend.isaxes'])
873+
874+
# The following may use a value of None to suppress the warning.
875+
_deprecated_set = set(['axes.hold']) # do NOT include in _all_deprecated
876+
873877
_all_deprecated = set(chain(_deprecated_ignore_map,
874-
_deprecated_map, _obsolete_set))
878+
_deprecated_map,
879+
_obsolete_set))
875880

876881

877882
class RcParams(dict):
@@ -887,6 +892,8 @@ class RcParams(dict):
887892
six.iteritems(defaultParams)
888893
if key not in _all_deprecated)
889894
msg_depr = "%s is deprecated and replaced with %s; please use the latter."
895+
msg_depr_set = ("%s is deprecated. Please remove it from your "
896+
"matplotlibrc and/or style files.")
890897
msg_depr_ignore = "%s is deprecated and ignored. Use %s"
891898
msg_obsolete = ("%s is obsolete. Please remove it from your matplotlibrc "
892899
"and/or style files.")
@@ -903,6 +910,8 @@ def __setitem__(self, key, val):
903910
warnings.warn(self.msg_depr % (key, alt_key))
904911
key = alt_key
905912
val = alt_val(val)
913+
elif key in _deprecated_set and val is not None:
914+
warnings.warn(self.msg_depr_set % key)
906915
elif key in _deprecated_ignore_map:
907916
alt = _deprecated_ignore_map[key]
908917
warnings.warn(self.msg_depr_ignore % (key, alt))

‎lib/matplotlib/axes/_axes.py

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1665,7 +1665,7 @@ def acorr(self, x, **kwargs):
16651665
16661666
x : sequence of scalar
16671667
1668-
hold : boolean, optional, default: True
1668+
hold : boolean, optional, *deprecated*, default: True
16691669
16701670
detrend : callable, optional, default: `mlab.detrend_none`
16711671
x is detrended by the `detrend` callable. Default is no
@@ -1713,6 +1713,8 @@ def acorr(self, x, **kwargs):
17131713
.. plot:: mpl_examples/pylab_examples/xcorr_demo.py
17141714
17151715
"""
1716+
if "hold" in kwargs:
1717+
warnings.warn("the 'hold' kwarg is deprecated", mplDeprecation)
17161718
return self.xcorr(x, x, **kwargs)
17171719

17181720
@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,
17301732
17311733
y : sequence of scalars of length n
17321734
1733-
hold : boolean, optional, default: True
1735+
hold : boolean, optional, *deprecated*, default: True
17341736
17351737
detrend : callable, optional, default: `mlab.detrend_none`
17361738
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,
17691771
The cross correlation is performed with :func:`numpy.correlate` with
17701772
`mode` = 2.
17711773
"""
1774+
if "hold" in kwargs:
1775+
warnings.warn("the 'hold' kwarg is deprecated", mplDeprecation)
17721776

17731777
Nx = len(x)
17741778
if Nx != len(y):
@@ -2136,7 +2140,7 @@ def make_iterable(x):
21362140
patches.append(r)
21372141

21382142
holdstate = self._hold
2139-
self.hold(True) # ensure hold is on before plotting errorbars
2143+
self._hold = True # ensure hold is on before plotting errorbars
21402144

21412145
if xerr is not None or yerr is not None:
21422146
if orientation == 'vertical':
@@ -2158,7 +2162,7 @@ def make_iterable(x):
21582162
else:
21592163
errorbar = None
21602164

2161-
self.hold(holdstate) # restore previous hold state
2165+
self._hold = holdstate # restore previous hold state
21622166

21632167
if adjust_xlim:
21642168
xmin, xmax = self.dataLim.intervalx
@@ -2380,7 +2384,7 @@ def stem(self, *args, **kwargs):
23802384
remember_hold = self._hold
23812385
if not self._hold:
23822386
self.cla()
2383-
self.hold(True)
2387+
self._hold = True
23842388

23852389
# Assume there's at least one data array
23862390
y = np.asarray(args[0])
@@ -2464,7 +2468,7 @@ def stem(self, *args, **kwargs):
24642468
color=basecolor, linestyle=basestyle,
24652469
marker=basemarker, label="_nolegend_")
24662470

2467-
self.hold(remember_hold)
2471+
self._hold = remember_hold
24682472

24692473
stem_container = StemContainer((markerline, stemlines, baseline),
24702474
label=label)
@@ -3786,7 +3790,7 @@ def dopatch(xs, ys, **kwargs):
37863790
setlabels(datalabels)
37873791

37883792
# reset hold status
3789-
self.hold(holdStatus)
3793+
self._hold = holdStatus
37903794

37913795
return dict(whiskers=whiskers, caps=caps, boxes=boxes,
37923796
medians=medians, fliers=fliers, means=means)

‎lib/matplotlib/axes/_base.py

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -540,6 +540,9 @@ def __init__(self, fig, rect,
540540
self._rasterization_zorder = None
541541

542542
self._hold = rcParams['axes.hold']
543+
if self._hold is None:
544+
self._hold = True
545+
543546
self._connected = {} # a dict from events to (id, func)
544547
self.cla()
545548
# funcs used to format x and y - fall back on major formatters
@@ -1191,14 +1194,25 @@ def set_color_cycle(self, clist):
11911194
else:
11921195
self.set_prop_cycle('color', clist)
11931196

1197+
@cbook.deprecated("2.0")
11941198
def ishold(self):
1195-
"""return the HOLD status of the axes"""
1199+
"""return the HOLD status of the axes
1200+
1201+
The `hold` mechanism is deprecated and will be removed in
1202+
v3.0.
1203+
"""
1204+
11961205
return self._hold
11971206

1207+
@cbook.deprecated("2.0")
11981208
def hold(self, b=None):
11991209
"""
12001210
Set the hold state
12011211
1212+
The ``hold`` mechanism is deprecated and will be removed in
1213+
v3.0. The behavior will remain consistent with the
1214+
long-time default value of True.
1215+
12021216
If *hold* is *None* (default), toggle the *hold* state. Else
12031217
set the *hold* state to boolean value *b*.
12041218

‎lib/matplotlib/colorbar.py

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -501,10 +501,10 @@ def _add_solids(self, X, Y, C):
501501
# Save, set, and restore hold state to keep pcolor from
502502
# clearing the axes. Ordinarily this will not be needed,
503503
# since the axes object should already have hold set.
504-
_hold = self.ax.ishold()
505-
self.ax.hold(True)
504+
_hold = self.ax._hold
505+
self.ax._hold = True
506506
col = self.ax.pcolormesh(*args, **kw)
507-
self.ax.hold(_hold)
507+
self.ax._hold = _hold
508508
#self.add_observer(col) # We should observe, not be observed...
509509

510510
if self.solids is not None:
@@ -1262,8 +1262,8 @@ def _add_solids(self, X, Y, C):
12621262
# Save, set, and restore hold state to keep pcolor from
12631263
# clearing the axes. Ordinarily this will not be needed,
12641264
# since the axes object should already have hold set.
1265-
_hold = self.ax.ishold()
1266-
self.ax.hold(True)
1265+
_hold = self.ax._hold
1266+
self.ax._hold = True
12671267

12681268
kw = {'alpha': self.alpha, }
12691269

@@ -1309,7 +1309,7 @@ def _add_solids(self, X, Y, C):
13091309
linewidths=(0.5 * mpl.rcParams['axes.linewidth'],))
13101310
self.ax.add_collection(self.dividers)
13111311

1312-
self.ax.hold(_hold)
1312+
self.ax._hold = _hold
13131313

13141314

13151315
def colorbar_factory(cax, mappable, **kwargs):

‎lib/matplotlib/figure.py

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -342,6 +342,9 @@ def __init__(self,
342342
self.patch.set_aa(False)
343343

344344
self._hold = rcParams['axes.hold']
345+
if self._hold is None:
346+
self._hold = True
347+
345348
self.canvas = None
346349
self._suptitle = None
347350

@@ -569,6 +572,7 @@ def set_canvas(self, canvas):
569572
"""
570573
self.canvas = canvas
571574

575+
@cbook.deprecated("2.0")
572576
def hold(self, b=None):
573577
"""
574578
Set the hold state. If hold is None (default), toggle the
@@ -579,6 +583,8 @@ def hold(self, b=None):
579583
hold() # toggle hold
580584
hold(True) # hold is on
581585
hold(False) # hold is off
586+
587+
All "hold" machinery is deprecated.
582588
"""
583589
if b is None:
584590
self._hold = not self._hold
@@ -1591,7 +1597,7 @@ def colorbar(self, mappable, cax=None, ax=None, use_gridspec=True, **kw):
15911597
cax, kw = cbar.make_axes_gridspec(ax, **kw)
15921598
else:
15931599
cax, kw = cbar.make_axes(ax, **kw)
1594-
cax.hold(True)
1600+
cax._hold = True
15951601
cb = cbar.colorbar_factory(cax, mappable, **kw)
15961602

15971603
self.sca(current_ax)

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

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -174,7 +174,6 @@ mathtext.default : it # The default font to use for math.
174174
# default face and edge color, default tick sizes,
175175
# default fontsizes for ticklabels, and so on. See
176176
# http://matplotlib.org/api/axes_api.html#module-matplotlib.axes
177-
axes.hold : True # whether to clear the axes by default on
178177
axes.facecolor : w # axes background color
179178
axes.edgecolor : k # axes edge color
180179
axes.linewidth : 1.0 # edge linewidth

‎lib/matplotlib/pylab.py

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,14 +49,12 @@
4949
getp - get a graphics property
5050
grid - set whether gridding is on
5151
hist - make a histogram
52-
hold - set the axes hold state
5352
ioff - turn interaction mode off
5453
ion - turn interaction mode on
5554
isinteractive - return True if interaction mode is on
5655
imread - load image file into array
5756
imsave - save array as an image file
5857
imshow - plot image data
59-
ishold - return the hold state of the current axes
6058
legend - make an axes legend
6159
locator_params - adjust parameters used in locating axis ticks
6260
loglog - a log log plot

0 commit comments

Comments
 (0)