Merge pull request #20071 from anntzer/aaa

QuLogic · web-flow · commit 826e68598d29 · 2022-02-23T03:11:37.000-05:00
Document, test, and simplify impl. of auto_adjustable_area.
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
@@ -1,8 +1,7 @@
 """
-===================================
-Make Room For Ylabel Using Axesgrid
-===================================
-
+====================================
+Make room for ylabel using axes_grid
+====================================
 """
 
 import matplotlib.pyplot as plt
@@ -20,7 +19,6 @@
 
 ###############################################################################
 
-
 fig = plt.figure()
 ax1 = fig.add_axes([0, 0, 1, 0.5])
 ax2 = fig.add_axes([0, 0.5, 1, 0.5])
@@ -35,7 +33,6 @@
 
 ###############################################################################
 
-
 fig = plt.figure()
 ax1 = fig.add_axes([0, 0, 1, 1])
 divider = make_axes_locatable(ax1)
diff --git a/lib/mpl_toolkits/axes_grid1/axes_divider.py b/lib/mpl_toolkits/axes_grid1/axes_divider.py
@@ -265,14 +265,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 *use_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 where 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:
@@ -693,15 +702,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, padding is determined from the decorations of *ax*.
+    Pass *use_axes* to consider the decorations of other Axes instead.
+    """
     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
@@ -204,6 +204,7 @@ def get_size(self, renderer):
             return rel_size, abs_size
 
 
+@_api.deprecated("3.6", alternative="size + pad")
 class Padded(_Base):
     """
     Return a instance where the absolute part of *size* is
@@ -238,6 +239,7 @@ def from_any(size, fraction_ref=None):
     raise ValueError("Unknown format")
 
 
+@_api.deprecated("3.6")
 class SizeFromFunc(_Base):
     def __init__(self, func):
         self._func = func
@@ -252,6 +254,7 @@ def get_size(self, renderer):
         return rel_size, abs_size
 
 
+@_api.deprecated("3.6")
 class GetExtentHelper:
     _get_func_map = {
         "left":   lambda self, axes_bbox: axes_bbox.xmin - self.xmin,
@@ -271,3 +274,31 @@ def __call__(self, renderer):
                        ax.bbox)
               for ax in self._ax_list]
         return max(vl)
+
+
+class _AxesDecorationsSize(_Base):
+    """
+    Fixed size, corresponding to the size of decorations on a given Axes side.
+    """
+
+    _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
@@ -510,3 +511,16 @@ def test_mark_inset_unstales_viewlim(fig_test, fig_ref):
     mark_inset(full, inset, 1, 4)
     # Manually unstale the full's viewLim.
     fig_ref.canvas.draw()
+
+
+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)
