Deprecate cla() methods of Axis and Spines in favor of clear()

timhoffm · timhoffm · commit f13cc9825c82 · 2020-10-12T02:36:58.000+02:00
diff --git a/doc/api/axis_api.rst b/doc/api/axis_api.rst
@@ -40,6 +40,7 @@ Inheritance
    :template: autosummary.rst
    :nosignatures:
 
+   Axis.clear
    Axis.cla
    Axis.get_scale
 
diff --git a/doc/api/next_api_changes/deprecations/18710-TH.rst b/doc/api/next_api_changes/deprecations/18710-TH.rst
@@ -0,0 +1,3 @@
+``Axis.cla()``, ``RadialAxis.cla()``, ``ThetaAxis.cla()`` and ``Spine.cla()``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+These methods are deprecated in favor of the respective ``clear()`` methods.
diff --git a/examples/misc/custom_projection.py b/examples/misc/custom_projection.py
@@ -48,7 +48,7 @@ def _init_axis(self):
         self.xaxis = maxis.XAxis(self)
         self.yaxis = maxis.YAxis(self)
         # Do not register xaxis or yaxis with spines -- as done in
-        # Axes._init_axis() -- until GeoAxes.xaxis.cla() works.
+        # Axes._init_axis() -- until GeoAxes.xaxis.clear() works.
         # self.spines['geo'].register_axis(self.yaxis)
         self._update_transScale()
 
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -1100,11 +1100,11 @@ def cla(self):
         xaxis_visible = self.xaxis.get_visible()
         yaxis_visible = self.yaxis.get_visible()
 
-        self.xaxis.cla()
-        self.yaxis.cla()
+        self.xaxis.clear()
+        self.yaxis.clear()
 
         for name, spine in self.spines.items():
-            spine.cla()
+            spine.clear()
 
         self.ignore_existing_data_limits = True
         self.callbacks = cbook.CallbackRegistry()
diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
@@ -705,7 +705,7 @@ def __init__(self, axes, pickradius=15):
         self._major_tick_kw = dict()
         self._minor_tick_kw = dict()
 
-        self.cla()
+        self.clear()
         self._set_scale('linear')
 
     # During initialization, Axis objects often create ticks that are later
@@ -768,8 +768,19 @@ def get_children(self):
         return [self.label, self.offsetText,
                 *self.get_major_ticks(), *self.get_minor_ticks()]
 
-    def cla(self):
-        """Clear this axis."""
+    def clear(self):
+        """
+        Clear the axis.
+
+        This resets axis properties to their default values:
+
+        - the label
+        - the scale
+        - locators, formatters and ticks
+        - major and minor grid
+        - units
+        - registered callbacks
+        """
 
         self.label.set_text('')  # self.set_label_text would change isDefault_
 
@@ -793,6 +804,11 @@ def cla(self):
         self.set_units(None)
         self.stale = True
 
+    @cbook.deprecated("3.4", alternative="Axis.clear()")
+    def cla(self):
+        """Clear this axis."""
+        return self.clear()
+
     def reset_ticks(self):
         """
         Re-initialize the major and minor Tick lists.
diff --git a/lib/matplotlib/projections/geo.py b/lib/matplotlib/projections/geo.py
@@ -32,7 +32,7 @@ def _init_axis(self):
         self.xaxis = maxis.XAxis(self)
         self.yaxis = maxis.YAxis(self)
         # Do not register xaxis or yaxis with spines -- as done in
-        # Axes._init_axis() -- until GeoAxes.xaxis.cla() works.
+        # Axes._init_axis() -- until GeoAxes.xaxis.clear() works.
         # self.spines['geo'].register_axis(self.yaxis)
         self._update_transScale()
 
diff --git a/lib/matplotlib/projections/polar.py b/lib/matplotlib/projections/polar.py
@@ -378,11 +378,15 @@ def _wrap_locator_formatter(self):
         self.isDefault_majloc = True
         self.isDefault_majfmt = True
 
-    def cla(self):
-        super().cla()
+    def clear(self):
+        super().clear()
         self.set_ticks_position('none')
         self._wrap_locator_formatter()
 
+    @cbook.deprecated("3.4", alternative="ThetaAxis.clear()")
+    def cla(self):
+        self.clear()
+
     def _set_scale(self, value, **kwargs):
         super()._set_scale(value, **kwargs)
         self._wrap_locator_formatter()
@@ -680,11 +684,15 @@ def _wrap_locator_formatter(self):
                                              self.axes))
         self.isDefault_majloc = True
 
-    def cla(self):
-        super().cla()
+    def clear(self):
+        super().clear()
         self.set_ticks_position('none')
         self._wrap_locator_formatter()
 
+    @cbook.deprecated("3.4", alternative="RadialAxis.clear()")
+    def cla(self):
+        self.clear()
+
     def _set_scale(self, value, **kwargs):
         super()._set_scale(value, **kwargs)
         self._wrap_locator_formatter()
@@ -810,7 +818,7 @@ def _init_axis(self):
         # This is moved out of __init__ because non-separable axes don't use it
         self.xaxis = ThetaAxis(self)
         self.yaxis = RadialAxis(self)
-        # Calling polar_axes.xaxis.cla() or polar_axes.xaxis.cla()
+        # Calling polar_axes.xaxis.clear() or polar_axes.xaxis.clear()
         # results in weird artifacts. Therefore we disable this for
         # now.
         # self.spines['polar'].register_axis(self.yaxis)
diff --git a/lib/matplotlib/spines.py b/lib/matplotlib/spines.py
@@ -228,14 +228,18 @@ def register_axis(self, axis):
         """
         self.axis = axis
         if self.axis is not None:
-            self.axis.cla()
+            self.axis.clear()
         self.stale = True
 
-    def cla(self):
+    def clear(self):
         """Clear the current spine."""
         self._position = None  # clear position
         if self.axis is not None:
-            self.axis.cla()
+            self.axis.clear()
+
+    @cbook.deprecated("3.4", alternative="Spine.clear()")
+    def cla(self):
+        self.clear()
 
     def _adjust_location(self):
         """Automatically set spine bounds to the view interval."""
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -1079,7 +1079,7 @@ def cla(self):
         # docstring inherited.
 
         super().cla()
-        self.zaxis.cla()
+        self.zaxis.clear()
 
         if self._sharez is not None:
             self.zaxis.major = self._sharez.zaxis.major

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	+``Axis.cla()``, ``RadialAxis.cla()``, ``ThetaAxis.cla()`` and ``Spine.cla()``
	`2`	`+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~`
	`3`	+These methods are deprecated in favor of the respective ``clear()`` methods.