diff --git a/doc/api/next_api_changes/deprecations/24577-AL.rst b/doc/api/next_api_changes/deprecations/24577-AL.rst new file mode 100644 index 000000000000..68c80a4310ef --- /dev/null +++ b/doc/api/next_api_changes/deprecations/24577-AL.rst @@ -0,0 +1,2 @@ +``ticklabels`` parameter of `.Axis.set_ticklabels` renamed to ``labels`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py index 3e665cda4270..574310ea763a 100644 --- a/lib/matplotlib/axes/_base.py +++ b/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") diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py index 9597d0b1ec2c..fff753704cea 100644 --- a/lib/matplotlib/axis.py +++ b/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 diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py index 5baf77ba1112..a5734632d44c 100644 --- a/lib/mpl_toolkits/mplot3d/axes3d.py +++ b/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")