Add Figure parameter layout and discourage tight_layout / constrained_layout

timhoffm · jklymak · commit d001ed17c063 · 2021-06-12T22:18:11.000-07: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,12 @@
+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``). 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
@@ -2138,6 +2138,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
@@ -2166,22 +2168,63 @@ 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.
+            Whether to use the tight layout mechanism. See `.set_tight_layout`.
+
+            .. admonition:: Discouraged
+
+                The use of this parameter is discouraged. Please use
+                ``layout='tight'`` instead for the common case
+                ``tight_layout=True`` and use `.set_tight_layout` otherwise.
 
         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'}, 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.
+
+            - 'tight': 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
+            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
@@ -2344,7 +2387,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.
         """
