MNT: prefer "clear" as canonical over clf

Author: tacaswell

lib/matplotlib/figure.py

@@ -913,7 +913,7 @@ def _break_share_link(ax, grouper):
         # Break link between any twinned axes
         _break_share_link(ax, ax._twinned_axes)
 
-    def clf(self, keep_observers=False):
+    def clear(self, keep_observers=False):
         """
         Clear the figure.
 
@@ -928,7 +928,7 @@ def clf(self, keep_observers=False):
 
         # first clear the axes in any subfigures
         for subfig in self.subfigs:
-            subfig.clf(keep_observers=keep_observers)
+            subfig.clear(keep_observers=keep_observers)
         self.subfigs = []
 
         for ax in tuple(self.axes):  # Iterate over the copy.
@@ -949,13 +949,22 @@ def clf(self, keep_observers=False):
 
         self.stale = True
 
-    # synonym for `clf`."""
-    clear = clf
+    # synonym for `clear`.
+    def clf(self, keep_observers=False):
+        """
+        Alias for the `clear()` method.
+
+        Parameters
+        ----------
+        keep_observers: bool, default: False
+            Set *keep_observers* to True if, for example,
+            a gui widget is tracking the Axes in the figure.
+        """
+        return self.clear(keep_observers=keep_observers)
 
     # Note: in the docstring below, the newlines in the examples after the
     # calls to legend() allow replacing it with figlegend() to generate the
     # docstring of pyplot.figlegend.
-
     @_docstring.dedent_interpd
     def legend(self, *args, **kwargs):
         """
@@ -2340,7 +2349,7 @@ def __init__(self,
         self.subplotpars = subplotpars
 
         self._axstack = _AxesStack()  # track all figure axes and current axes
-        self.clf()
+        self.clear()
         self._cachedRenderer = None
 
         # list of child gridspecs for this figure
@@ -2839,10 +2848,10 @@ def set_figheight(self, val, forward=True):
         """
         self.set_size_inches(self.get_figwidth(), val, forward=forward)
 
-    def clf(self, keep_observers=False):
+    def clear(self, keep_observers=False):
         # docstring inherited
-        super().clf(keep_observers=keep_observers)
-        # FigureBase.clf does not clear toolbars, as
+        super().clear(keep_observers=keep_observers)
+        # FigureBase.clear does not clear toolbars, as
         # only Figure can have toolbars
         toolbar = self.canvas.toolbar
         if toolbar is not None:

lib/matplotlib/tests/test_figure.py

@@ -16,7 +16,7 @@
 from matplotlib._api.deprecation import MatplotlibDeprecationWarning
 from matplotlib.testing.decorators import image_comparison, check_figures_equal
 from matplotlib.axes import Axes
-from matplotlib.figure import Figure
+from matplotlib.figure import Figure, FigureBase
 from matplotlib.layout_engine import (ConstrainedLayoutEngine,
                                       TightLayoutEngine)
 from matplotlib.ticker import AutoMinorLocator, FixedFormatter, ScalarFormatter
@@ -709,7 +709,8 @@ def test_removed_axis():
     fig.canvas.draw()
 
 
-def test_figure_clear():
+@pytest.mark.parametrize('clear_meth', ['clear', 'clf'])
+def test_figure_clear(clear_meth):
     # we test the following figure clearing scenarios:
     fig = plt.figure()
 
@@ -719,19 +720,19 @@ def test_figure_clear():
 
     # b) a figure with a single unnested axes
     ax = fig.add_subplot(111)
-    fig.clear()
+    getattr(fig, clear_meth)()
     assert fig.axes == []
 
     # c) a figure multiple unnested axes
     axes = [fig.add_subplot(2, 1, i+1) for i in range(2)]
-    fig.clear()
+    getattr(fig, clear_meth)()
     assert fig.axes == []
 
     # d) a figure with a subfigure
     gs = fig.add_gridspec(ncols=2, nrows=1)
     subfig = fig.add_subfigure(gs[0])
     subaxes = subfig.add_subplot(111)
-    fig.clear()
+    getattr(fig, clear_meth)()
     assert subfig not in fig.subfigs
     assert fig.axes == []
 
@@ -755,15 +756,15 @@ def test_figure_clear():
     subaxes = subfig.add_subplot(111)
     assert mainaxes in fig.axes
     assert subaxes in fig.axes
-    subfig.clear()
+    getattr(subfig, clear_meth)()
     assert subfig in fig.subfigs
     assert subaxes not in subfig.axes
     assert subaxes not in fig.axes
     assert mainaxes in fig.axes
 
     # e.4) clearing the whole thing
     subaxes = subfig.add_subplot(111)
-    fig.clear()
+    getattr(fig, clear_meth)()
     assert fig.axes == []
     assert fig.subfigs == []
 
@@ -774,22 +775,28 @@ def test_figure_clear():
     assert all(sfig in fig.subfigs for sfig in subfigs)
 
     # f.1) clearing only one subfigure
-    subfigs[0].clear()
+    getattr(subfigs[0], clear_meth)()
     assert subaxes[0] not in fig.axes
     assert subaxes[1] in fig.axes
     assert subfigs[1] in fig.subfigs
 
     # f.2) clearing the whole thing
-    subfigs[1].clear()
+    getattr(subfigs[1], clear_meth)()
     subfigs = [fig.add_subfigure(gs[i]) for i in [0, 1]]
     subaxes = [sfig.add_subplot(111) for sfig in subfigs]
     assert all(ax in fig.axes for ax in subaxes)
     assert all(sfig in fig.subfigs for sfig in subfigs)
-    fig.clear()
+    getattr(fig, clear_meth)()
     assert fig.subfigs == []
     assert fig.axes == []
 
 
+def test_clf_not_refedined():
+    for klass in FigureBase.__subclasses__():
+        # check that subclasses do not get redefined in our Figure subclasses
+        assert 'clf' not in klass.__dict__
+
+
 @mpl.style.context('mpl20')
 def test_picking_does_not_stale():
     fig, ax = plt.subplots()