Deprecate stem(..., use_line_collection=False)

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.

Author: timhoffm

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.

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

lib/matplotlib/pyplot.py

@@ -2837,8 +2837,9 @@ def stackplot(
 @_copy_docstring_and_deprecators(Axes.stem)
 def stem(
         *args, linefmt=None, markerfmt=None, basefmt=None, bottom=0,
-        label=None, use_line_collection=True, orientation='vertical',
-        data=None):
+        label=None,
+        use_line_collection=_api.deprecation._deprecated_parameter,
+        orientation='vertical', data=None):
     return gca().stem(
         *args, linefmt=linefmt, markerfmt=markerfmt, basefmt=basefmt,
         bottom=bottom, label=label,

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:
+        ax.stem(x, np.cos(x),
+                linefmt='C2-.', markerfmt='k+', basefmt='C1-.', label=' ')
+    else:
+        with pytest.warns(match='deprecated'):
+            ax.stem(x, np.cos(x),
+                    linefmt='C2-.', markerfmt='k+', basefmt='C1-.', label=' ',
+                    use_line_collection=False)
     ax.legend()
 
 
@@ -3868,9 +3873,16 @@ def test_stem_orientation(use_line_collection):
     x = np.linspace(0.1, 2*np.pi, 50)
 
     fig, ax = plt.subplots()
-    ax.stem(x, np.cos(x),
-            linefmt='C2-.', markerfmt='kx', basefmt='C1-.',
-            use_line_collection=use_line_collection, orientation='horizontal')
+    if use_line_collection:
+        ax.stem(x, np.cos(x),
+                linefmt='C2-.', markerfmt='kx', basefmt='C1-.',
+                orientation='horizontal')
+    else:
+        with pytest.warns(match='deprecated'):
+            ax.stem(x, np.cos(x),
+                    linefmt='C2-.', markerfmt='kx', basefmt='C1-.',
+                    use_line_collection=False,
+                    orientation='horizontal')
 
 
 @image_comparison(['hist_stacked_stepfilled_alpha'])