Deprecate unused canvas parameter to MultiCursor

Closes matplotlib#21496.

Author: timhoffm

doc/api/next_api_changes/deprecations/30737-TH.rst

@@ -0,0 +1,8 @@
+The *canvas* parameter to ``MultiCursor``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+... is deprecated. It has been unused for a while already.
+
+Please remove the parameter and change the call from
+``MultiCursor(canvas, axes)`` to ``MultiCursor(axes)``. Both calls are
+valid throughout the deprecation period.

galleries/examples/widgets/multicursor.py

@@ -26,7 +26,7 @@
 fig, ax3 = plt.subplots()
 ax3.plot(t, s3)
 
-multi = MultiCursor(None, (ax1, ax2, ax3), color='r', lw=1)
+multi = MultiCursor((ax1, ax2, ax3), color='r', lw=1)
 plt.show()
 
 # %%

lib/matplotlib/tests/test_widgets.py

@@ -3,6 +3,7 @@
 import operator
 from unittest import mock
 
+import matplotlib as mpl
 from matplotlib.backend_bases import DrawEvent, KeyEvent, MouseEvent
 import matplotlib.colors as mcolors
 import matplotlib.widgets as widgets
@@ -1680,15 +1681,22 @@ def test_polygon_selector_clear_method(ax):
 
 @pytest.mark.parametrize("horizOn", [False, True])
 @pytest.mark.parametrize("vertOn", [False, True])
-def test_MultiCursor(horizOn, vertOn):
+@pytest.mark.parametrize("with_deprecated_canvas", [False, True])
+def test_MultiCursor(horizOn, vertOn, with_deprecated_canvas):
     fig = plt.figure()
     (ax1, ax3) = fig.subplots(2, sharex=True)
     ax2 = plt.figure().subplots()
 
-    # useblit=false to avoid having to draw the figure to cache the renderer
-    multi = widgets.MultiCursor(
-        None, (ax1, ax2), useblit=False, horizOn=horizOn, vertOn=vertOn
-    )
+    if with_deprecated_canvas:
+        with pytest.warns(mpl.MatplotlibDeprecationWarning, match=r"canvas.*deprecat"):
+            multi = widgets.MultiCursor(
+                None, (ax1, ax2), useblit=False, horizOn=horizOn, vertOn=vertOn
+            )
+    else:
+        # useblit=false to avoid having to draw the figure to cache the renderer
+        multi = widgets.MultiCursor(
+            (ax1, ax2), useblit=False, horizOn=horizOn, vertOn=vertOn
+        )
 
     # Only two of the axes should have a line drawn on them.
     assert len(multi.vlines) == 2

lib/matplotlib/widgets.py

@@ -1989,12 +1989,19 @@ class MultiCursor(Widget):
     Provide a vertical (default) and/or horizontal line cursor shared between
     multiple Axes.
 
+    Call signatures::
+
+        MultiCursor(axes, *, ...)
+        MultiCursor(canvas, axes, *, ...)  # deprecated
+
     For the cursor to remain responsive you must keep a reference to it.
 
     Parameters
     ----------
     canvas : object
-        This parameter is entirely unused and only kept for back-compatibility.
+        This parameter is entirely unused.
+
+        .. deprecated:: 3.11
 
     axes : list of `~matplotlib.axes.Axes`
         The `~.axes.Axes` to attach the cursor to.
@@ -2021,11 +2028,25 @@ class MultiCursor(Widget):
     See :doc:`/gallery/widgets/multicursor`.
     """
 
-    def __init__(self, canvas, axes, *, useblit=True, horizOn=False, vertOn=True,
+    def __init__(self, *args, useblit=True, horizOn=False, vertOn=True,
                  **lineprops):
-        # canvas is stored only to provide the deprecated .canvas attribute;
-        # once it goes away the unused argument won't need to be stored at all.
-        self._canvas = canvas
+        # Deprecation of canvas as the first attribute. When the deprecation exprires:
+        # - change the signature to __init__(self, axes, *, ...)
+        # - delete the "Call signatures" block in the docstring
+        # - delete this block
+        kwargs = {k: lineprops.pop(k)
+                  for k in list(lineprops) if k in ("canvas", "axes")}
+        params = _api.select_matching_signature(
+            [lambda axes: locals(), lambda canvas, axes: locals()], *args, **kwargs)
+        if "canvas" in params:
+            _api.warn_deprecated(
+                "3.11",
+                message="The canvas parameter in MultiCursor is unused and deprecated "
+                "since  %(since)s. Please remove it and call MultiCursor(axes) "
+                "instead of MultiCursor(canvas, axes). The latter will start raising "
+                "an error in %(removal)s"
+            )
+        axes = params["axes"]
 
         self.axes = axes
         self.horizOn = horizOn