Add "standard" Axes wrapper getters/setters for Axis invertedness.

anntzer · anntzer · commit f5764c9c3877 · 2024-11-05T12:37:42.000+01:00
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)`).
diff --git a/doc/users/next_whats_new/axis_inversion.rst b/doc/users/next_whats_new/axis_inversion.rst
@@ -0,0 +1,4 @@
+Standard getters/setters for axis inversion state
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Whether an axis is inverted can now be queried and set using the `.Axes` getters
+`.get_xinverted`/`.get_yinverted` and setters `.set_xinverted`/`.set_yinverted`.
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -3605,13 +3605,14 @@ def invert_xaxis(self):
 
         See Also
         --------
-        xaxis_inverted
+        get_xinverted
         get_xlim, set_xlim
         get_xbound, set_xbound
         """
         self.xaxis.set_inverted(not self.xaxis.get_inverted())
 
-    xaxis_inverted = _axis_method_wrapper("xaxis", "get_inverted")
+    set_xinverted = _axis_method_wrapper("xaxis", "set_inverted")
+    get_xinverted = xaxis_inverted = _axis_method_wrapper("xaxis", "get_inverted")
 
     def get_xbound(self):
         """
@@ -3858,13 +3859,14 @@ def invert_yaxis(self):
 
         See Also
         --------
-        yaxis_inverted
+        get_yinverted
         get_ylim, set_ylim
         get_ybound, set_ybound
         """
         self.yaxis.set_inverted(not self.yaxis.get_inverted())
 
-    yaxis_inverted = _axis_method_wrapper("yaxis", "get_inverted")
+    set_yinverted = _axis_method_wrapper("yaxis", "set_inverted")
+    get_yinverted = yaxis_inverted = _axis_method_wrapper("yaxis", "get_inverted")
 
     def get_ybound(self):
         """
diff --git 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
@@ -1890,14 +1890,15 @@ def invert_zaxis(self):
 
         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)
 
-    zaxis_inverted = _axis_method_wrapper("zaxis", "get_inverted")
+    set_zinverted = _axis_method_wrapper("zaxis", "set_inverted")
+    get_zinverted = zaxis_inverted = _axis_method_wrapper("zaxis", "get_inverted")
 
     def get_zbound(self):
         """
