Deprecate axes_divider.AxesLocator.

The axes_divider module creates axes locator objects, allowing the
following pattern.
```
divider = Divider(<divider-args>)  # or a subclass of Divider
locator = divider.new_locator(<locator-args>)
ax.set_axes_locator(locator)  # will call locator(ax, renderer) at draw time
```
`locator` is actually an AxesLocator instance, which gets passed
`divider` and `<locator-args>`; `locator(ax, renderer)` then simply
calls (something like) `divider.locate(<locator-args>, ax, renderer)`,
i.e. the AxesLocator instance simply exists to hold arguments for
calling back into a divider method.

One issue of this approach is that all the communication between the
Divider and the AxesLocator class becomes public API (e.g., the locate
method), even though these are essentially internal implementation
details.  This makes e.g. tightening of the locate API need to go
through deprecation cycles (6eeb9ba).

Instead, this PR completely gets rid of the AxesLocator class, and lets
new_locator return an essentially opaque callable object (a
functools.partial over a private method of AxesLocator), for which the
only documented API is "this can be used as an axes locator callable,
i.e. passed to ax.set_axes.locator".  This PR also clarifies the role of
_xrefindex and _yrefindex and consolidates all their handling into
append_size, letting new_horizontal and new_vertical call that method
instead of manipulating these indices themselves.

Author: anntzer

doc/api/next_api_changes/deprecations/24312-AL.rst

@@ -0,0 +1,9 @@
+``axes_grid1.axes_divider`` API changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``AxesLocator`` class is deprecated.  The ``new_locator`` method of divider
+instances now instead returns an opaque callable (which can still be passed to
+``ax.set_axes_locator``).
+
+``Divider.locate`` is deprecated; use ``Divider.new_locator(...)(ax, renderer)``
+instead.

galleries/users_explain/toolkits/axes_grid.py

@@ -302,7 +302,7 @@
     horiz = [...]  # Some other horizontal constraints.
     divider = Divider(fig, rect, horiz, vert)
 
-then use `.Divider.new_locator` to create an `.AxesLocator` instance for a
+then use `.Divider.new_locator` to create an axes locator callable for a
 given grid entry::
 
     locator = divider.new_locator(nx=0, ny=1)  # Grid entry (1, 0).
@@ -311,7 +311,7 @@
 
     ax.set_axes_locator(locator)
 
-The `.AxesLocator` is a callable object that returns the location and size of
+The axes locator callable returns the location and size of
 the cell at the first column and the second row.
 
 Locators that spans over multiple cells can be created with, e.g.::

lib/mpl_toolkits/axes_grid1/axes_divider.py

@@ -2,6 +2,8 @@
 Helper classes to adjust the positions of multiple axes at drawing time.
 """
 
+import functools
+
 import numpy as np
 
 import matplotlib as mpl
@@ -99,6 +101,9 @@ def get_anchor(self):
         """Return the anchor."""
         return self._anchor
 
+    def get_subplotspec(self):
+        return None
+
     def set_horizontal(self, h):
         """
         Parameters
@@ -162,8 +167,44 @@ def _calc_offsets(sizes, k):
         # the resulting cumulative offset positions.
         return np.cumsum([0, *(sizes @ [k, 1])])
 
+    def new_locator(self, nx, ny, nx1=None, ny1=None):
+        """
+        Return an axes locator callable for the specified cell.
+
+        Parameters
+        ----------
+        nx, nx1 : int
+            Integers specifying the column-position of the
+            cell. When *nx1* is None, a single *nx*-th column is
+            specified. Otherwise, location of columns spanning between *nx*
+            to *nx1* (but excluding *nx1*-th column) is specified.
+        ny, ny1 : int
+            Same as *nx* and *nx1*, but for row positions.
+        """
+        if nx1 is None:
+            nx1 = nx + 1
+        if ny1 is None:
+            ny1 = ny + 1
+        # append_size("left") adds a new size at the beginning of the
+        # horizontal size lists; this shift transforms e.g.
+        # new_locator(nx=2, ...) into effectively new_locator(nx=3, ...).  To
+        # take that into account, instead of recording nx, we record
+        # nx-self._xrefindex, where _xrefindex is shifted by 1 by each
+        # append_size("left"), and re-add self._xrefindex back to nx in
+        # _locate, when the actual axes position is computed.  Ditto for y.
+        xref = self._xrefindex
+        yref = self._yrefindex
+        locator = functools.partial(
+            self._locate, nx - xref, ny - yref, nx1 - xref, ny1 - yref)
+        locator.get_subplotspec = self.get_subplotspec
+        return locator
+
+    @_api.deprecated(
+        "3.8", alternative="divider.new_locator(...)(ax, renderer)")
     def locate(self, nx, ny, nx1=None, ny1=None, axes=None, renderer=None):
         """
+        Implementation of ``divider.new_locator().__call__``.
+
         Parameters
         ----------
         nx, nx1 : int
@@ -176,6 +217,25 @@ def locate(self, nx, ny, nx1=None, ny1=None, axes=None, renderer=None):
         axes
         renderer
         """
+        xref = self._xrefindex
+        yref = self._yrefindex
+        return self._locate(
+            nx - xref, (nx + 1 if nx1 is None else nx1) - xref,
+            ny - yref, (ny + 1 if ny1 is None else ny1) - yref,
+            axes, renderer)
+
+    def _locate(self, nx, ny, nx1, ny1, axes, renderer):
+        """
+        Implementation of ``divider.new_locator().__call__``.
+
+        The axes locator callable returned by ``new_locator()`` is created as
+        a `functools.partial` of this method with *nx*, *ny*, *nx1*, and *ny1*
+        specifying the requested cell.
+        """
+        nx += self._xrefindex
+        nx1 += self._xrefindex
+        ny += self._yrefindex
+        ny1 += self._yrefindex
 
         fig_w, fig_h = self._fig.bbox.size / self._fig.dpi
         x, y, w, h = self.get_position_runtime(axes, renderer)
@@ -211,25 +271,6 @@ def locate(self, nx, ny, nx1=None, ny1=None, axes=None, renderer=None):
 
         return mtransforms.Bbox.from_bounds(x1, y1, w1, h1)
 
-    def new_locator(self, nx, ny, nx1=None, ny1=None):
-        """
-        Return a new `.AxesLocator` for the specified cell.
-
-        Parameters
-        ----------
-        nx, nx1 : int
-            Integers specifying the column-position of the
-            cell. When *nx1* is None, a single *nx*-th column is
-            specified. Otherwise, location of columns spanning between *nx*
-            to *nx1* (but excluding *nx1*-th column) is specified.
-        ny, ny1 : int
-            Same as *nx* and *nx1*, but for row positions.
-        """
-        return AxesLocator(
-            self, nx, ny,
-            nx1 if nx1 is not None else nx + 1,
-            ny1 if ny1 is not None else ny + 1)
-
     def append_size(self, position, size):
         _api.check_in_list(["left", "right", "bottom", "top"],
                            position=position)
@@ -264,6 +305,7 @@ def add_auto_adjustable_area(self, use_axes, pad=0.1, adjust_dirs=None):
             self.append_size(d, Size._AxesDecorationsSize(use_axes, d) + pad)
 
 
+@_api.deprecated("3.8")
 class AxesLocator:
     """
     A callable object which returns the position and size of a given
@@ -400,24 +442,17 @@ def new_horizontal(self, size, pad=None, pack_start=False, **kwargs):
         """
         if pad is None:
             pad = mpl.rcParams["figure.subplot.wspace"] * self._xref
+        pos = "left" if pack_start else "right"
         if pad:
             if not isinstance(pad, Size._Base):
                 pad = Size.from_any(pad, fraction_ref=self._xref)
-            if pack_start:
-                self._horizontal.insert(0, pad)
-                self._xrefindex += 1
-            else:
-                self._horizontal.append(pad)
+            self.append_size(pos, pad)
         if not isinstance(size, Size._Base):
             size = Size.from_any(size, fraction_ref=self._xref)
-        if pack_start:
-            self._horizontal.insert(0, size)
-            self._xrefindex += 1
-            locator = self.new_locator(nx=0, ny=self._yrefindex)
-        else:
-            self._horizontal.append(size)
-            locator = self.new_locator(
-                nx=len(self._horizontal) - 1, ny=self._yrefindex)
+        self.append_size(pos, size)
+        locator = self.new_locator(
+            nx=0 if pack_start else len(self._horizontal) - 1,
+            ny=self._yrefindex)
         ax = self._get_new_axes(**kwargs)
         ax.set_axes_locator(locator)
         return ax
@@ -432,24 +467,17 @@ def new_vertical(self, size, pad=None, pack_start=False, **kwargs):
         """
         if pad is None:
             pad = mpl.rcParams["figure.subplot.hspace"] * self._yref
+        pos = "bottom" if pack_start else "top"
         if pad:
             if not isinstance(pad, Size._Base):
                 pad = Size.from_any(pad, fraction_ref=self._yref)
-            if pack_start:
-                self._vertical.insert(0, pad)
-                self._yrefindex += 1
-            else:
-                self._vertical.append(pad)
+            self.append_size(pos, pad)
         if not isinstance(size, Size._Base):
             size = Size.from_any(size, fraction_ref=self._yref)
-        if pack_start:
-            self._vertical.insert(0, size)
-            self._yrefindex += 1
-            locator = self.new_locator(nx=self._xrefindex, ny=0)
-        else:
-            self._vertical.append(size)
-            locator = self.new_locator(
-                nx=self._xrefindex, ny=len(self._vertical) - 1)
+        self.append_size(pos, size)
+        locator = self.new_locator(
+            nx=self._xrefindex,
+            ny=0 if pack_start else len(self._vertical) - 1)
         ax = self._get_new_axes(**kwargs)
         ax.set_axes_locator(locator)
         return ax
@@ -563,7 +591,7 @@ class HBoxDivider(SubplotDivider):
 
     def new_locator(self, nx, nx1=None):
         """
-        Create a new `.AxesLocator` for the specified cell.
+        Create an axes locator callable for the specified cell.
 
         Parameters
         ----------
@@ -573,10 +601,12 @@ def new_locator(self, nx, nx1=None):
             specified. Otherwise, location of columns spanning between *nx*
             to *nx1* (but excluding *nx1*-th column) is specified.
         """
-        return AxesLocator(self, nx, 0, nx1 if nx1 is not None else nx + 1, 1)
+        return super().new_locator(nx, 0, nx1, 0)
 
-    def locate(self, nx, ny, nx1=None, ny1=None, axes=None, renderer=None):
+    def _locate(self, nx, ny, nx1, ny1, axes, renderer):
         # docstring inherited
+        nx += self._xrefindex
+        nx1 += self._xrefindex
         fig_w, fig_h = self._fig.bbox.size / self._fig.dpi
         x, y, w, h = self.get_position_runtime(axes, renderer)
         summed_ws = self.get_horizontal_sizes(renderer)
@@ -598,7 +628,7 @@ class VBoxDivider(SubplotDivider):
 
     def new_locator(self, ny, ny1=None):
         """
-        Create a new `.AxesLocator` for the specified cell.
+        Create an axes locator callable for the specified cell.
 
         Parameters
         ----------
@@ -608,10 +638,12 @@ def new_locator(self, ny, ny1=None):
             specified. Otherwise, location of rows spanning between *ny*
             to *ny1* (but excluding *ny1*-th row) is specified.
         """
-        return AxesLocator(self, 0, ny, 1, ny1 if ny1 is not None else ny + 1)
+        return super().new_locator(0, ny, 0, ny1)
 
-    def locate(self, nx, ny, nx1=None, ny1=None, axes=None, renderer=None):
+    def _locate(self, nx, ny, nx1, ny1, axes, renderer):
         # docstring inherited
+        ny += self._yrefindex
+        ny1 += self._yrefindex
         fig_w, fig_h = self._fig.bbox.size / self._fig.dpi
         x, y, w, h = self.get_position_runtime(axes, renderer)
         summed_hs = self.get_vertical_sizes(renderer)

lib/mpl_toolkits/axes_grid1/tests/test_axes_grid1.py

@@ -608,9 +608,14 @@ def test_grid_axes_position(direction):
     fig = plt.figure()
     grid = Grid(fig, 111, (2, 2), direction=direction)
     loc = [ax.get_axes_locator() for ax in np.ravel(grid.axes_row)]
-    assert loc[1]._nx > loc[0]._nx and loc[2]._ny < loc[0]._ny
-    assert loc[0]._nx == loc[2]._nx and loc[0]._ny == loc[1]._ny
-    assert loc[3]._nx == loc[1]._nx and loc[3]._ny == loc[2]._ny
+    # Test nx.
+    assert loc[1].args[0] > loc[0].args[0]
+    assert loc[0].args[0] == loc[2].args[0]
+    assert loc[3].args[0] == loc[1].args[0]
+    # Test ny.
+    assert loc[2].args[1] < loc[0].args[1]
+    assert loc[0].args[1] == loc[1].args[1]
+    assert loc[3].args[1] == loc[2].args[1]
 
 
 @pytest.mark.parametrize('rect, ngrids, error, message', (