Deprecate Toolbar.press/release; add helper to find overridden methods.

anntzer · anntzer · commit fb199bafc74f · 2020-04-29T19:59:39.000+02:00
Even though the docs stated that NavigationToolbar2.press/.release were
called whenever a mouse button was pressed/released, these methods were
in fact *only* called when this button press/release occurred at the
beginning/end of an interactive pan or zoom; even then they were only
used by the wx backend to set up some stuff at the beginning/end of a
zoom.

Instead wx can just override press_zoom and release_zoom to insert
its additional code, and we can deprecate the confusingly named
.press() and .release() (in general, users should just connect
to "button_press/release_event" if they want all such events
anyways).  As usual, we need to not only deprecate the methods on the
NavigationToolbar2 class, but also detect if third-party subclasses
have overridden them and also warn in that case.  This pattern
(warn-if-overridden-by-subclass) occurs now quite a few times in the
codebase, so add a helper (_deprecate_method_override) to handle that.
diff --git a/doc/api/api_changes_3.3/deprecations.rst b/doc/api/api_changes_3.3/deprecations.rst
@@ -377,6 +377,14 @@ NavigationToolbar2QT.ctx
 ~~~~~~~~~~~~~~~~~~~~~~~~
 This attribute is deprecated.
 
+NavigationToolbar2.press and .release
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+These methods were called when pressing or releasing a mouse button,
+but *only* when an interactive pan or zoom was occurring (contrary to
+what the docs stated).  They are deprecated; if you write a backend
+which needs to customize such events, please directly override
+``press_pan``/``press_zoom``/``release_pan``/``release_zoom`` instead.
+
 Path helpers in :mod:`.bezier`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -2688,14 +2688,6 @@ class NavigationToolbar2:
       :meth:`draw_rubberband` (optional)
          draw the zoom to rect "rubberband" rectangle
 
-      :meth:`press`  (optional)
-         whenever a mouse button is pressed, you'll be notified with
-         the event
-
-      :meth:`release` (optional)
-         whenever a mouse button is released, you'll be notified with
-         the event
-
       :meth:`set_message` (optional)
          display message
 
@@ -2914,6 +2906,7 @@ def pan(self, *args):
             a.set_navigate_mode(self.mode)
         self.set_message(self.mode)
 
+    @cbook.deprecated("3.3")
     def press(self, event):
         """Called whenever a mouse button is pressed."""
 
@@ -2937,7 +2930,12 @@ def press_pan(self, event):
                 self.canvas.mpl_disconnect(self._id_drag)
                 self._id_drag = self.canvas.mpl_connect(
                     'motion_notify_event', self.drag_pan)
-        self.press(event)
+        press = cbook._deprecate_method_override(
+            __class__.press, self, since="3.3", message="Calling an "
+            "overridden press() at pan start is deprecated since %(since)s "
+            "and will be removed %(removal)s; override press_pan() instead.")
+        if press is not None:
+            press(event)
 
     def press_zoom(self, event):
         """Callback for mouse button press in zoom to rect mode."""
@@ -2959,7 +2957,12 @@ def press_zoom(self, event):
             "axes": axes,
             "cid": id_zoom,
         }
-        self.press(event)
+        press = cbook._deprecate_method_override(
+            __class__.press, self, since="3.3", message="Calling an "
+            "overridden press() at zoom start is deprecated since %(since)s "
+            "and will be removed %(removal)s; override press_zoom() instead.")
+        if press is not None:
+            press(event)
 
     def push_current(self):
         """Push the current view limits and position onto the stack."""
@@ -2972,6 +2975,7 @@ def push_current(self):
                  for ax in self.canvas.figure.axes}))
         self.set_history_buttons()
 
+    @cbook.deprecated("3.3")
     def release(self, event):
         """Callback for mouse button release."""
 
@@ -2990,7 +2994,12 @@ def release_pan(self, event):
         self._xypress = []
         self._button_pressed = None
         self.push_current()
-        self.release(event)
+        release = cbook._deprecate_method_override(
+            __class__.press, self, since="3.3", message="Calling an "
+            "overridden release() at pan stop is deprecated since %(since)s "
+            "and will be removed %(removal)s; override release_pan() instead.")
+        if release is not None:
+            release(event)
         self._draw()
 
     def drag_pan(self, event):
@@ -3033,7 +3042,13 @@ def release_zoom(self, event):
             if ((abs(x - start_x) < 5 and event.key != "y") or
                     (abs(y - start_y) < 5 and event.key != "x")):
                 self._xypress = None
-                self.release(event)
+                release = cbook._deprecate_method_override(
+                    __class__.press, self, since="3.3", message="Calling an "
+                    "overridden release() at zoom stop is deprecated since "
+                    "%(since)s and will be removed %(removal)s; override "
+                    "release_zoom() instead.")
+                if release is not None:
+                    release(event)
                 self._draw()
                 return
 
@@ -3052,7 +3067,13 @@ def release_zoom(self, event):
         self._zoom_info = None
 
         self.push_current()
-        self.release(event)
+        release = cbook._deprecate_method_override(
+            __class__.press, self, since="3.3", message="Calling an "
+            "overridden release() at zoom stop is deprecated since %(since)s "
+            "and will be removed %(removal)s; override release_zoom() "
+            "instead.")
+        if release is not None:
+            release(event)
 
     @cbook.deprecated("3.3", alternative="toolbar.canvas.draw_idle()")
     def draw(self):
diff --git a/lib/matplotlib/backends/backend_wx.py b/lib/matplotlib/backends/backend_wx.py
@@ -1202,7 +1202,8 @@ def set_cursor(self, cursor):
         self.canvas.SetCursor(cursor)
         self.canvas.Update()
 
-    def press(self, event):
+    def press_zoom(self, event):
+        super().press_zoom(event)
         if self.mode.name == 'ZOOM':
             if not self.retinaFix:
                 self.wxoverlay = wx.Overlay()
@@ -1214,7 +1215,8 @@ def press(self, event):
                     self.zoomStartY = event.ydata
                     self.zoomAxes = event.inaxes
 
-    def release(self, event):
+    def release_zoom(self, event):
+        super().release_zoom(event)
         if self.mode.name == 'ZOOM':
             # When the mouse is released we reset the overlay and it
             # restores the former content to the window.
diff --git a/lib/matplotlib/cbook/__init__.py b/lib/matplotlib/cbook/__init__.py
@@ -31,6 +31,7 @@
 from .deprecation import (
     deprecated, warn_deprecated,
     _rename_parameter, _delete_parameter, _make_keyword_only,
+    _deprecate_method_override,
     _suppress_matplotlib_deprecation_warning,
     MatplotlibDeprecationWarning, mplDeprecation)
 
diff --git a/lib/matplotlib/cbook/deprecation.py b/lib/matplotlib/cbook/deprecation.py
@@ -429,6 +429,31 @@ def wrapper(*args, **kwargs):
     return wrapper
 
 
+def _deprecate_method_override(method, obj, **kwargs):
+    """
+    Return ``obj.method`` with a deprecation if it was overridden, else None.
+
+    Parameters
+    ----------
+    method
+        An unbound method, i.e. an expression of the form
+        ``Class.method_name``.  Remember that within the body of a method, one
+        can always use ``__class__`` to refer to the class that is currently
+        being defined.
+    obj
+        An object of the class where *method* is defined.
+    **kwargs
+        Additional parameters passed to `warn_deprecated` to generate the
+        deprecation warning; must at least include the "since" key.
+    """
+    name = method.__name__
+    bound_method = getattr(obj, name)
+    if bound_method != method.__get__(obj):
+        warn_deprecated(**{"name": name, "obj_type": "method", **kwargs})
+        return bound_method
+    return None
+
+
 @contextlib.contextmanager
 def _suppress_matplotlib_deprecation_warning():
     with warnings.catch_warnings():
