Document, test, and simplify impl. of auto_adjustable_area.

anntzer · anntzer · commit 2e29d008775d · 2021-10-21T00:52:54.000+02:00
Document behavior of auto_adjustable_area, and slightly modernize the
example.

Simplify its implementation: `Padded` is just size addition and
`GetExtentHelper` and `SizeFromFunc` can reasonably be fused into a
single class; none of them are used anywhere else, so just deprecate
them as public APIs.

Add a test.
diff --git a/doc/api/next_api_changes/deprecations/20071-AL.rst b/doc/api/next_api_changes/deprecations/20071-AL.rst
@@ -0,0 +1,5 @@
+``axes_size`` internal helpers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following APIs are deprecated: ``axes_size.Padded`` (use ``size + pad``
+instead), ``axes_size.SizeFromFunc``, ``axes_size.GetExtentHelper``.
diff --git a/examples/axes_grid1/make_room_for_ylabel_using_axesgrid.py b/examples/axes_grid1/make_room_for_ylabel_using_axesgrid.py
@@ -11,19 +11,18 @@
 from mpl_toolkits.axes_grid1.axes_divider import make_axes_area_auto_adjustable
 
 
-plt.figure()
-ax = plt.axes([0, 0, 1, 1])
+fig = plt.figure()
+ax = fig.add_axes([0, 0, 1, 1])
 
 ax.set_yticks([0.5], labels=["very long label"])
 
 make_axes_area_auto_adjustable(ax)
 
 ###############################################################################
 
-
-plt.figure()
-ax1 = plt.axes([0, 0, 1, 0.5])
-ax2 = plt.axes([0, 0.5, 1, 0.5])
+fig = plt.figure()
+ax1 = fig.add_axes([0, 0, 1, 0.5])
+ax2 = fig.add_axes([0, 0.5, 1, 0.5])
 
 ax1.set_yticks([0.5], labels=["very long label"])
 ax1.set_ylabel("Y label")
@@ -37,7 +36,7 @@
 
 
 fig = plt.figure()
-ax1 = plt.axes([0, 0, 1, 1])
+ax1 = fig.add_axes([0, 0, 1, 1])
 divider = make_axes_locatable(ax1)
 
 ax2 = divider.new_horizontal("100%", pad=0.3, sharey=ax1)
diff --git a/lib/mpl_toolkits/axes_grid1/axes_divider.py b/lib/mpl_toolkits/axes_grid1/axes_divider.py
@@ -266,14 +266,23 @@ def append_size(self, position, size):
                                position=position)
 
     def add_auto_adjustable_area(self, use_axes, pad=0.1, adjust_dirs=None):
+        """
+        Add auto-adjustable padding around axes to take their decorations
+        (title, labels, ticks, ticklabels) into account during layout.
+
+        Parameters
+        ----------
+        use_axes : `~.axes.Axes` or list of `~.axes.Axes`
+            The axes whose decorations are taken into account.
+        pad : float, optional
+            Additional padding in inches.
+        adjust_dirs : list of {"left", "right", "bottom", "top"}, optional
+            The sides in which padding is added; defaults to all four sides.
+        """
         if adjust_dirs is None:
             adjust_dirs = ["left", "right", "bottom", "top"]
-        from .axes_size import Padded, SizeFromFunc, GetExtentHelper
         for d in adjust_dirs:
-            helper = GetExtentHelper(use_axes, d)
-            size = SizeFromFunc(helper)
-            padded_size = Padded(size, pad)  # pad in inch
-            self.append_size(d, padded_size)
+            self.append_size(d, Size._AxesDecorationsSize(use_axes, d) + pad)
 
 
 class AxesLocator:
@@ -733,15 +742,20 @@ def make_axes_locatable(axes):
     return divider
 
 
-def make_axes_area_auto_adjustable(ax,
-                                   use_axes=None, pad=0.1,
-                                   adjust_dirs=None):
+def make_axes_area_auto_adjustable(
+        ax, use_axes=None, pad=0.1, adjust_dirs=None):
+    """
+    Add auto-adjustable padding around *ax* to take its decorations (title,
+    labels, ticks, ticklabels) into account during layout, using
+    `Divider.add_auto_adjustable_area`.
+
+    By default, the decorations of *ax* are taken into account, but the
+    decorations of other artists can be used instead using *use_axes*.
+    """
     if adjust_dirs is None:
         adjust_dirs = ["left", "right", "bottom", "top"]
     divider = make_axes_locatable(ax)
-
     if use_axes is None:
         use_axes = ax
-
     divider.add_auto_adjustable_area(use_axes=use_axes, pad=pad,
                                      adjust_dirs=adjust_dirs)
diff --git a/lib/mpl_toolkits/axes_grid1/axes_size.py b/lib/mpl_toolkits/axes_grid1/axes_size.py
@@ -203,6 +203,7 @@ def get_size(self, renderer):
             return rel_size, abs_size
 
 
+@_api.deprecated("3.5", alternative="size + pad")
 class Padded(_Base):
     """
     Return a instance where the absolute part of *size* is
@@ -237,6 +238,7 @@ def from_any(size, fraction_ref=None):
     raise ValueError("Unknown format")
 
 
+@_api.deprecated("3.5")
 class SizeFromFunc(_Base):
     def __init__(self, func):
         self._func = func
@@ -251,6 +253,7 @@ def get_size(self, renderer):
         return rel_size, abs_size
 
 
+@_api.deprecated("3.5")
 class GetExtentHelper:
     _get_func_map = {
         "left":   lambda self, axes_bbox: axes_bbox.xmin - self.xmin,
@@ -270,3 +273,27 @@ def __call__(self, renderer):
                        ax.bbox)
               for ax in self._ax_list]
         return max(vl)
+
+
+class _AxesDecorationsSize(_Base):
+    _get_size_map = {
+        "left":   lambda tight_bb, axes_bb: axes_bb.xmin - tight_bb.xmin,
+        "right":  lambda tight_bb, axes_bb: tight_bb.xmax - axes_bb.xmax,
+        "bottom": lambda tight_bb, axes_bb: axes_bb.ymin - tight_bb.ymin,
+        "top":    lambda tight_bb, axes_bb: tight_bb.ymax - axes_bb.ymax,
+    }
+
+    def __init__(self, ax, direction):
+        self._get_size = _api.check_getitem(
+            self._get_size_map, direction=direction)
+        self._ax_list = [ax] if isinstance(ax, Axes) else ax
+
+    def get_size(self, renderer):
+        sz = max([
+            self._get_size(ax.get_tightbbox(renderer, call_axes_locator=False),
+                           ax.bbox)
+            for ax in self._ax_list])
+        dpi = renderer.points_to_pixels(72)
+        abs_size = sz / dpi
+        rel_size = 0
+        return rel_size, abs_size
diff --git a/lib/mpl_toolkits/tests/test_axes_grid1.py b/lib/mpl_toolkits/tests/test_axes_grid1.py
@@ -16,7 +16,8 @@
     Grid, AxesGrid, ImageGrid)
 from mpl_toolkits.axes_grid1.anchored_artists import (
     AnchoredSizeBar, AnchoredDirectionArrows)
-from mpl_toolkits.axes_grid1.axes_divider import HBoxDivider
+from mpl_toolkits.axes_grid1.axes_divider import (
+    HBoxDivider, make_axes_area_auto_adjustable)
 from mpl_toolkits.axes_grid1.inset_locator import (
     zoomed_inset_axes, mark_inset, inset_axes, BboxConnectorPatch)
 import mpl_toolkits.axes_grid1.mpl_axes
@@ -494,3 +495,16 @@ def test_grid_axes_position(direction):
     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
+
+
+def test_auto_adjustable():
+    fig = plt.figure()
+    ax = fig.add_axes([0, 0, 1, 1])
+    pad = 0.1
+    make_axes_area_auto_adjustable(ax, pad=pad)
+    fig.canvas.draw()
+    tbb = ax.get_tightbbox(fig._cachedRenderer)
+    assert tbb.x0 == pytest.approx(pad * fig.dpi)
+    assert tbb.x1 == pytest.approx(fig.bbox.width - pad * fig.dpi)
+    assert tbb.y0 == pytest.approx(pad * fig.dpi)
+    assert tbb.y1 == pytest.approx(fig.bbox.height - pad * fig.dpi)
