8000 Backport PR #22735: MNT: prefer Figure.clear() as canonical over Figu… · tacaswell/matplotlib@d4588a3 · GitHub
[go: up one dir, main page]
Skip to content

Commit d4588a3

Browse files
timhoffmtacaswell
timhoffm
authored and
tacaswell
committed
Backport PR matplotlib#22735: MNT: prefer Figure.clear() as canonical over Figure.clf()
Merge pull request matplotlib#22735 from tacaswell/mnt_prefer_clear MNT: prefer Figure.clear() as canonical over Figure.clf() (cherry picked from commit 6fedb48)
1 parent 7d48484 commit d4588a3

File tree

6 files changed

+43
-22
lines changed

6 files changed

+43
-22
lines changed

‎doc/api/prev_api_changes/api_changes_3.0.0.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -471,7 +471,7 @@ Hold machinery
471471
Setting or unsetting ``hold`` (:ref:`deprecated in version 2.0<v200_deprecate_hold>`) has now
472472
been completely removed. Matplotlib now always behaves as if ``hold=True``.
473473
To clear an axes you can manually use :meth:`~.axes.Axes.cla()`,
474-
or to clear an entire figure use :meth:`~.figure.Figure.clf()`.
474+
or to clear an entire figure use :meth:`~.figure.Figure.clear()`.
475475

476476

477477
Removal of deprecated backends

‎doc/users/prev_whats_new/changelog.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3139,7 +3139,7 @@ the `API changes <../../api/api_changes.html>`_.
31393139
Fixed a bug in backend_qt4, reported on mpl-dev - DSD
31403140

31413141
2007-03-26
3142-
Removed colorbar_classic from figure.py; fixed bug in Figure.clf() in which
3142+
Removed colorbar_classic from figure.py; fixed bug in Figure.clear() in which
31433143
_axobservers was not getting cleared. Modernization and cleanups. - EF
31443144

31453145
2007-03-26

‎lib/matplotlib/figure.py

Lines changed: 22 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -935,7 +935,7 @@ def _break_share_link(ax, grouper):
935935
# Break link between any twinned axes
936936
_break_share_link(ax, ax._twinned_axes)
937937

938-
def clf(self, keep_observers=False):
938+
def clear(self, keep_observers=False):
939939
"""
940940
Clear the figure.
941941
@@ -950,7 +950,7 @@ def clf(self, keep_observers=False):
950950

951951
# first clear the axes in any subfigures
952952
for subfig in self.subfigs:
953-
subfig.clf(keep_observers=keep_observers)
953+
subfig.clear(keep_observers=keep_observers)
954954
self.subfigs = []
955955

956956
for ax in tuple(self.axes): # Iterate over the copy.
@@ -971,8 +971,22 @@ def clf(self, keep_observers=False):
971971

972972
self.stale = True
973973

974-
# synonym for `clf`."""
975-
clear = clf
974+
# synonym for `clear`.
975+
def clf(self, keep_observers=False):
976+
"""
977+
Alias for the `clear()` method.
978+
979+
.. admonition:: Discouraged
980+
981+
The use of ``clf()`` is discouraged. Use ``clear()`` instead.
982+
983+
Parameters
984+
----------
985+
keep_observers: bool, default: False
986+
Set *keep_observers* to True if, for example,
987+
a gui widget is tracking the Axes in the figure.
988+
"""
989+
return self.clear(keep_observers=keep_observers)
976990

977991
# Note: in the docstring below, the newlines in the examples after the
978992
# calls to legend() allow replacing it with figlegend() to generate the
@@ -2349,7 +2363,7 @@ def __init__(self,
23492363
self.set_tight_layout(tight_layout)
23502364

23512365
self._axstack = _AxesStack() # track all figure axes and current axes
2352-
self.clf()
2366+
self.clear()
23532367
self._cachedRenderer = None
23542368

23552369
self.set_constrained_layout(constrained_layout)
@@ -2786,10 +2800,10 @@ def set_figheight(self, val, forward=True):
27862800
"""
27872801
self.set_size_inches(self.get_figwidth(), val, forward=forward)
27882802

2789-
def clf(self, keep_observers=False):
2803+
def clear(self, keep_observers=False):
27902804
# docstring inherited
2791-
super().clf(keep_observers=keep_observers)
2792-
# FigureBase.clf does not clear toolbars, as
2805+
super().clear(keep_observers=keep_observers)
2806+
# FigureBase.clear does not clear toolbars, as
27932807
# only Figure can have toolbars
27942808
toolbar = getattr(self.canvas, 'toolbar', None)
27952809
if toolbar is not None:

‎lib/matplotlib/pyplot.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -955,7 +955,7 @@ def close(fig=None):
955955

956956
def clf():
957957
"""Clear the current figure."""
958-
gcf().clf()
958+
gcf().clear()
959959

960960

961961
def draw():

‎lib/matplotlib/tests/test_figure.py

Lines changed: 17 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
from matplotlib._api.deprecation import MatplotlibDeprecationWarning
1616
from matplotlib.testing.decorators import image_comparison, check_figures_equal
1717
from matplotlib.axes import Axes
18-
from matplotlib.figure import Figure
18+
from matplotlib.figure import Figure, FigureBase
1919
from matplotlib.ticker import AutoMinorLocator, FixedFormatter, ScalarFormatter
2020
import matplotlib.pyplot as plt
2121
import matplotlib.dates as mdates
@@ -689,7 +689,8 @@ def test_removed_axis():
689689
fig.canvas.draw()
690690

691691

692-
def test_figure_clear():
692+
@pytest.mark.parametrize('clear_meth', ['clear', 'clf'])
693+
def test_figure_clear(clear_meth):
693694
# we test the following figure clearing scenarios:
694695
fig = plt.figure()
695696

@@ -699,19 +700,19 @@ def test_figure_clear():
699700

700701
# b) a figure with a single unnested axes
701702
ax = fig.add_subplot(111)
702-
fig.clear()
703+
getattr(fig, clear_meth)()
703704
assert fig.axes == []
704705

705706
# c) a figure multiple unnested axes
706707
axes = [fig.add_subplot(2, 1, i+1) for i in range(2)]
707-
fig.clear()
708+
getattr(fig, clear_meth)()
708709
assert fig.axes == []
709710

710711
# d) a figure with a subfigure
711712
gs = fig.add_gridspec(ncols=2, nrows=1)
712713
subfig = fig.add_subfigure(gs[0])
713714
subaxes = subfig.add_subplot(111)
714-
fig.clear()
715+
getattr(fig, clear_meth)()
715716
assert subfig not in fig.subfigs
716717
assert fig.axes == []
717718

@@ -735,15 +736,15 @@ def test_figure_clear():
735736
subaxes = subfig.add_subplot(111)
736737
assert mainaxes in fig.axes
737738
assert subaxes in fig.axes
738-
subfig.clear()
739+
getattr(subfig, clear_meth)()
739740
assert subfig in fig.subfigs
740741
assert subaxes not in subfig.axes
741742
assert subaxes not in fig.axes
742743
assert mainaxes in fig.axes
743744

744745
# e.4) clearing the whole thing
745746
subaxes = subfig.add_subplot(111)
746-
fig.clear()
747+
getattr(fig, clear_meth)()
747748
assert fig.axes == []
748749
assert fig.subfigs == []
749750

@@ -754,22 +755,28 @@ def test_figure_clear():
754755
assert all(sfig in fig.subfigs for sfig in subfigs)
755756

756757
# f.1) clearing only one subfigure
757-
subfigs[0].clear()
758+
getattr(subfigs[0], clear_meth)()
758759
assert subaxes[0] not in fig.axes
759760
assert subaxes[1] in fig.axes
760761
assert subfigs[1] in fig.subfigs
761762

762763
# f.2) clearing the whole thing
763-
subfigs[1].clear()
764+
getattr(subfigs[1], clear_meth)()
764765
subfigs = [fig.add_subfigure(gs[i]) for i in [0, 1]]
765766
subaxes = [sfig.add_subplot(111) for sfig in subfigs]
766767
assert all(ax in fig.axes for ax in subaxes)
767768
assert all(sfig in fig.subfigs for sfig in subfigs)
768-
fig.clear()
769+
getattr(fig, clear_meth)()
769770
assert fig.subfigs == []
770771
assert fig.axes == []
771772

772773

774+
def test_clf_not_refedined():
775+
for klass in FigureBase.__subclasses__():
776+
# check that subclasses do not get redefined in our Figure subclasses
777+
assert 'clf' not in klass.__dict__
778+
779+
773780
@mpl.style.context('mpl20')
774781
def test_picking_does_not_stale():
775782
fig, ax = plt.subplots()

‎lib/matplotlib/tests/test_usetex.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ def test_minus_no_descent(fontsize):
7171
heights = {}
7272
fig = plt.figure()
7373
for vals in [(1,), (-1,), (-1, 1)]:
74-
fig.clf()
74+
fig.clear()
7575
for x in vals:
7676
fig.text(.5, .5, f"${x}$", usetex=True)
7777
fig.canvas.draw()

0 commit comments

Comments
 (0)
0