Add Figure parameter layout and discourage tight_layout / constrained_layout

timhoffm · timhoffm · commit b92db60a3cd1 · 2021-04-07T23:17:35.000+02:00
diff --git a/doc/api/next_api_changes/deprecations/19892-TH.rst b/doc/api/next_api_changes/deprecations/19892-TH.rst
@@ -0,0 +1,13 @@
+Discouraged: ``Figure`` parameters ``tight_layout`` and ``constrained_layout``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The ``Figure`` parameters ``tight_layout`` and ``constrained_layout`` are
+triggering competing layout mechanisms and thus should not be used together.
+
+To make the API clearer, we've merged them under the new parameter ``layout``
+with values 'constrained' (equal to ``constrained_layout=True``), 'tight'
+(equal to ``tight_layout=True``) and a dict (equal to calling ``tight_layout``
+with that dict). If given ``layout`` takes precedence.
+
+The use of ``tight_layout`` and ``constrained_layout`` is discouraged in
+favor of ``layout``. However, these parameters will stay available for
+backward compatibility.
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -2123,6 +2123,8 @@ def __init__(self,
                  subplotpars=None,  # rc figure.subplot.*
                  tight_layout=None,  # rc figure.autolayout
                  constrained_layout=None,  # rc figure.constrained_layout.use
+                 *,
+                 layout=None,
                  ):
         """
         Parameters
@@ -2151,22 +2153,67 @@ def __init__(self,
             parameters :rc:`figure.subplot.*` are used.
 
         tight_layout : bool or dict, default: :rc:`figure.autolayout`
-            If ``False`` use *subplotpars*. If ``True`` adjust subplot
-            parameters using `.tight_layout` with default padding.
-            When providing a dict containing the keys ``pad``, ``w_pad``,
-            ``h_pad``, and ``rect``, the default `.tight_layout` paddings
-            will be overridden.
+            This is equal to ``layout='tight'`` or ``layout=dict(...)``.
+
+            .. admonition:: Discouraged
+
+                The use of this parameter is discouraged. Please use
+                ``layout='tight'`` or ``layout=dict(...)`` instead.
 
         constrained_layout : bool, default: :rc:`figure.constrained_layout.use`
-            If ``True`` use constrained layout to adjust positioning of plot
-            elements.  Like ``tight_layout``, but designed to be more
-            flexible.  See
-            :doc:`/tutorials/intermediate/constrainedlayout_guide`
-            for examples.  (Note: does not work with `add_subplot` or
-            `~.pyplot.subplot2grid`.)
+            This is equal to ``layout='constrained'``.
+
+            .. admonition:: Discouraged
+
+                The use of this parameter is discouraged. Please use
+                ``layout='constrained'`` instead.
+
+        layout : {'constrained', 'tight'} or dict, optional
+            The layout mechanism for positioning of plot elements.
+            Supported values:
+
+            - 'constrained': The constrained layout solver usually gives the
+              best layout results and is thus recommended. However, it is
+              computationally expensive and can be slow for complex figures
+              with many elements.
+
+              See :doc:`/tutorials/intermediate/constrainedlayout_guide`
+              for examples.  (Note: does not work with `add_subplot` or
+              `~.pyplot.subplot2grid`.)
+
+            - 'tight' or dict: Use the tight layout mechanism. This is a
+              relatively simple algorithm, that adjusts the subplot parameters
+              so that decorations like tick labels, axis labels and titles
+              have enough space. See `.Figure.set_tight_layout` for further
+              details.
+
+            If not given, fall back to using the parameters *tight_layout* and
+            *constrained_layout*, including their config defaults
+            :rc:`figure.autolayout` and :rc:`figure.constrained_layout.use`.
         """
         super().__init__()
 
+        if layout is not None:
+            if tight_layout is not None:
+                _api.warn_external(
+                    "The Figure parameters 'layout' and 'tight_layout' "
+                    "cannot be used together. Please use 'layout' only.")
+            if constrained_layout is not None:
+                _api.warn_external(
+                    "The Figure parameters 'layout' and 'constrained_layout' "
+                    "cannot be used together. Please use 'layout' only.")
+            if layout == 'constrained':
+                tight_layout = False
+                constrained_layout = True
+            elif layout == 'tight':
+                tight_layout = True
+                constrained_layout = False
+            elif isinstance(layout, dict):
+                tight_layout = layout
+                constrained_layout = False
+            else:
+                raise ValueError(f"Invalid value for 'layout': {layout!r}")
+
         self.callbacks = cbook.CallbackRegistry()
         # Callbacks traditionally associated with the canvas (and exposed with
         # a proxy property), but that actually need to be on the figure for
@@ -2330,7 +2377,7 @@ def set_tight_layout(self, tight):
         ----------
         tight : bool or dict with keys "pad", "w_pad", "h_pad", "rect" or None
             If a bool, sets whether to call `.tight_layout` upon drawing.
-            If ``None``, use the ``figure.autolayout`` rcparam instead.
+            If ``None``, use :rc:`figure.autolayout` instead.
             If a dict, pass it as kwargs to `.tight_layout`, overriding the
             default paddings.
         """
