Add title_prop keyword to matplotlib.pyplot.legend

smartlixx · smartlixx · commit 4b246ee745f9 · 2021-04-14T22:49:24.000+08:00
diff --git a/doc/users/next_whats_new/legend_title_prop_kwarg.rst b/doc/users/next_whats_new/legend_title_prop_kwarg.rst
@@ -0,0 +1,15 @@
+Legend now has a title_prop kwarg
+-------------------------------------
+
+The title for a `.Figure.legend` and `.Axes.legend` can now have its
+title's font properties set via the ``title_prop`` kwarg, defaults to 
+``None``, which means the legend's title will have the font properties
+as set by the :rc:`legend.title_fontsize`. Through this new kwarg, one
+can set the legend's title font properties through either FontProperties
+or dict, for example:
+
+.. plot::
+
+    fig, ax = plt.subplots(figsize=(4, 3))
+    ax.plot(range(10))
+    ax.legend(title='Points', title_prop={'family': 'serif'}, title_fontsize=22) 
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -237,6 +237,10 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
 title : str or None
     The legend's title. Default is no title (``None``).
 
+title_prop : None or `matplotlib.font_manager.FontProperties` or dict
+    The font properties of the legend's title. If None (default), the current
+    :data:`matplotlib.rcParams` will be used.
+
 title_fontsize : int or {'xx-small', 'x-small', 'small', 'medium', 'large', \
 'x-large', 'xx-large'}, default: :rc:`legend.title_fontsize`
     The font size of the legend's title.
@@ -323,6 +327,7 @@ def __init__(self, parent, handles, labels,
                                  # box, none use rc
                  shadow=None,
                  title=None,  # set a title for the legend
+                 title_prop=None,  # properties for the legend title
                  title_fontsize=None,  # the font size for the title
                  framealpha=None,  # set frame alpha
                  edgecolor=None,  # frame patch edgecolor
@@ -507,10 +512,22 @@ def __init__(self, parent, handles, labels,
         self._loc_used_default = tmp  # ignore changes done by _set_loc
 
         # figure out title fontsize:
-        if title_fontsize is None:
-            title_fontsize = mpl.rcParams['legend.title_fontsize']
-        tprop = FontProperties(size=title_fontsize)
-        self.set_title(title, prop=tprop)
+        if title_prop is None:
+            if title_fontsize is None:
+                title_fontsize = mpl.rcParams["legend.title_fontsize"]
+            self.title_prop = FontProperties(
+                size=title_fontsize)
+        else:
+            self.title_prop = FontProperties._from_any(title_prop)
+            if isinstance(title_prop, dict) and "size" not in title_prop:
+                if title_fontsize is None:
+                    title_fontsize = mpl.rcParams["legend.title_fontsize"]
+                self.title_prop.set_size(title_fontsize)
+            else:
+                if title_fontsize is not None:
+                    self.title_prop.set_size(title_fontsize)
+
+        self.set_title(title, prop=self.title_prop)
         self._draggable = None
 
         # set the text color
diff --git a/lib/matplotlib/tests/test_legend.py b/lib/matplotlib/tests/test_legend.py
@@ -546,10 +546,25 @@ def test_window_extent_cached_renderer():
 
 def test_legend_title_fontsize():
     # test the title_fontsize kwarg
-    fig, ax = plt.subplots()
-    ax.plot(range(10))
-    leg = ax.legend(title='Aardvark', title_fontsize=22)
+    fig, axes = plt.subplots(2, 2, figsize=(8, 6))
+    axes = axes.flat
+    axes[0].plot(range(10))
+    leg = axes[0].legend(title='Aardvark', title_fontsize=22)
     assert leg.get_title().get_fontsize() == 22
+    axes[1].plot(range(10))
+    leg2 = axes[1].legend(title='Aardvark',
+                          title_prop={'family': 'serif', 'size': 22})
+    assert leg2.get_title().get_fontsize() == 22
+    axes[2].plot(range(10))
+    leg3 = axes[2].legend(title='Aardvark',
+                          title_prop={'family': 'serif'},
+                          title_fontsize=22)
+    assert leg3.get_title().get_fontsize() == 22
+    axes[3].plot(range(10))
+    leg4 = axes[3].legend(title='Aardvark',
+                          title_prop={'family': 'serif', 'size': 10},
+                          title_fontsize=22)
+    assert leg4.get_title().get_fontsize() == 22
 
 
 def test_legend_labelcolor_single():
