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)`).

Author: anntzer

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
 

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

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.

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):
         """

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: ...

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):
         """