Merge pull request matplotlib#17137 from anntzer/pressrelease

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

Author: QuLogic

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`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

lib/matplotlib/axis.py

@@ -174,13 +174,13 @@ def __init__(self, axes, loc, label=None,
                            ("_get_gridline", "gridline"),
                            ("_get_text1", "label1"),
                            ("_get_text2", "label2")]:
-            if getattr(self, meth) != getattr(Tick, meth).__get__(self):
-                cbook.warn_deprecated(
-                    "3.3", message=f"Relying on {meth} to initialize "
-                    f"Tick.{attr} is deprecated since %(since)s and will not "
-                    f"work %(removal)s; please directly set the attribute in "
-                    "the subclass' __init__ instead.")
-                setattr(self, attr, getattr(self, meth)())
+            overridden_method = cbook._deprecate_method_override(
+                getattr(__class__, meth), self, since="3.3", message="Relying "
+                f"on {meth} to initialize Tick.{attr} is deprecated since "
+                f"%(since)s and will not work %(removal)s; please directly "
+                f"set the attribute in the subclass' __init__ instead.")
+            if overridden_method:
+                setattr(self, attr, overridden_method())
         for artist in [self.tick1line, self.tick2line, self.gridline,
                        self.label1, self.label2]:
             self._set_artist_props(artist)

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):

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.

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)
 

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():

lib/matplotlib/offsetbox.py

@@ -1700,15 +1700,10 @@ def __init__(self, ref_artist, use_blit=False):
 
         if not ref_artist.pickable():
             ref_artist.set_picker(True)
-        with cbook._suppress_matplotlib_deprecation_warning():
-            if self.artist_picker != DraggableBase.artist_picker.__get__(self):
-                overridden_picker = self.artist_picker
-            else:
-                overridden_picker = None
+        overridden_picker = cbook._deprecate_method_override(
+            __class__.artist_picker, self, since="3.3",
+            addendum="Directly set the artist's picker if desired.")
         if overridden_picker is not None:
-            cbook.warn_deprecated(
-                "3.3", name="artist_picker", obj_type="method",
-                addendum="Directly set the artist's picker if desired.")
             ref_artist.set_picker(overridden_picker)
         self.cids = [c2, c3]