From 74079d0dcc48a9c5c786f522453bdf304d1fbade Mon Sep 17 00:00:00 2001
From: Thomas A Caswell <tcaswell@gmail.com>
Date: Thu, 29 Apr 2021 14:28:07 -0400
Subject: [PATCH] ENH: pass extra kwrags in FigureBase, SubFigure, Figure to
 set

Consistent with other artists and allows properties controlled by `set_XYZ` to
be set at init time.

Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>
---
 doc/users/next_whats_new/figure_kwargs.rst | 11 ++++++++++
 lib/matplotlib/figure.py                   | 25 ++++++++++++++++++----
 lib/matplotlib/tests/test_figure.py        |  8 +++++++
 3 files changed, 40 insertions(+), 4 deletions(-)
 create mode 100644 doc/users/next_whats_new/figure_kwargs.rst

diff --git a/doc/users/next_whats_new/figure_kwargs.rst b/doc/users/next_whats_new/figure_kwargs.rst
new file mode 100644
index 000000000000..738cb65f972d
--- /dev/null
+++ b/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')
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
index f187868d4fe4..9920c6b22de7 100644
--- a/lib/matplotlib/figure.py
+++ b/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
diff --git a/lib/matplotlib/tests/test_figure.py b/lib/matplotlib/tests/test_figure.py
index ccb1381fa5b5..ff539f58d4fe 100644
--- a/lib/matplotlib/tests/test_figure.py
+++ b/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'