Merge pull request matplotlib#20426 from jklymak/layout-engine

ENH: Layout engine

Author: tacaswell

doc/api/index.rst

@@ -67,6 +67,7 @@ Alphabetical list of modules:
    gridspec_api.rst
    hatch_api.rst
    image_api.rst
+   layout_engine_api.rst
    legend_api.rst
    legend_handler_api.rst
    lines_api.rst

doc/api/layout_engine_api.rst

@@ -0,0 +1,9 @@
+****************************
+``matplotlib.layout_engine``
+****************************
+
+.. currentmodule:: matplotlib.layout_engine
+
+.. automodule:: matplotlib.layout_engine
+   :members:
+   :inherited-members:

doc/api/next_api_changes/behavior/20426-JK.rst

@@ -0,0 +1,5 @@
+Incompatible layout engines raise
+---------------------------------
+``tight_layout`` and ``constrained_layout`` are incompatible if
+a colorbar has been added to the figure.  Invoking the incompatible layout
+engine used to warn, but now raises with a ``RuntimeError``.

doc/users/next_whats_new/layout_engine.rst

@@ -0,0 +1,7 @@
+New ``layout_engine`` module
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Matplotlib ships with ``tight_layout`` and ``constrained_layout`` layout
+engines.  A new ``layout_engine`` module is provided to allow downstream
+libraries to write their own layout engines and `~.figure.Figure` objects can
+now take a `.LayoutEngine` subclass as an argument to the *layout* parameter.

lib/matplotlib/_constrained_layout.py

@@ -18,6 +18,7 @@
 import numpy as np
 
 from matplotlib import _api, artist as martist
+from matplotlib.backend_bases import _get_renderer
 import matplotlib.transforms as mtransforms
 import matplotlib._layoutgrid as mlayoutgrid
 
@@ -62,7 +63,7 @@
 
 
 ######################################################
-def do_constrained_layout(fig, renderer, h_pad, w_pad,
+def do_constrained_layout(fig, h_pad, w_pad,
                           hspace=None, wspace=None):
     """
     Do the constrained_layout.  Called at draw time in
@@ -91,6 +92,7 @@ def do_constrained_layout(fig, renderer, h_pad, w_pad,
     layoutgrid : private debugging structure
     """
 
+    renderer = _get_renderer(fig)
     # make layoutgrid tree...
     layoutgrids = make_layoutgrids(fig, None)
     if not layoutgrids['hasgrids']:

lib/matplotlib/_tight_bbox.py

@@ -17,11 +17,10 @@ def adjust_bbox(fig, bbox_inches, fixed_dpi=None):
     """
     origBbox = fig.bbox
     origBboxInches = fig.bbox_inches
-    orig_tight_layout = fig.get_tight_layout()
+    orig_layout = fig.get_layout_engine()
+    fig.set_layout_engine(None)
     _boxout = fig.transFigure._boxout
 
-    fig.set_tight_layout(False)
-
     old_aspect = []
     locator_list = []
     sentinel = object()
@@ -47,7 +46,7 @@ def restore_bbox():
 
         fig.bbox = origBbox
         fig.bbox_inches = origBboxInches
-        fig.set_tight_layout(orig_tight_layout)
+        fig.set_layout_engine(orig_layout)
         fig.transFigure._boxout = _boxout
         fig.transFigure.invalidate()
         fig.patch.set_bounds(0, 0, 1, 1)

lib/matplotlib/backend_bases.py

@@ -2226,7 +2226,7 @@ def print_figure(
             if bbox_inches is None:
                 bbox_inches = rcParams['savefig.bbox']
 
-            if (self.figure.get_constrained_layout() or
+            if (self.figure.get_layout_engine() is not None or
                     bbox_inches == "tight"):
                 # we need to trigger a draw before printing to make sure
                 # CL works.  "tight" also needs a draw to get the right
@@ -2255,8 +2255,8 @@ def print_figure(
             else:
                 _bbox_inches_restore = None
 
-            # we have already done CL above, so turn it off:
-            stack.enter_context(self.figure._cm_set(constrained_layout=False))
+            # we have already done layout above, so turn it off:
+            stack.enter_context(self.figure._cm_set(layout_engine=None))
             try:
                 # _get_renderer may change the figure dpi (as vector formats
                 # force the figure dpi to 72), so we need to set it again here.