Merge pull request matplotlib#20115 from tacaswell/enh_figure_kwargs

Author: timhoffm

doc/users/next_whats_new/figure_kwargs.rst

@@ -0,0 +1,11 @@
+
+Figure init passes keyword arguments through to set
+---------------------------------------------------
+
+Similar to many other sub-classes of `~.Artist`, `~.FigureBase`, `~.SubFigure`,
+and `~.Figure` will now pass any additional keyword arguments to `~.Artist.set`
+to allow properties of the newly created object to be set at init time.  For
+example ::
+
+  from matplotlib.figure import Figure
+  fig = Figure(label='my figure')

lib/matplotlib/figure.py

@@ -184,7 +184,7 @@ class FigureBase(Artist):
     Base class for `.figure.Figure` and `.figure.SubFigure` containing the
     methods that add artists to the figure or subfigure, create Axes, etc.
     """
-    def __init__(self):
+    def __init__(self, **kwargs):
         super().__init__()
         # remove the non-figure artist _axes property
         # as it makes no sense for a figure to be _in_ an axes
@@ -217,6 +217,7 @@ def __init__(self):
         self.subfigs = []
         self.stale = True
         self.suppressComposite = None
+        self.set(**kwargs)
 
     def _get_draw_artists(self, renderer):
         """Also runs apply_aspect"""
@@ -1923,6 +1924,7 @@ def _set_artist_props(self, a):
         a.set_transform(self.transSubfigure)
 
 
+@docstring.interpd
 class SubFigure(FigureBase):
     """
     Logical figure that can be placed inside a figure.
@@ -1945,7 +1947,8 @@ def __init__(self, parent, subplotspec, *,
                  facecolor=None,
                  edgecolor=None,
                  linewidth=0.0,
-                 frameon=None):
+                 frameon=None,
+                 **kwargs):
         """
         Parameters
         ----------
@@ -1969,8 +1972,14 @@ def __init__(self, parent, subplotspec, *,
 
         frameon : bool, default: :rc:`figure.frameon`
             If ``False``, suppress drawing the figure background patch.
+
+        Other Parameters
+        ----------------
+        **kwargs : `.SubFigure` properties, optional
+
+            %(SubFigure:kwdoc)s
         """
-        super().__init__()
+        super().__init__(**kwargs)
         if facecolor is None:
             facecolor = mpl.rcParams['figure.facecolor']
         if edgecolor is None:
@@ -2114,6 +2123,7 @@ def draw(self, renderer):
             self.stale = False
 
 
+@docstring.interpd
 class Figure(FigureBase):
     """
     The top level container for all the plot elements.
@@ -2154,6 +2164,7 @@ def __init__(self,
                  subplotpars=None,  # rc figure.subplot.*
                  tight_layout=None,  # rc figure.autolayout
                  constrained_layout=None,  # rc figure.constrained_layout.use
+                 **kwargs
                  ):
         """
         Parameters
@@ -2195,8 +2206,14 @@ def __init__(self,
             :doc:`/tutorials/intermediate/constrainedlayout_guide`
             for examples.  (Note: does not work with `add_subplot` or
             `~.pyplot.subplot2grid`.)
+
+        Other Parameters
+        ----------------
+        **kwargs : `.Figure` properties, optional
+
+            %(Figure:kwdoc)s
         """
-        super().__init__()
+        super().__init__(**kwargs)
 
         self.callbacks = cbook.CallbackRegistry()
         # Callbacks traditionally associated with the canvas (and exposed with

lib/matplotlib/tests/test_figure.py

@@ -1110,3 +1110,11 @@ def test_waitforbuttonpress(recwarn):  # recwarn undoes warn filters at exit.
     assert fig.waitforbuttonpress() is True
     Timer(.1, fig.canvas.button_press_event, (0, 0, 1)).start()
     assert fig.waitforbuttonpress() is False
+
+
+def test_kwargs_pass():
+    fig = Figure(label='whole Figure')
+    sub_fig = fig.subfigures(1, 1, label='sub figure')
+
+    assert fig.get_label() == 'whole Figure'
+    assert sub_fig.get_label() == 'sub figure'