Clarify warning about labels with leading underscores.

Replaces and closes matplotlib#17488.

Co-authored-by: Clement Walter <[email protected]>

Author: timhoffm

lib/matplotlib/legend.py

@@ -406,9 +406,9 @@ def val_or_rc(val, rc_name):
         _lab, _hand = [], []
         for label, handle in zip(labels, handles):
             if isinstance(label, str) and label.startswith('_'):
-                _api.warn_external('The handle {!r} has a label of {!r} '
-                                   'which cannot be automatically added to'
-                                   ' the legend.'.format(handle, label))
+                _api.warn_external(f"The label {label!r} of {handle!r} starts "
+                                   "with '_'. It is thus excluded from the "
+                                   "legend.")
             else:
                 _lab.append(label)
                 _hand.append(handle)

lib/matplotlib/tests/test_legend.py

@@ -78,6 +78,20 @@ def test_various_labels():
     ax.legend(numpoints=1, loc='best')
 
 
+def test_legend_label_with_leading_underscore():
+    """
+    Test that artists with labels starting with an underscore are not added to
+    the legend, and that a warning is issued if one tries to add them
+    explicitly.
+    """
+    fig, ax = plt.subplots()
+    line, = ax.plot([0, 1], label='_foo')
+    with pytest.warns(UserWarning,
+                      match=r"starts with '_'.*excluded from the legend."):
+        legend = ax.legend(handles=[line])
+    assert len(legend.legendHandles) == 0
+
+
 @image_comparison(['legend_labels_first.png'], remove_text=True)
 def test_labels_first():
     # test labels to left of markers