Merge pull request matplotlib#20079 from anntzer/nxy1none

Prepare axes_divider for simpler(?) indexing-based API.

Author: QuLogic

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

@@ -0,0 +1,10 @@
+Support for ``nx1 = None`` or ``ny1 = None`` in ``AxesLocator`` and ``Divider.locate``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In :mod:`.axes_grid1.axes_divider`, various internal APIs will stop supporting
+passing ``nx1 = None`` or ``ny1 = None`` to mean ``nx + 1`` or ``ny + 1``, in
+preparation for a possible future API which allows indexing and slicing of
+dividers (possibly ``divider[a:b] == divider.new_locator(a, b)``, but also
+``divider[a:] == divider.new_locator(a, <end>)``).  The user-facing
+`.Divider.new_locator` API is unaffected -- it correctly normalizes ``nx1 = None``
+and ``ny1 = None`` as needed.

lib/mpl_toolkits/axes_grid1/axes_divider.py

@@ -214,8 +214,16 @@ def locate(self, nx, ny, nx1=None, ny1=None, axes=None, renderer=None):
             x0, y0 = x, y
 
         if nx1 is None:
+            _api.warn_deprecated(
+                "3.5", message="Support for passing nx1=None to mean nx+1 is "
+                "deprecated since %(since)s; in a future version, nx1=None "
+                "will mean 'up to the last cell'.")
             nx1 = nx + 1
         if ny1 is None:
+            _api.warn_deprecated(
+                "3.5", message="Support for passing ny1=None to mean ny+1 is "
+                "deprecated since %(since)s; in a future version, ny1=None "
+                "will mean 'up to the last cell'.")
             ny1 = ny + 1
 
         x1, w1 = x0 + ox[nx] / fig_w, (ox[nx1] - ox[nx]) / fig_w
@@ -237,7 +245,10 @@ def new_locator(self, nx, ny, nx1=None, ny1=None):
         ny, ny1 : int
             Same as *nx* and *nx1*, but for row positions.
         """
-        return AxesLocator(self, nx, ny, nx1, ny1)
+        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):
         if position == "left":
@@ -267,9 +278,10 @@ def add_auto_adjustable_area(self, use_axes, pad=0.1, adjust_dirs=None):
 
 class AxesLocator:
     """
-    A simple callable object, initialized with AxesDivider class,
-    returns the position and size of the given cell.
+    A callable object which returns the position and size of a given
+    AxesDivider cell.
     """
+
     def __init__(self, axes_divider, nx, ny, nx1=None, ny1=None):
         """
         Parameters
@@ -291,8 +303,16 @@ def __init__(self, axes_divider, nx, ny, nx1=None, ny1=None):
         self._nx, self._ny = nx - _xrefindex, ny - _yrefindex
 
         if nx1 is None:
+            _api.warn_deprecated(
+                "3.5", message="Support for passing nx1=None to mean nx+1 is "
+                "deprecated since %(since)s; in a future version, nx1=None "
+                "will mean 'up to the last cell'.")
             nx1 = nx + 1
         if ny1 is None:
+            _api.warn_deprecated(
+                "3.5", message="Support for passing ny1=None to mean ny+1 is "
+                "deprecated since %(since)s; in a future version, ny1=None "
+                "will mean 'up to the last cell'.")
             ny1 = ny + 1
 
         self._nx1 = nx1 - _xrefindex
@@ -645,7 +665,7 @@ 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, None)
+        return AxesLocator(self, nx, 0, nx1 if nx1 is not None else nx + 1, 1)
 
     def locate(self, nx, ny, nx1=None, ny1=None, axes=None, renderer=None):
         # docstring inherited
@@ -656,6 +676,10 @@ def locate(self, nx, ny, nx1=None, ny1=None, axes=None, renderer=None):
         x0, y0, ox, hh = _locate(
             x, y, w, h, summed_ws, equal_hs, fig_w, fig_h, self.get_anchor())
         if nx1 is None:
+            _api.warn_deprecated(
+                "3.5", message="Support for passing nx1=None to mean nx+1 is "
+                "deprecated since %(since)s; in a future version, nx1=None "
+                "will mean 'up to the last cell'.")
             nx1 = nx + 1
         x1, w1 = x0 + ox[nx] / fig_w, (ox[nx1] - ox[nx]) / fig_w
         y1, h1 = y0, hh
@@ -680,7 +704,7 @@ 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, None, ny1)
+        return AxesLocator(self, 0, ny, 1, ny1 if ny1 is not None else ny + 1)
 
     def locate(self, nx, ny, nx1=None, ny1=None, axes=None, renderer=None):
         # docstring inherited
@@ -691,6 +715,10 @@ def locate(self, nx, ny, nx1=None, ny1=None, axes=None, renderer=None):
         y0, x0, oy, ww = _locate(
             y, x, h, w, summed_hs, equal_ws, fig_h, fig_w, self.get_anchor())
         if ny1 is None:
+            _api.warn_deprecated(
+                "3.5", message="Support for passing ny1=None to mean ny+1 is "
+                "deprecated since %(since)s; in a future version, ny1=None "
+                "will mean 'up to the last cell'.")
             ny1 = ny + 1
         x1, w1 = x0, ww
         y1, h1 = y0 + oy[ny] / fig_h, (oy[ny1] - oy[ny]) / fig_h