Deprecate non-string values as legend labels

timhoffm · timhoffm · commit 9b7d171bd725 · 2020-03-14T18:01:44.000+01:00
diff --git a/doc/api/next_api_changes/deprecations.rst b/doc/api/next_api_changes/deprecations.rst
@@ -327,6 +327,10 @@ Support for passing ``None`` as base class to `.axes.subplot_class_factory`,
 ``axes_grid1.parasite_axes.parasite_axes_auxtrans_class_factory`` is deprecated.
 Explicitly pass the correct base ``Axes`` class instead.
 
+Legend labels must be strings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Passing non-string objects as legend labels is deprecated.
+
 ``axes_rgb``
 ~~~~~~~~~~~~
 In :mod:`mpl_toolkits.axes_grid1.axes_rgb`, ``imshow_rgb`` is deprecated (use
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -395,6 +395,11 @@ def __init__(self, parent, handles, labels,
         # trim handles and labels if illegal label...
         _lab, _hand = [], []
         for label, handle in zip(labels, handles):
+            if not isinstance(label, str):
+                cbook.warn_deprecated(
+                   "3.3",
+                   message="Passing non-string objects as legend "
+                           "labels is deprecated.")
             if isinstance(label, str) and label.startswith('_'):
                 cbook._warn_external('The handle {!r} has a label of {!r} '
                                      'which cannot be automatically added to'
diff --git a/lib/matplotlib/tests/test_legend.py b/lib/matplotlib/tests/test_legend.py
@@ -5,6 +5,7 @@
 import numpy as np
 import pytest
 
+from matplotlib.cbook import MatplotlibDeprecationWarning
 from matplotlib.testing.decorators import image_comparison
 import matplotlib.pyplot as plt
 import matplotlib as mpl
@@ -234,6 +235,15 @@ def test_legend_handle_label(self):
             plt.legend(lines, ['hello world'])
         Legend.assert_called_with(plt.gca(), lines, ['hello world'])
 
+    def test_legend_handles_only(self):
+        lines = plt.plot(range(10))
+        with pytest.warns(MatplotlibDeprecationWarning,
+                match="Passing non-string objects as legend labels is "
+                      "deprecated"):
+            # a single arg is interpreted as labels
+            # it's a common error to just pass handles
+            plt.legend(lines)
+
     def test_legend_no_args(self):
         lines = plt.plot(range(10), label='hello world')
         with mock.patch('matplotlib.legend.Legend') as Legend:
