Merge pull request matplotlib#24577 from anntzer/set_ticklabels

Fold _set_ticklabels into set_ticklabels.

Author: QuLogic

doc/api/next_api_changes/deprecations/24577-AL.rst

@@ -0,0 +1,2 @@
+``ticklabels`` parameter of `.Axis.set_ticklabels` renamed to ``labels``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

lib/matplotlib/axes/_base.py

@@ -3750,7 +3750,7 @@ def set_xlim(self, left=None, right=None, emit=True, auto=False,
     get_xminorticklabels = _axis_method_wrapper("xaxis", "get_minorticklabels")
     get_xticklabels = _axis_method_wrapper("xaxis", "get_ticklabels")
     set_xticklabels = _axis_method_wrapper(
-        "xaxis", "_set_ticklabels",
+        "xaxis", "set_ticklabels",
         doc_sub={"Axis.set_ticks": "Axes.set_xticks"})
 
     def get_ylabel(self):
@@ -3982,7 +3982,7 @@ def set_ylim(self, bottom=None, top=None, emit=True, auto=False,
     get_yminorticklabels = _axis_method_wrapper("yaxis", "get_minorticklabels")
     get_yticklabels = _axis_method_wrapper("yaxis", "get_ticklabels")
     set_yticklabels = _axis_method_wrapper(
-        "yaxis", "_set_ticklabels",
+        "yaxis", "set_ticklabels",
         doc_sub={"Axis.set_ticks": "Axes.set_yticks"})
 
     xaxis_date = _axis_method_wrapper("xaxis", "axis_date")

lib/matplotlib/axis.py

@@ -1918,15 +1918,17 @@ def set_pickradius(self, pickradius):
     def _format_with_dict(tickd, x, pos):
         return tickd.get(x, "")
 
-    def set_ticklabels(self, ticklabels, *, minor=False, **kwargs):
+    @_api.rename_parameter("3.7", "ticklabels", "labels")
+    def set_ticklabels(self, labels, *, minor=False, fontdict=None, **kwargs):
         r"""
-        [*Discouraged*] Set the text values of the tick labels.
+        [*Discouraged*] Set this Axis' tick labels with list of string labels.
 
         .. admonition:: Discouraged
 
-            The use of this method is discouraged, because of the dependency
-            on tick positions. In most cases, you'll want to use
-            ``set_[x/y]ticks(positions, labels)`` instead.
+            The use of this method is discouraged, because of the dependency on
+            tick positions. In most cases, you'll want to use
+            ``Axes.set_[x/y/z]ticks(positions, labels)`` or ``Axis.set_ticks``
+            instead.
 
             If you are using this method, you should always fix the tick
             positions before, e.g. by using `.Axis.set_ticks` or by explicitly
@@ -1935,12 +1937,23 @@ def set_ticklabels(self, ticklabels, *, minor=False, **kwargs):
 
         Parameters
         ----------
-        ticklabels : sequence of str or of `.Text`\s
+        labels : sequence of str or of `.Text`\s
             Texts for labeling each tick location in the sequence set by
             `.Axis.set_ticks`; the number of labels must match the number of
             locations.
+
         minor : bool
             If True, set minor ticks instead of major ticks.
+
+        fontdict : dict, optional
+            A dictionary controlling the appearance of the ticklabels.
+            The default *fontdict* is::
+
+               {'fontsize': rcParams['axes.titlesize'],
+                'fontweight': rcParams['axes.titleweight'],
+                'verticalalignment': 'baseline',
+                'horizontalalignment': loc}
+
         **kwargs
             Text properties.
 
@@ -1951,26 +1964,26 @@ def set_ticklabels(self, ticklabels, *, minor=False, **kwargs):
             ``tick.label2`` if it is visible, in that order.
         """
         try:
-            ticklabels = [t.get_text() if hasattr(t, 'get_text') else t
-                          for t in ticklabels]
+            labels = [t.get_text() if hasattr(t, 'get_text') else t
+                      for t in labels]
         except TypeError:
-            raise TypeError(f"{ticklabels:=} must be a sequence") from None
+            raise TypeError(f"{labels:=} must be a sequence") from None
         locator = (self.get_minor_locator() if minor
                    else self.get_major_locator())
         if isinstance(locator, mticker.FixedLocator):
-            # Passing [] as a list of ticklabels is often used as a way to
-            # remove all tick labels, so only error for > 0 ticklabels
-            if len(locator.locs) != len(ticklabels) and len(ticklabels) != 0:
+            # Passing [] as a list of labels is often used as a way to
+            # remove all tick labels, so only error for > 0 labels
+            if len(locator.locs) != len(labels) and len(labels) != 0:
                 raise ValueError(
                     "The number of FixedLocator locations"
                     f" ({len(locator.locs)}), usually from a call to"
                     " set_ticks, does not match"
-                    f" the number of ticklabels ({len(ticklabels)}).")
-            tickd = {loc: lab for loc, lab in zip(locator.locs, ticklabels)}
+                    f" the number of labels ({len(labels)}).")
+            tickd = {loc: lab for loc, lab in zip(locator.locs, labels)}
             func = functools.partial(self._format_with_dict, tickd)
             formatter = mticker.FuncFormatter(func)
         else:
-            formatter = mticker.FixedFormatter(ticklabels)
+            formatter = mticker.FixedFormatter(labels)
 
         if minor:
             self.set_minor_formatter(formatter)
@@ -1982,6 +1995,8 @@ def set_ticklabels(self, ticklabels, *, minor=False, **kwargs):
             ticks = self.get_major_ticks(len(locs))
 
         ret = []
+        if fontdict is not None:
+            kwargs.update(fontdict)
         for pos, (loc, tick) in enumerate(zip(locs, ticks)):
             tick.update_position(loc)
             tick_label = formatter(loc, pos)
@@ -2000,47 +2015,6 @@ def set_ticklabels(self, ticklabels, *, minor=False, **kwargs):
         self.stale = True
         return ret
 
-    # Wrapper around set_ticklabels used to generate Axes.set_x/ytickabels; can
-    # go away once the API of Axes.set_x/yticklabels becomes consistent.
-    def _set_ticklabels(self, labels, *, fontdict=None, minor=False, **kwargs):
-        """
-        Set this Axis' labels with list of string labels.
-
-        .. warning::
-            This method should only be used after fixing the tick positions
-            using `.Axis.set_ticks`. Otherwise, the labels may end up in
-            unexpected positions.
-
-        Parameters
-        ----------
-        labels : list of str
-            The label texts.
-
-        fontdict : dict, optional
-            A dictionary controlling the appearance of the ticklabels.
-            The default *fontdict* is::
-
-               {'fontsize': rcParams['axes.titlesize'],
-                'fontweight': rcParams['axes.titleweight'],
-                'verticalalignment': 'baseline',
-                'horizontalalignment': loc}
-
-        minor : bool, default: False
-            Whether to set the minor ticklabels rather than the major ones.
-
-        Returns
-        -------
-        list of `.Text`
-            The labels.
-
-        Other Parameters
-        ----------------
-        **kwargs : `~.text.Text` properties.
-        """
-        if fontdict is not None:
-            kwargs.update(fontdict)
-        return self.set_ticklabels(labels, minor=minor, **kwargs)
-
     def _set_tick_locations(self, ticks, *, minor=False):
         # see docstring of set_ticks
 

lib/mpl_toolkits/mplot3d/axes3d.py

@@ -748,7 +748,7 @@ def get_zlim(self):
     get_zminorticklabels = _axis_method_wrapper("zaxis", "get_minorticklabels")
     get_zticklabels = _axis_method_wrapper("zaxis", "get_ticklabels")
     set_zticklabels = _axis_method_wrapper(
-        "zaxis", "_set_ticklabels",
+        "zaxis", "set_ticklabels",
         doc_sub={"Axis.set_ticks": "Axes3D.set_zticks"})
 
     zaxis_date = _axis_method_wrapper("zaxis", "axis_date")