Make params to pyplot.tight_layout keyword-only.

anntzer · anntzer · commit 9b304a00c328 · 2020-04-23T22:22:34.000+02:00
This will allow just autogen'ing pyplot.tight_layout with boilerplate.py
after the deprecation elapses (Figure.tight_layout currently has a
`delete_parameter()` on its first parameter, *renderer*; after *that*
deprecation elapses all following parameters become keyword only).

Also some docstring rewordings.
diff --git a/doc/api/api_changes_3.3/deprecations.rst b/doc/api/api_changes_3.3/deprecations.rst
@@ -460,10 +460,11 @@ replaced by calls to ``draw_idle()`` on the corresponding canvas.
 The ``add_checker`` and ``check_update`` methods and ``update_dict`` attribute
 of `.ScalarMappable` are deprecated.
 
-``ColorbarBase`` parameters will become keyword-only
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-All parameters of ``ColorbarBase``, except for the first (*ax*), will become
-keyword-only, consistently with ``Colorbar``.
+`.pyplot.tight_layout` and ``ColorbarBase`` parameters will become keyword-only
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+All parameters of `.pyplot.tight_layout` and all parameters of ``ColorbarBase``
+except for the first (*ax*) will become keyword-only, consistently with
+`.Figure.tight_layout` and ``Colorbar``, respectively.
 
 `.Axes.pie` radius and startangle
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -2414,7 +2414,7 @@ def execute_constrained_layout(self, renderer=None):
     def tight_layout(self, renderer=None, pad=1.08, h_pad=None, w_pad=None,
                      rect=None):
         """
-        Automatically adjust subplot parameters to give specified padding.
+        Adjust the padding between and around subplots.
 
         To exclude an artist on the axes from the bounding box calculation
         that determines the subplot parameters (i.e. legend, or annotation),
@@ -2424,16 +2424,15 @@ def tight_layout(self, renderer=None, pad=1.08, h_pad=None, w_pad=None,
         ----------
         renderer : subclass of `~.backend_bases.RendererBase`, optional
             Defaults to the renderer for the figure.  Deprecated.
-        pad : float, optional
+        pad : float, default: 1.08
             Padding between the figure edge and the edges of subplots,
             as a fraction of the font size.
-        h_pad, w_pad : float, optional
+        h_pad, w_pad : float, default: *pad*
             Padding (height/width) between edges of adjacent subplots,
-            as a fraction of the font size.  Defaults to *pad*.
-        rect : tuple (left, bottom, right, top), optional
-            A rectangle (left, bottom, right, top) in the normalized
-            figure coordinate that the whole subplots area (including
-            labels) will fit into. Default is (0, 0, 1, 1).
+            as a fraction of the font size.
+        rect : tuple (left, bottom, right, top), default: (0, 0, 1, 1)
+            A rectangle in normalized figure coordinates into which the whole
+            subplots area (including labels) will fit.
 
         See Also
         --------
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -1328,22 +1328,23 @@ def subplot_tool(targetfig=None):
     return SubplotTool(targetfig, toolfig)
 
 
+# After deprecation elapses, this can be autogenerated by boilerplate.py.
+@cbook._make_keyword_only("3.3", "pad")
 def tight_layout(pad=1.08, h_pad=None, w_pad=None, rect=None):
     """
-    Automatically adjust subplot parameters to give specified padding.
+    Adjust the padding between and around subplots.
 
     Parameters
     ----------
-    pad : float
+    pad : float, default: 1.08
         Padding between the figure edge and the edges of subplots,
         as a fraction of the font size.
-    h_pad, w_pad : float, optional
+    h_pad, w_pad : float, default: *pad*
         Padding (height/width) between edges of adjacent subplots,
-        as a fraction of the font size.  Defaults to *pad*.
+        as a fraction of the font size.
     rect : tuple (left, bottom, right, top), default: (0, 0, 1, 1)
-        A rectangle (left, bottom, right, top) in the normalized
-        figure coordinate that the whole subplots area (including
-        labels) will fit into.
+        A rectangle in normalized figure coordinates into which the whole
+        subplots area (including labels) will fit.
     """
     gcf().tight_layout(pad=pad, h_pad=h_pad, w_pad=w_pad, rect=rect)
 
