From d7ee951c5dd3f9b32b190d2e6479435a4c301757 Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Tue, 5 Nov 2024 11:46:42 +0100 Subject: [PATCH] Add "standard" Axes wrapper getters/setters for Axis invertedness. Currently, toggling an axis invertedness requires either using the Axes method `ax.invert_xaxis()` (whose effect depends on whether it has already been called before) or going through the axis method `ax.xaxis.set_inverted()`; likewise, querying invertedness state requires either using the `ax.xaxis_inverted()` method, which has slightly nonstandard naming, or going through the axis method `ax.xaxis.get_inverted()`. For practicality, provide getters and setters with standard names: `ax.get_xinverted()`/`ax.set_xinverted()` (and likewise for y/z). In particular, the "standard" setter can be used with the multi-setter Artist.set(), or directly when creating the axes (`add_subplot(xinverted=True)`). --- doc/api/axes_api.rst | 4 +++ doc/api/toolkits/mplot3d/axes3d.rst | 6 ++++ doc/users/next_whats_new/axis_inversion.rst | 9 ++++++ lib/matplotlib/axes/_base.py | 35 +++++++++++++++++++-- lib/matplotlib/axes/_base.pyi | 4 +++ lib/mpl_toolkits/mplot3d/axes3d.py | 17 +++++++++- 6 files changed, 72 insertions(+), 3 deletions(-) create mode 100644 doc/users/next_whats_new/axis_inversion.rst diff --git a/doc/api/axes_api.rst b/doc/api/axes_api.rst index 6afdad4e768e..f389226d907a 100644 --- a/doc/api/axes_api.rst +++ b/doc/api/axes_api.rst @@ -285,8 +285,12 @@ Axis limits and direction :template: autosummary.rst :nosignatures: + Axes.set_xinverted + Axes.get_xinverted Axes.invert_xaxis Axes.xaxis_inverted + Axes.set_yinverted + Axes.get_yinverted Axes.invert_yaxis Axes.yaxis_inverted diff --git a/doc/api/toolkits/mplot3d/axes3d.rst b/doc/api/toolkits/mplot3d/axes3d.rst index 83cd8dd63cef..612b3dd82a4b 100644 --- a/doc/api/toolkits/mplot3d/axes3d.rst +++ b/doc/api/toolkits/mplot3d/axes3d.rst @@ -99,10 +99,16 @@ Axis limits and direction get_zlim set_zlim get_w_lims + get_xinverted + set_xinverted invert_xaxis xaxis_inverted + get_yinverted + set_yinverted invert_yaxis yaxis_inverted + get_zinverted + set_zinverted invert_zaxis zaxis_inverted get_xbound diff --git a/doc/users/next_whats_new/axis_inversion.rst b/doc/users/next_whats_new/axis_inversion.rst new file mode 100644 index 000000000000..8d0e161b9ab2 --- /dev/null +++ b/doc/users/next_whats_new/axis_inversion.rst @@ -0,0 +1,9 @@ +Standard getters/setters for axis inversion state +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Whether an axis is inverted can now be queried and set using the `.axes.Axes` +getters `~.Axes.get_xinverted`/`~.Axes.get_yinverted` and setters +`~.Axes.set_xinverted`/`~.Axes.set_yinverted`. + +The previously existing methods (`.Axes.xaxis_inverted`, `.Axes.invert_xaxis`) +are now discouraged (but not deprecated) due to their non-standard naming and +behavior. diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py index 4c5b18e9e843..bcf072caef80 100644 --- a/lib/matplotlib/axes/_base.py +++ b/lib/matplotlib/axes/_base.py @@ -6,6 +6,7 @@ from numbers import Real from operator import attrgetter import re +import textwrap import types import numpy as np @@ -3603,15 +3604,30 @@ def invert_xaxis(self): """ Invert the x-axis. + .. admonition:: Discouraged + + The use of this method is discouraged. + Use `.Axes.set_xinverted` instead. + See Also -------- - xaxis_inverted + get_xinverted get_xlim, set_xlim get_xbound, set_xbound """ self.xaxis.set_inverted(not self.xaxis.get_inverted()) + set_xinverted = _axis_method_wrapper("xaxis", "set_inverted") + get_xinverted = _axis_method_wrapper("xaxis", "get_inverted") xaxis_inverted = _axis_method_wrapper("xaxis", "get_inverted") + if xaxis_inverted.__doc__: + xaxis_inverted.__doc__ += textwrap.dedent(""" + + .. admonition:: Discouraged + + The use of this method is discouraged. + Use `.Axes.get_xinverted` instead. + """) def get_xbound(self): """ @@ -3856,15 +3872,30 @@ def invert_yaxis(self): """ Invert the y-axis. + .. admonition:: Discouraged + + The use of this method is discouraged. + Use `.Axes.set_yinverted` instead. + See Also -------- - yaxis_inverted + get_yinverted get_ylim, set_ylim get_ybound, set_ybound """ self.yaxis.set_inverted(not self.yaxis.get_inverted()) + set_yinverted = _axis_method_wrapper("yaxis", "set_inverted") + get_yinverted = _axis_method_wrapper("yaxis", "get_inverted") yaxis_inverted = _axis_method_wrapper("yaxis", "get_inverted") + if yaxis_inverted.__doc__: + yaxis_inverted.__doc__ += textwrap.dedent(""" + + .. admonition:: Discouraged + + The use of this method is discouraged. + Use `.Axes.get_yinverted` instead. + """) def get_ybound(self): """ diff --git a/lib/matplotlib/axes/_base.pyi b/lib/matplotlib/axes/_base.pyi index ee3c7cf0dee9..b4926f113564 100644 --- a/lib/matplotlib/axes/_base.pyi +++ b/lib/matplotlib/axes/_base.pyi @@ -405,7 +405,9 @@ class _AxesBase(martist.Artist): def get_autoscaley_on(self) -> bool: ... def set_autoscalex_on(self, b: bool) -> None: ... def set_autoscaley_on(self, b: bool) -> None: ... + def get_xinverted(self) -> bool: ... def xaxis_inverted(self) -> bool: ... + def set_xinverted(self, inverted: bool) -> None: ... def get_xscale(self) -> str: ... def set_xscale(self, value: str | ScaleBase, **kwargs) -> None: ... def get_xticks(self, *, minor: bool = ...) -> np.ndarray: ... @@ -430,7 +432,9 @@ class _AxesBase(martist.Artist): fontdict: dict[str, Any] | None = ..., **kwargs ) -> list[Text]: ... + def get_yinverted(self) -> bool: ... def yaxis_inverted(self) -> bool: ... + def set_yinverted(self, inverted: bool) -> None: ... def get_yscale(self) -> str: ... def set_yscale(self, value: str | ScaleBase, **kwargs) -> None: ... def get_yticks(self, *, minor: bool = ...) -> np.ndarray: ... diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py index d0ba360c314b..f58d2eedf80e 100644 --- a/lib/mpl_toolkits/mplot3d/axes3d.py +++ b/lib/mpl_toolkits/mplot3d/axes3d.py @@ -1888,16 +1888,31 @@ def invert_zaxis(self): """ Invert the z-axis. + .. admonition:: Discouraged + + The use of this method is discouraged. + Use `.Axes3D.set_zinverted` instead. + See Also -------- - zaxis_inverted + get_zinverted get_zlim, set_zlim get_zbound, set_zbound """ bottom, top = self.get_zlim() self.set_zlim(top, bottom, auto=None) + set_zinverted = _axis_method_wrapper("zaxis", "set_inverted") + get_zinverted = _axis_method_wrapper("zaxis", "get_inverted") zaxis_inverted = _axis_method_wrapper("zaxis", "get_inverted") + if zaxis_inverted.__doc__: + zaxis_inverted.__doc__ += textwrap.dedent(""" + + .. admonition:: Discouraged + + The use of this method is discouraged. + Use `.Axes3D.get_zinverted` instead. + """) def get_zbound(self): """