Update handling of sequence labels for plot

rcomer · rcomer · commit 630ebba5b39f · 2024-02-10T14:02:12.000Z
diff --git a/doc/api/next_api_changes/behavior/27767-REC.rst b/doc/api/next_api_changes/behavior/27767-REC.rst
@@ -0,0 +1,7 @@
+Legend labels for ``plot``
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Previously if a sequence was passed to the *label* parameter of `~.Axes.plot` when
+plotting a single dataset, the sequence was automatically cast to string for the legend
+label.  Now, if the sequence has only one element, that element will be the legend
+label.  To keep the old behavior, cast the sequence to string before passing.
diff --git a/doc/api/next_api_changes/deprecations/27767-REC.rst b/doc/api/next_api_changes/deprecations/27767-REC.rst
@@ -0,0 +1,9 @@
+Legend labels for ``plot``
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Previously if a sequence was passed to the *label* parameter of `~.Axes.plot` when
+plotting a single dataset, the sequence was automatically cast to string for the legend
+label.  This behavior is now deprecated and in future will error if the sequence length
+is not one (consistent with multi-dataset behavior, where the number of elements must
+match the number of datasets).  To keep the old behavior, cast the sequence to string
+before passing.
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -513,11 +513,19 @@ def _plot_args(self, axes, tup, kwargs, *,
 
         label = kwargs.get('label')
         n_datasets = max(ncx, ncy)
-        if n_datasets > 1 and not cbook.is_scalar_or_string(label):
+        if not cbook.is_scalar_or_string(label):
             if len(label) != n_datasets:
-                raise ValueError(f"label must be scalar or have the same "
-                                 f"length as the input data, but found "
-                                 f"{len(label)} for {n_datasets} datasets.")
+                if n_datasets > 1:
+                    raise ValueError(f"label must be scalar or have the same "
+                                     f"length as the input data, but found "
+                                     f"{len(label)} for {n_datasets} datasets.")
+                else:
+                    msg = (f'Passing label as a length {len(label)} sequence when '
+                            'plotting a single dataset is deprecated in Matplotlib 3.9 '
+                            'and will error in 3.11.  To keep the current behavior, '
+                            'cast the sequence to string before passing.')
+                    _api.warn_deprecated('3.9', message=msg)
+                    label = [label]
             labels = label
         else:
             labels = [label] * n_datasets
diff --git a/lib/matplotlib/tests/test_legend.py b/lib/matplotlib/tests/test_legend.py
@@ -1197,12 +1197,22 @@ def test_plot_single_input_multiple_label(label_array):
     x = [1, 2, 3]
     y = [2, 5, 6]
     fig, ax = plt.subplots()
-    ax.plot(x, y, label=label_array)
+    with pytest.warns(mpl.MatplotlibDeprecationWarning,
+                      match='Passing label as a length 2 sequence'):
+        ax.plot(x, y, label=label_array)
     leg = ax.legend()
     assert len(leg.get_texts()) == 1
     assert leg.get_texts()[0].get_text() == str(label_array)
 
 
+def test_plot_single_input_list_label():
+    fig, ax = plt.subplots()
+    ax.plot([[0], [1]], label=['A'])
+    leg = ax.legend()
+    assert len(leg.get_texts()) == 1
+    assert leg.get_texts()[0].get_text() == 'A'
+
+
 def test_plot_multiple_label_incorrect_length_exception():
     # check that exception is raised if multiple labels
     # are given, but number of on labels != number of lines
