8000 Merge pull request #22735 from tacaswell/mnt_prefer_clear · tacaswell/matplotlib@6fedb48 · GitHub
[go: up one dir, main page]
Skip to content

Commit 6fedb48

Browse files
timhoffmtimhoffm
authored
Merge pull request matplotlib#22735 from tacaswell/mnt_prefer_clear
MNT: prefer Figure.clear() as canonical over Figure.clf()
2 parents c603cc6 + 3587b8b commit 6fedb48

File tree

6 files changed

+43
-23
lines changed

6 files changed

+43
-23
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 & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -913,7 +913,7 @@ def _break_share_link(ax, grouper):
913913
# Break link between any twinned axes
914914
_break_share_link(ax, ax._twinned_axes)
915915

916-
def clf(self, keep_observers=False):
916+
def clear(self, keep_observers=False):
917917
"""
918918
Clear the figure.
919919
@@ -928,7 +928,7 @@ def clf(self, keep_observers=False):
928928

929929
# first clear the axes in any subfigures
930930
for subfig in self.subfigs:
931-
subfig.clf(keep_observers=keep_observers)
931+
subfig.clear(keep_observers=keep_observers)
932932
self.subfigs = []
933933

934934
for ax in tuple(self.axes): # Iterate over the copy.
@@ -949,13 +949,26 @@ def clf(self, keep_observers=False):
949949

950950
self.stale = True
951951

952-
# synonym for `clf`."""
953-
clear = clf
952+
# synonym for `clear`.
953+
def clf(self, keep_observers=False):
954+
"""
955+
Alias for the `clear()` method.
956+
957+
.. admonition:: Discouraged
958+
959+
The use of ``clf()`` is discouraged. Use ``clear()`` instead.
960+
961+
Parameters
962+
----------
963+
keep_observers: bool, default: False
964+
Set *keep_observers* to True if, for example,
965+
a gui widget is tracking the Axes in the figure.
966+
"""
967+
return self.clear(keep_observers=keep_observers)
954968

955969
# Note: in the docstring below, the newlines in the examples after the
956970
# calls to legend() allow replacing it with figlegend() to generate the
957971
# docstring of pyplot.figlegend.
958-
959972
@_docstring.dedent_interpd
960973
def legend(self, *args, **kwargs):
961974
"""
@@ -2340,7 +2353,7 @@ def __init__(self,
23402353
self.subplotpars = subplotpars
23412354

23422355
self._axstack = _AxesStack() # track all figure axes and current axes
2343-
self.clf()
2356+
self.clear()
23442357
self._cachedRenderer = None
23452358

23462359
# list of child gridspecs for this figure
@@ -2839,10 +2852,10 @@ def set_figheight(self, val, forward=True):
28392852
"""
28402853
self.set_size_inches(self.get_figwidth(), val, forward=forward)
28412854

2842-
def clf(self, keep_observers=False):
2855+
def clear(self, keep_observers=False):
28432856
# docstring inherited
2844-
super().clf(keep_observers=keep_observers)
2845-
# FigureBase.clf does not clear toolbars, as
2857+
super().clear(keep_observers=keep_observers)
2858+
# FigureBase.clear does not clear toolbars, as
28462859
# only Figure can have toolbars
28472860
toolbar = self.canvas.toolbar
28482861
if toolbar is not None:

‎lib/matplotlib/pyplot.py

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

954954
def clf():
955955
"""Clear the current figure."""
956-
gcf().clf()
956+
gcf().clear()
957957

958958

959959
def draw():

‎lib/matplotlib/tests/test_figure.py

Lines changed: 17 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
from matplotlib._api.deprecation import MatplotlibDeprecationWarning
1717
from matplotlib.testing.decorators import image_comparison, check_figures_equal
1818
from matplotlib.axes import Axes
19-
from matplotlib.figure import Figure
19+
from matplotlib.figure import Figure, FigureBase
2020
from matplotlib.layout_engine import (ConstrainedLayoutEngine,
2121
TightLayoutEngine)
2222
from matplotlib.ticker import AutoMinorLocator, FixedFormatter, ScalarFormatter
@@ -709,7 +709,8 @@ def test_removed_axis():
709709
fig.canvas.draw()
710710

711711

712-
def test_figure_clear():
712+
@pytest.mark.parametrize('clear_meth', ['clear', 'clf'])
713+
def test_figure_clear(clear_meth):
713714
# we test the following figure clearing scenarios:
714715
fig = plt.figure()
715716

@@ -719,19 +720,19 @@ def test_figure_clear():
719720

720721
# b) a figure with a single unnested axes
721722
ax = fig.add_subplot(111)
722-
fig.clear()
723+
getattr(fig, clear_meth)()
723724
assert fig.axes == []
724725

725726
# c) a figure multiple unnested axes
726727
axes = [fig.add_subplot(2, 1, i+1) for i in range(2)]
727-
fig.clear()
728+
getattr(fig, clear_meth)()
728729
assert fig.axes == []
729730

730731
# d) a figure with a subfigure
731732
gs = fig.add_gridspec(ncols=2, nrows=1)
732733
subfig = fig.add_subfigure(gs[0])
733734
subaxes = subfig.add_subplot(111)
734-
fig.clear()
735+
getattr(fig, clear_meth)()
735736
assert subfig not in fig.subfigs
736737
assert fig.axes == []
737738

@@ -755,15 +756,15 @@ def test_figure_clear():
755756
subaxes = subfig.add_subplot(111)
756757
assert mainaxes in fig.axes
757758
assert subaxes in fig.axes
758-
subfig.clear()
759+
getattr(subfig, clear_meth)()
759760
assert subfig in fig.subfigs
760761
assert subaxes not in subfig.axes
761762
assert subaxes not in fig.axes
762763
assert mainaxes in fig.axes
763764

764765
# e.4) clearing the whole thing
765766
subaxes = subfig.add_subplot(111)
766-
fig.clear()
767+
getattr(fig, clear_meth)()
767768
assert fig.axes == []
768769
assert fig.subfigs == []
769770

@@ -774,22 +775,28 @@ def test_figure_clear():
774775
assert all(sfig in fig.subfigs for sfig in subfigs)
775776

776777
# f.1) clearing only one subfigure
777-
subfigs[0].clear()
778+
getattr(subfigs[0], clear_meth)()
778779
assert subaxes[0] not in fig.axes
779780
assert subaxes[1] in fig.axes
780781
assert subfigs[1] in fig.subfigs
781782

782783
# f.2) clearing the whole thing
783-
subfigs[1].clear()
784+
getattr(subfigs[1], clear_meth)()
784785
subfigs = [fig.add_subfigure(gs[i]) for i in [0, 1]]
785786
subaxes = [sfig.add_subplot(111) for sfig in subfigs]
786787
assert all(ax in fig.axes for ax in subaxes)
787788
assert all(sfig in fig.subfigs for sfig in subfigs)
788-
fig.clear()
789+
getattr(fig, clear_meth)()
789790
assert fig.subfigs == []
790791
assert fig.axes == []
791792

792793

794+
def test_clf_not_refedined():
795+
for klass in FigureBase.__subclasses__():
796+
# check that subclasses do not get redefined in our Figure subclasses
797+
assert 'clf' not in klass.__dict__
798+
799+
793800
@mpl.style.context('mpl20')
794801
def test_picking_does_not_stale():
795802
fig, ax = plt.subplots()

‎lib/matplotlib/tests/test_usetex.py

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

0 commit comments

Comments
 (0)
0