Deprecate nth_coord parameter from FixedAxisArtistHelper.new_fixed_axis.

anntzer · anntzer · commit 8d69190a840b · 2023-10-16T11:27:38.000+02:00
FixedAxisArtistHelpers place an axis on either the bottom, top, left, or
right of an axis per (`loc`); we already infer whether it's an x-axis or
a y-axis (`nth_coord`) from that and error out if there's a mismatch, so
we may just as well delete the nth_coord parameter (which was already
optional to start with).

While at it, also expire deprecation for passing inconsistent nth_coord
and loc.
diff --git a/doc/api/next_api_changes/deprecations/27095-AL.rst b/doc/api/next_api_changes/deprecations/27095-AL.rst
@@ -0,0 +1,10 @@
+*nth_coord* parameter to axisartist helpers for fixed axis
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Helper APIs in `.axisartist` for generating a "fixed" axis on rectilinear axes
+(`.FixedAxisArtistHelperRectilinear`) no longer take a *nth_coord* parameter,
+as that parameter is entirely inferred from the (required) *loc* parameter and
+having inconsistent *nth_coord* and *loc* is an error.
+
+For curvilinear axes, the *nth_coord* parameter remains supported (it affects
+the *ticks*, not the axis position itself), but that parameter will become
+keyword-only, for consistency with the rectilinear case.
diff --git a/doc/api/next_api_changes/removals/27095-AL.rst b/doc/api/next_api_changes/removals/27095-AL.rst
@@ -0,0 +1,5 @@
+Inconsistent *nth_coord* and *loc* passed to ``_FixedAxisArtistHelperBase``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The value of the *nth_coord* parameter of ``_FixedAxisArtistHelperBase`` and
+its subclasses is now inferred from the value of *loc*; passing inconsistent
+values (e.g., requesting a "top y axis" or a "left x axis") has no more effect.
diff --git a/lib/mpl_toolkits/axisartist/axislines.py b/lib/mpl_toolkits/axisartist/axislines.py
@@ -116,17 +116,11 @@ class _FixedAxisArtistHelperBase(_AxisArtistHelperBase):
         lambda self: {"left": (0, 0), "right": (1, 0),
                       "bottom": (0, 0), "top": (0, 1)}[self._loc]))
 
+    @_api.delete_parameter("3.9", "nth_coord")
     def __init__(self, loc, nth_coord=None):
         """``nth_coord = 0``: x-axis; ``nth_coord = 1``: y-axis."""
-        self.nth_coord = (
-            nth_coord if nth_coord is not None else
-            _api.check_getitem(
-                {"bottom": 0, "top": 0, "left": 1, "right": 1}, loc=loc))
-        if (nth_coord == 0 and loc not in ["left", "right"]
-                or nth_coord == 1 and loc not in ["bottom", "top"]):
-            _api.warn_deprecated(
-                "3.7", message=f"{loc=!r} is incompatible with "
-                "{nth_coord=}; support is deprecated since %(since)s")
+        self.nth_coord = _api.check_getitem(
+            {"bottom": 0, "top": 0, "left": 1, "right": 1}, loc=loc)
         self._loc = loc
         self._pos = {"bottom": 0, "top": 1, "left": 0, "right": 1}[loc]
         super().__init__()
@@ -184,12 +178,13 @@ def get_line(self, axes):
 
 class FixedAxisArtistHelperRectilinear(_FixedAxisArtistHelperBase):
 
+    @_api.delete_parameter("3.9", "nth_coord")
     def __init__(self, axes, loc, nth_coord=None):
         """
         nth_coord = along which coordinate value varies
         in 2D, nth_coord = 0 ->  x axis, nth_coord = 1 -> y axis
         """
-        super().__init__(loc, nth_coord)
+        super().__init__(loc)
         self.axis = [axes.xaxis, axes.yaxis][self.nth_coord]
 
     # TICK
@@ -333,6 +328,8 @@ def __init__(self, axes):
         super().__init__()
         self.axes = axes
 
+    @_api.delete_parameter(
+        "3.9", "nth_coord", addendum="'nth_coord' is now inferred from 'loc'.")
     def new_fixed_axis(self, loc,
                        nth_coord=None,
                        axis_direction=None,
@@ -345,8 +342,7 @@ def new_fixed_axis(self, loc,
             axes = self.axes
         if axis_direction is None:
             axis_direction = loc
-
-        helper = FixedAxisArtistHelperRectilinear(axes, loc, nth_coord)
+        helper = FixedAxisArtistHelperRectilinear(axes, loc)
         axisline = AxisArtist(axes, helper, offset=offset,
                               axis_direction=axis_direction)
         return axisline
@@ -359,7 +355,6 @@ def new_floating_axis(self, nth_coord, value,
             _api.warn_external(
                 "'new_floating_axis' explicitly requires the axes keyword.")
             axes = self.axes
-
         helper = FloatingAxisArtistHelperRectilinear(
             axes, nth_coord, value, axis_direction)
         axisline = AxisArtist(axes, helper, axis_direction=axis_direction)
@@ -494,21 +489,11 @@ def get_children(self):
         return children
 
     def new_fixed_axis(self, loc, offset=None):
-        gh = self.get_grid_helper()
-        axis = gh.new_fixed_axis(loc,
-                                 nth_coord=None,
-                                 axis_direction=None,
-                                 offset=offset,
-                                 axes=self,
-                                 )
-        return axis
+        return self.get_grid_helper().new_fixed_axis(loc, offset=offset, axes=self)
 
     def new_floating_axis(self, nth_coord, value, axis_direction="bottom"):
-        gh = self.get_grid_helper()
-        axis = gh.new_floating_axis(nth_coord, value,
-                                    axis_direction=axis_direction,
-                                    axes=self)
-        return axis
+        return self.get_grid_helper().new_floating_axis(
+            nth_coord, value, axis_direction=axis_direction, axes=self)
 
 
 class AxesZero(Axes):
diff --git a/lib/mpl_toolkits/axisartist/grid_helper_curvelinear.py b/lib/mpl_toolkits/axisartist/grid_helper_curvelinear.py
@@ -8,6 +8,7 @@
 import numpy as np
 
 import matplotlib as mpl
+from matplotlib import _api
 from matplotlib.path import Path
 from matplotlib.transforms import Affine2D, IdentityTransform
 from .axislines import (
@@ -270,6 +271,7 @@ def update_grid_finder(self, aux_trans=None, **kwargs):
         self.grid_finder.update(**kwargs)
         self._old_limits = None  # Force revalidation.
 
+    @_api.make_keyword_only("3.9", "nth_coord")
     def new_fixed_axis(self, loc,
                        nth_coord=None,
                        axis_direction=None,
