Merge pull request matplotlib#26190 from anntzer/_l

Deprecate removal of explicit legend handles whose label starts with _.

Author: timhoffm

doc/api/next_api_changes/deprecations/26190-AL.rst

@@ -0,0 +1,7 @@
+Artists explicitly passed in will no longer be filtered by legend() based on their label
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Currently, artists explicitly passed to ``legend(handles=[...])`` are filtered
+out if their label starts with an underscore.  This behavior is deprecated;
+explicitly filter out such artists
+(``[art for art in artists if not art.get_label().startswith('_')]``) if
+necessary.

lib/matplotlib/legend.py

@@ -465,9 +465,12 @@ 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(f"The label {label!r} of {handle!r} starts "
-                                   "with '_'. It is thus excluded from the "
-                                   "legend.")
+                _api.warn_deprecated("3.8", message=(
+                    "An artist whose label starts with an underscore was passed to "
+                    "legend(); such artists will no longer be ignored in the future.  "
+                    "To suppress this warning, explicitly filter out such artists, "
+                    "e.g. with `[art for art in artists if not "
+                    "art.get_label().startswith('_')]`."))
             else:
                 _lab.append(label)
                 _hand.append(handle)

lib/matplotlib/tests/test_legend.py

@@ -17,7 +17,7 @@
 import matplotlib.lines as mlines
 from matplotlib.legend_handler import HandlerTuple
 import matplotlib.legend as mlegend
-from matplotlib import rc_context
+from matplotlib import _api, rc_context
 from matplotlib.font_manager import FontProperties
 
 
@@ -144,8 +144,7 @@ def test_legend_label_with_leading_underscore():
     """
     fig, ax = plt.subplots()
     line, = ax.plot([0, 1], label='_foo')
-    with pytest.warns(UserWarning,
-                      match=r"starts with '_'.*excluded from the legend."):
+    with pytest.warns(_api.MatplotlibDeprecationWarning, match="with an underscore"):
         legend = ax.legend(handles=[line])
     assert len(legend.legend_handles) == 0