Deprecate backend_tools.SetCursorBase.set_cursor.

Which is now replaced by `FigureCanvasBase.set_cursor`.

Author: QuLogic

doc/api/next_api_changes/deprecations/20620-ES.rst

@@ -1,4 +1,18 @@
-``NavigationToolbar2.set_cursor``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``NavigationToolbar2.set_cursor`` and ``backend_tools.SetCursorBase.set_cursor``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Instead, use the `.FigureCanvasBase.set_cursor` method on the canvas (available
 as the ``canvas`` attribute on the toolbar or the Figure.)
+
+``backend_tools.SetCursorBase`` and subclasses
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``backend_tools.SetCursorBase`` was subclassed to provide backend-specific
+implementations of ``set_cursor``. As that is now deprecated, the subclassing
+is no longer necessary. Consequently, the following subclasses are also
+deprecated:
+
+- ``matplotlib.backends.backend_gtk3.SetCursorGTK3``
+- ``matplotlib.backends.backend_qt5.SetCursorQt``
+- ``matplotlib.backends._backend_tk.SetCursorTk``
+- ``matplotlib.backends.backend_wx.SetCursorWx``
+
+Instead, use the `.backend_tools.ToolSetCursor` class.

lib/matplotlib/backend_managers.py

@@ -254,6 +254,16 @@ def add_tool(self, name, tool, *args, **kwargs):
                                'exists, not added')
             return self._tools[name]
 
+        if name == 'cursor' and tool_cls != tools.SetCursorBase:
+            _api.warn_deprecated("3.5",
+                                 message="Overriding ToolSetCursor with "
+                                 f"{tool_cls.__qualname__} was only "
+                                 "necessary to provide the .set_cursor() "
+                                 "method, which is deprecated since "
+                                 "%(since)s and will be removed "
+                                 "%(removal)s. Please report this to the "
+                                 f"{tool_cls.__module__} author.")
+
         tool_obj = tool_cls(self, name, *args, **kwargs)
         self._tools[name] = tool_obj
 

lib/matplotlib/backend_tools.py

@@ -22,7 +22,7 @@
 
 import matplotlib as mpl
 from matplotlib._pylab_helpers import Gcf
-from matplotlib import cbook
+from matplotlib import _api, cbook
 
 
 class Cursors(enum.IntEnum):  # Must subclass int for the macOS backend.
@@ -277,13 +277,17 @@ def _set_cursor_cbk(self, event):
             self.canvas.set_cursor(self._default_cursor)
             self._last_cursor = self._default_cursor
 
+    @_api.deprecated("3.5", alternative="figure.canvas.set_cursor")
     def set_cursor(self, cursor):
         """
         Set the cursor.
-
-        This method has to be implemented per backend.
         """
-        raise NotImplementedError
+        self.canvas.set_cursor(cursor)
+
+
+# This exists solely for deprecation warnings; remove with
+# SetCursorBase.set_cursor.
+ToolSetCursor = SetCursorBase
 
 
 class ToolCursorPosition(ToolBase):

lib/matplotlib/backends/_backend_tk.py

@@ -794,6 +794,7 @@ def remove_rubberband(self):
             del self.lastrect
 
 
+@_api.deprecated("3.5", alternative="ToolSetCursor")
 class SetCursorTk(backend_tools.SetCursorBase):
     def set_cursor(self, cursor):
         NavigationToolbar2Tk.set_cursor(
@@ -907,7 +908,6 @@ def trigger(self, *args):
 
 backend_tools.ToolSaveFigure = SaveFigureTk
 backend_tools.ToolConfigureSubplots = ConfigureSubplotsTk
-backend_tools.ToolSetCursor = SetCursorTk
 backend_tools.ToolRubberband = RubberbandTk
 backend_tools.ToolHelp = HelpTk
 backend_tools.ToolCopyToClipboard = backend_tools.ToolCopyToClipboardBase

lib/matplotlib/backends/backend_gtk3.py

@@ -718,6 +718,7 @@ class PseudoToolbar:
         return NavigationToolbar2GTK3.save_figure(PseudoToolbar())
 
 
+@_api.deprecated("3.5", alternative="ToolSetCursor")
 class SetCursorGTK3(backend_tools.SetCursorBase):
     def set_cursor(self, cursor):
         NavigationToolbar2GTK3.set_cursor(
@@ -851,7 +852,6 @@ def error_msg_gtk(msg, parent=None):
 
 backend_tools.ToolSaveFigure = SaveFigureGTK3
 backend_tools.ToolConfigureSubplots = ConfigureSubplotsGTK3
-backend_tools.ToolSetCursor = SetCursorGTK3
 backend_tools.ToolRubberband = RubberbandGTK3
 backend_tools.ToolHelp = HelpGTK3
 backend_tools.ToolCopyToClipboard = ToolCopyToClipboardGTK3

lib/matplotlib/backends/backend_qt5.py

@@ -932,6 +932,7 @@ def trigger(self, *args):
             self._make_classic_style_pseudo_toolbar())
 
 
+@_api.deprecated("3.5", alternative="ToolSetCursor")
 class SetCursorQt(backend_tools.SetCursorBase):
     def set_cursor(self, cursor):
         NavigationToolbar2QT.set_cursor(
@@ -961,7 +962,6 @@ def trigger(self, *args, **kwargs):
 
 backend_tools.ToolSaveFigure = SaveFigureQt
 backend_tools.ToolConfigureSubplots = ConfigureSubplotsQt
-backend_tools.ToolSetCursor = SetCursorQt
 backend_tools.ToolRubberband = RubberbandQt
 backend_tools.ToolHelp = HelpQt
 backend_tools.ToolCopyToClipboard = ToolCopyToClipboardQT

lib/matplotlib/backends/backend_wx.py

@@ -1282,6 +1282,7 @@ def trigger(self, *args):
             self._make_classic_style_pseudo_toolbar())
 
 
+@_api.deprecated("3.5", alternative="ToolSetCursor")
 class SetCursorWx(backend_tools.SetCursorBase):
     def set_cursor(self, cursor):
         NavigationToolbar2Wx.set_cursor(
@@ -1363,7 +1364,6 @@ def trigger(self, *args, **kwargs):
 
 backend_tools.ToolSaveFigure = SaveFigureWx
 backend_tools.ToolConfigureSubplots = ConfigureSubplotsWx
-backend_tools.ToolSetCursor = SetCursorWx
 backend_tools.ToolRubberband = RubberbandWx
 backend_tools.ToolHelp = HelpWx
 backend_tools.ToolCopyToClipboard = ToolCopyToClipboardWx