ENH: add title_fontsize to legend

jklymak · jklymak · commit 156131cc29ef · 2018-05-04T11:04:21.000-07:00
diff --git a/doc/users/next_whats_new/legend_title_fontsize_kwarg.rst b/doc/users/next_whats_new/legend_title_fontsize_kwarg.rst
@@ -0,0 +1,9 @@
+Legend now has a title_fontsize kwarg (and rcParam)
+---------------------------------------------------
+
+The title for a `.Figure.legend` and `.Axes.legend` can now have its
+fontsize set via the ``title_fontsize`` kwarg.  There is also a new
+:rc:`legend.title_fontsize`.  Both default to ``None``, which means
+the legend title will have the same fontsize as the axes default fontsize
+(*not* the legend fontsize, set by the ``fontsize`` kwarg or
+:rc:`legend.fontsize`).  
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -333,7 +333,7 @@ def __init__(self, parent, handles, labels,
                                  # box, none use rc
                  shadow=None,
                  title=None,  # set a title for the legend
-
+                 title_fontsize=None,  # set to ax.fontsize if None
                  framealpha=None,  # set frame alpha
                  edgecolor=None,  # frame patch edgecolor
                  facecolor=None,  # frame patch facecolor
@@ -539,7 +539,11 @@ def __init__(self, parent, handles, labels,
             self.get_frame().set_alpha(framealpha)
 
         self._loc = loc
-        self.set_title(title)
+        # figure out title fontsize:
+        if title_fontsize is None:
+            title_fontsize = rcParams['legend.title_fontsize']
+        tprop = FontProperties(size=title_fontsize)
+        self.set_title(title, prop=tprop)
         self._last_fontsize_points = self._fontsize
         self._draggable = None
 
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -420,6 +420,13 @@ def validate_aspect(s):
         raise ValueError('not a valid aspect specification')
 
 
+def validate_fontsize_None(s):
+    if s is None or s == 'None':
+        return None
+    else:
+        return validate_fontsize(s)
+
+
 def validate_fontsize(s):
     fontsizes = ['xx-small', 'x-small', 'small', 'medium', 'large',
                  'x-large', 'xx-large', 'smaller', 'larger']
@@ -1226,6 +1233,7 @@ def _validate_linestyle(ls):
     # the number of points in the legend line for scatter
     'legend.scatterpoints': [1, validate_int],
     'legend.fontsize': ['medium', validate_fontsize],
+    'legend.title_fontsize': [None, validate_fontsize_None],
      # the relative size of legend markers vs. original
     'legend.markerscale': [1.0, validate_float],
     'legend.shadow': [False, validate_bool],
diff --git a/lib/matplotlib/tests/test_legend.py b/lib/matplotlib/tests/test_legend.py
@@ -502,3 +502,11 @@ def test_legend_proper_window_extent():
     leg = ax.legend()
     x02 = leg.get_window_extent(fig.canvas.get_renderer()).x0
     assert pytest.approx(x01*2, 0.1) == x02
+
+
+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)
+    assert leg.get_title().get_fontsize() == 22
diff --git a/matplotlibrc.template b/matplotlibrc.template
@@ -415,6 +415,7 @@ backend      : $TEMPLATE_BACKEND
 #legend.scatterpoints : 1        ## number of scatter points
 #legend.markerscale   : 1.0      ## the relative size of legend markers vs. original
 #legend.fontsize      : medium
+#legend.title_fontsize    : None ## None sets to the same as the default axes.  
 ## Dimensions as fraction of fontsize:
 #legend.borderpad     : 0.4      ## border whitespace
 #legend.labelspacing  : 0.5      ## the vertical space between the legend entries
