API: warn if stairs used in way that is likely not desired

tacaswell · tacaswell · commit 03aa5e30dfa9 · 2024-04-05T16:25:15.000-04:00
Closes #26752
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -7194,9 +7194,16 @@ def stairs(self, values, edges=None, *,
             True or an array is passed to *baseline*, a closed
             path is drawn.
 
+            If None, then drawn as an unclosed Path.
+
         fill : bool, default: False
             Whether the area under the step curve should be filled.
 
+            Passing both ``fill=True` and ``baseline=None`` will likely result in
+            undesired filling as the first and last points will be connected
+            with a straight line with the fill between and the stairs.
+
+
         Returns
         -------
         StepPatch : `~matplotlib.patches.StepPatch`
@@ -7234,6 +7241,15 @@ def stairs(self, values, edges=None, *,
                                    fill=fill,
                                    **kwargs)
         self.add_patch(patch)
+        if baseline is None and fill:
+            _api.warn_external(
+                f"Both {baseline=} and {fill=} have been passed. "
+                "Because baseline in None, the Path used to draw the stairs will "
+                "not be closed, thus because fill is True the polygon will be closed "
+                "by drawing an (unstroked) edge from the first to last point.  It is "
+                "very likely that the resulting fill patterns is not the desired "
+                "result."
+            )
         if baseline is None:
             baseline = 0
         if orientation == 'vertical':
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -2342,6 +2342,23 @@ def test_hist_zorder(histtype, zorder):
         assert patch.get_zorder() == zorder
 
 
+def test_stairs_no_baseline_fill_warns():
+    fig, ax = plt.subplots()
+    baseline = None
+    fill = True
+    warn_match = (
+        "Because baseline in None, the Path used to draw the stairs will "
+    )
+    with pytest.warns(UserWarning, match=warn_match):
+        ax.stairs(
+            [4, 5, 1, 0, 2],
+            [1, 2, 3, 4, 5, 6],
+            facecolor="blue",
+            baseline=baseline,
+            fill=fill
+        )
+
+
 @check_figures_equal(extensions=['png'])
 def test_stairs(fig_test, fig_ref):
     import matplotlib.lines as mlines
