ENH: pass extra kwrags in FigureBase, SubFigure, Figure to set

tacaswell · tacaswell · commit a1b4679194be · 2021-04-29T14:35:15.000-04:00
Consistent with other artists and allows properties controlled by `set_XYZ` to
be set at init time.
diff --git a/doc/users/next_whats_new/figure_kwargs.rst b/doc/users/next_whats_new/figure_kwargs.rst
@@ -0,0 +1,11 @@
+
+Figure init passes 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')
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -181,7 +181,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
@@ -214,6 +214,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"""
@@ -1939,7 +1940,8 @@ def __init__(self, parent, subplotspec, *,
                  facecolor=None,
                  edgecolor=None,
                  linewidth=0.0,
-                 frameon=None):
+                 frameon=None,
+                 **kwargs):
         """
         Parameters
         ----------
@@ -1963,8 +1965,14 @@ def __init__(self, parent, subplotspec, *,
 
         frameon : bool, default: :rc:`figure.frameon`
             If ``False``, suppress drawing the figure background patch.
+
+        Other Parameters
+        ----------------
+        **kwargs : `.Artist` properties, optional
+
+            %(Artist_kwdoc)s
         """
-        super().__init__()
+        super().__init__(**kwargs)
         if facecolor is None:
             facecolor = mpl.rcParams['figure.facecolor']
         if edgecolor is None:
@@ -2147,6 +2155,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
@@ -2188,8 +2197,14 @@ def __init__(self,
             :doc:`/tutorials/intermediate/constrainedlayout_guide`
             for examples.  (Note: does not work with `add_subplot` or
             `~.pyplot.subplot2grid`.)
+
+        Other Parameters
+        ----------------
+        **kwargs : `.Artist` properties, optional
+
+            %(Artist_kwdoc)s
         """
-        super().__init__()
+        super().__init__(**kwargs)
 
         self.callbacks = cbook.CallbackRegistry()
         # Callbacks traditionally associated with the canvas (and exposed with
diff --git a/lib/matplotlib/tests/test_figure.py b/lib/matplotlib/tests/test_figure.py
@@ -1068,3 +1068,11 @@ def test_add_axes_kwargs():
     assert ax1.name == 'rectilinear'
     assert ax1 is not ax
     plt.close()
+
+
+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'
