Skip to content

Deprecate unused canvas parameter to MultiCursor #30737

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
efiring merged 2 commits into from
Dec 18, 2025
Merged

Deprecate unused canvas parameter to MultiCursor #30737

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1c6ccce
Deprecate unused canvas parameter to MultiCursor
timhoffm Nov 9, 2025
d798256
Update lib/matplotlib/widgets.py
greglucas Dec 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions doc/api/next_api_changes/deprecations/30737-TH.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 1 addition & 1 deletion galleries/examples/widgets/multicursor.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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()

# %%
Expand Down
18 changes: 13 additions & 5 deletions lib/matplotlib/tests/test_widgets.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
31 changes: 26 additions & 5 deletions lib/matplotlib/widgets.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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 expires:
# - 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
Expand Down
Loading