Merge pull request #20470 from kdpenner/legend-handlers

tacaswell · web-flow · commit a734ed298adc · 2022-03-02T23:37:34.000-05:00
ENH: Issues warnings for legend handles without handlers
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -38,6 +38,7 @@
 from matplotlib.collections import (
     Collection, CircleCollection, LineCollection, PathCollection,
     PolyCollection, RegularPolyCollection)
+from matplotlib.text import Text
 from matplotlib.transforms import Bbox, BboxBase, TransformedBbox
 from matplotlib.transforms import BboxTransformTo, BboxTransformFrom
 from matplotlib.offsetbox import (
@@ -740,11 +741,12 @@ def _init_legend_box(self, handles, labels, markerfirst=True):
             handler = self.get_legend_handler(legend_handler_map, orig_handle)
             if handler is None:
                 _api.warn_external(
-                    "Legend does not support {!r} instances.\nA proxy artist "
-                    "may be used instead.\nSee: "
-                    "https://matplotlib.org/users/legend_guide.html"
-                    "#creating-artists-specifically-for-adding-to-the-legend-"
-                    "aka-proxy-artists".format(orig_handle))
+                             "Legend does not support handles for {0} "
+                             "instances.\nA proxy artist may be used "
+                             "instead.\nSee: https://matplotlib.org/"
+                             "stable/tutorials/intermediate/legend_guide.html"
+                             "#controlling-the-legend-entries".format(
+                                 type(orig_handle).__name__))
                 # No handle for this artist, so we just defer to None.
                 handle_list.append(None)
             else:
@@ -1074,14 +1076,14 @@ def _get_legend_handles(axs, legend_handler_map=None):
     for ax in axs:
         handles_original += [
             *(a for a in ax._children
-              if isinstance(a, (Line2D, Patch, Collection))),
+              if isinstance(a, (Line2D, Patch, Collection, Text))),
             *ax.containers]
         # support parasite axes:
         if hasattr(ax, 'parasites'):
             for axx in ax.parasites:
                 handles_original += [
                     *(a for a in axx._children
-                      if isinstance(a, (Line2D, Patch, Collection))),
+                      if isinstance(a, (Line2D, Patch, Collection, Text))),
                     *axx.containers]
 
     handler_map = {**Legend.get_default_handler_map(),
@@ -1091,6 +1093,15 @@ def _get_legend_handles(axs, legend_handler_map=None):
         label = handle.get_label()
         if label != '_nolegend_' and has_handler(handler_map, handle):
             yield handle
+        elif (label not in ['_nolegend_', ''] and
+                not has_handler(handler_map, handle)):
+            _api.warn_external(
+                             "Legend does not support handles for {0} "
+                             "instances.\nSee: https://matplotlib.org/stable/"
+                             "tutorials/intermediate/legend_guide.html"
+                             "#implementing-a-custom-legend-handler".format(
+                                 type(handle).__name__))
+            continue
 
 
 def _get_legend_handles_labels(axs, legend_handler_map=None):
diff --git a/lib/matplotlib/tests/test_legend.py b/lib/matplotlib/tests/test_legend.py
@@ -506,6 +506,15 @@ def test_handler_numpoints():
     ax.legend(numpoints=0.5)
 
 
+def test_text_nohandler_warning():
+    """Test that Text artists with labels raise a warning"""
+    fig, ax = plt.subplots()
+    ax.text(x=0, y=0, s="text", label="label")
+    with pytest.warns(UserWarning) as record:
+        ax.legend()
+    assert len(record) == 1
+
+
 def test_empty_bar_chart_with_legend():
     """Test legend when bar chart is empty with a label."""
     # related to issue #13003. Calling plt.legend() should not
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
@@ -148,6 +148,9 @@ def __init__(self,
         """
         Create a `.Text` instance at *x*, *y* with string *text*.
 
+        While Text accepts the 'label' keyword argument, by default it is not
+        added to the handles of a legend.
+
         Valid keyword arguments are:
 
         %(Text:kwdoc)s
