Deprecate stem(..., use_line_collection=False)

timhoffm · timhoffm · commit 2282d4b21584 · 2022-06-19T20:59:26.000+02:00
as suggested in a75c716 > We could consider deprecating use_line_collection later (as it's > basically an artefact of the transition), though there's no real hurry > for it. The old non-linecollection way handles the presence of markers differently. In the interest of simplification, we should deprecate it. I expect that it's barely used because users would have to explicitly opt-in to the old behavior.
diff --git a/doc/api/next_api_changes/deprecations/23302-TH.rst b/doc/api/next_api_changes/deprecations/23302-TH.rst
@@ -0,0 +1,4 @@
+``stem(..., use_line_collection=False)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+... is deprecated with no replacement. This was compatibility fallback to a
+former more inefficient representation of the stem lines.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -2804,6 +2804,7 @@ def broken_barh(self, xranges, yrange, **kwargs):
         return col
 
     @_preprocess_data()
+    @_api.delete_parameter("3.6", "use_line_collection")
     def stem(self, *args, linefmt=None, markerfmt=None, basefmt=None, bottom=0,
              label=None, use_line_collection=True, orientation='vertical'):
         """
@@ -2870,11 +2871,12 @@ def stem(self, *args, linefmt=None, markerfmt=None, basefmt=None, bottom=0,
             The label to use for the stems in legends.
 
         use_line_collection : bool, default: True
+            *Deprecated since 3.6*
+
             If ``True``, store and plot the stem lines as a
             `~.collections.LineCollection` instead of individual lines, which
             significantly increases performance.  If ``False``, defaults to the
-            old behavior of using a list of `.Line2D` objects.  This parameter
-            may be deprecated in the future.
+            old behavior of using a list of `.Line2D` objects.
 
         data : indexable object, optional
             DATA_PARAMETER_PLACEHOLDER
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -3826,9 +3826,14 @@ def test_stem(use_line_collection):
     fig, ax = plt.subplots()
     # Label is a single space to force a legend to be drawn, but to avoid any
     # text being drawn
-    ax.stem(x, np.cos(x),
-            linefmt='C2-.', markerfmt='k+', basefmt='C1-.', label=' ',
-            use_line_collection=use_line_collection)
+    if use_line_collection:
+        with pytest.warns(match='deprecated'):
+            ax.stem(x, np.cos(x),
+                linefmt='C2-.', markerfmt='k+', basefmt='C1-.', label=' ',
+                use_line_collection=True)
+    else:
+        ax.stem(x, np.cos(x),
+            linefmt='C2-.', markerfmt='k+', basefmt='C1-.', label=' ')
     ax.legend()
 
 
