Merge pull request #15237 from anntzer/widgets

timhoffm · web-flow · commit 30ee9390920b · 2019-09-10T11:08:47.000+02:00
Cleanup widgets.py.
diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
@@ -78,30 +78,28 @@ def get_active(self):
         return self._active
 
     # set_active is overridden by SelectorWidgets.
-    active = property(get_active, lambda self, active: self.set_active(active),
-                      doc="Is the widget active?")
+    active = property(get_active, set_active, doc="Is the widget active?")
 
     def ignore(self, event):
-        """Return True if event should be ignored.
+        """
+        Return whether *event* should be ignored.
 
-        This method (or a version of it) should be called at the beginning
-        of any event callback.
+        This method should be called at the beginning of any event callback.
         """
         return not self.active
 
 
 class AxesWidget(Widget):
-    """Widget that is connected to a single
-    :class:`~matplotlib.axes.Axes`.
+    """
+    Widget that is connected to a single `~matplotlib.axes.Axes`.
 
     To guarantee that the widget remains responsive and not garbage-collected,
     a reference to the object should be maintained by the user.
 
     This is necessary because the callback registry
     maintains only weak-refs to the functions, which are member
     functions of the widget.  If there are no references to the widget
-    object it may be garbage collected which will disconnect the
-    callbacks.
+    object it may be garbage collected which will disconnect the callbacks.
 
     Attributes
     ----------
@@ -118,7 +116,8 @@ def __init__(self, ax):
         self.cids = []
 
     def connect_event(self, event, callback):
-        """Connect callback with an event.
+        """
+        Connect callback with an event.
 
         This should be used in lieu of `figure.canvas.mpl_connect` since this
         function stores callback ids for later clean up.
@@ -137,7 +136,7 @@ class Button(AxesWidget):
     A GUI neutral button.
 
     For the button to remain responsive you must keep a reference to it.
-    Call :meth:`on_clicked` to connect to the button.
+    Call `.on_clicked` to connect to the button.
 
     Attributes
     ----------
@@ -158,18 +157,13 @@ def __init__(self, ax, label, image=None,
         ----------
         ax : `~matplotlib.axes.Axes`
             The `~.axes.Axes` instance the button will be placed into.
-
         label : str
             The button text. Accepts string.
-
-        image : array, mpl image, Pillow Image
+        image : array-like or PIL image
             The image to place in the button, if not *None*.
-            Can be any legal arg to imshow (numpy array,
-            matplotlib Image instance, or Pillow Image).
-
+            Supported inputs are the same as for `.Axes.imshow`.
         color : color
             The color of the button when not activated.
-
         hovercolor : color
             The color of the button when the mouse is over it.
         """
@@ -198,24 +192,20 @@ def __init__(self, ax, label, image=None,
         self._lastcolor = color
 
     def _click(self, event):
-        if self.ignore(event):
-            return
-        if event.inaxes != self.ax:
-            return
-        if not self.eventson:
+        if (self.ignore(event)
+                or event.inaxes != self.ax
+                or not self.eventson):
             return
         if event.canvas.mouse_grabber != self.ax:
             event.canvas.grab_mouse(self.ax)
 
     def _release(self, event):
-        if self.ignore(event):
-            return
-        if event.canvas.mouse_grabber != self.ax:
+        if (self.ignore(event)
+                or event.canvas.mouse_grabber != self.ax):
             return
         event.canvas.release_mouse(self.ax)
-        if not self.eventson:
-            return
-        if event.inaxes != self.ax:
+        if (not self.eventson
+                or event.inaxes != self.ax):
             return
         for cid, func in self.observers.items():
             func(event)
@@ -622,9 +612,8 @@ def set_active(self, index):
             Raises ValueError if *index* is invalid.
 
         Callbacks will be triggered if :attr:`eventson` is True.
-
         """
-        if 0 > index >= len(self.labels):
+        if not 0 <= index < len(self.labels):
             raise ValueError("Invalid CheckButton index: %d" % index)
 
         l1, l2 = self.lines[index]
@@ -823,12 +812,12 @@ def _keypress(self, event):
                 self.cursor_index = 0
             elif key == "end":
                 self.cursor_index = len(self.text)
-            elif(key == "backspace"):
+            elif key == "backspace":
                 if self.cursor_index != 0:
                     self.text = (self.text[:self.cursor_index - 1] +
                                  self.text[self.cursor_index:])
                     self.cursor_index -= 1
-            elif(key == "delete"):
+            elif key == "delete":
                 if self.cursor_index != len(self.text):
                     self.text = (self.text[:self.cursor_index] +
                                  self.text[self.cursor_index + 1:])
@@ -871,9 +860,8 @@ def begin_typing(self, x):
 
     def stop_typing(self):
         notifysubmit = False
-        # because _notify_submit_users might throw an error in the
-        # user's code, we only want to call it once we've already done
-        # our cleanup.
+        # Because _notify_submit_users might throw an error in the user's code,
+        # we only want to call it once we've already done our cleanup.
         if self.capturekeystrokes:
             # Check for toolmanager handling the keypress
             if self.ax.figure.canvas.manager.key_press_handler_id is not None:
@@ -988,7 +976,6 @@ class RadioButtons(AxesWidget):
 
     Connect to the RadioButtons with the :meth:`on_clicked` method.
 
-
     Attributes
     ----------
     ax
@@ -1001,8 +988,8 @@ class RadioButtons(AxesWidget):
         A list of `~.patches.Circle` instances defining the buttons.
     value_selected : str
         The label text of the currently selected button.
-
     """
+
     def __init__(self, ax, labels, active=0, activecolor='blue'):
         """
         Add radio buttons to an `~.axes.Axes`.
@@ -1348,8 +1335,7 @@ class MultiCursor(Widget):
     Provide a vertical (default) and/or horizontal line cursor shared between
     multiple axes.
 
-    For the cursor to remain responsive you must keep a reference to
-    it.
+    For the cursor to remain responsive you must keep a reference to it.
 
     Example usage::
 
@@ -1511,54 +1497,42 @@ def connect_default_events(self):
         self.connect_event('scroll_event', self.on_scroll)
 
     def ignore(self, event):
-        """return *True* if *event* should be ignored"""
+        # docstring inherited
         if not self.active or not self.ax.get_visible():
             return True
-
         # If canvas was locked
         if not self.canvas.widgetlock.available(self):
             return True
-
         if not hasattr(event, 'button'):
             event.button = None
-
         # Only do rectangle selection if event was triggered
         # with a desired button
-        if self.validButtons is not None:
-            if event.button not in self.validButtons:
-                return True
-
+        if (self.validButtons is not None
+                and event.button not in self.validButtons):
+            return True
         # If no button was pressed yet ignore the event if it was out
         # of the axes
         if self.eventpress is None:
             return event.inaxes != self.ax
-
-        # If a button was pressed, check if the release-button is the
-        # same.
+        # If a button was pressed, check if the release-button is the same.
         if event.button == self.eventpress.button:
             return False
-
-        # If a button was pressed, check if the release-button is the
-        # same.
+        # If a button was pressed, check if the release-button is the same.
         return (event.inaxes != self.ax or
                 event.button != self.eventpress.button)
 
     def update(self):
-        """draw using newfangled blit or oldfangled draw depending on
-        useblit
-
+        """
+        Draw using blit() or draw_idle() depending on ``self.useblit``.
         """
         if not self.ax.get_visible():
             return False
-
         if self.useblit:
             if self.background is not None:
                 self.canvas.restore_region(self.background)
             for artist in self.artists:
                 self.ax.draw_artist(artist)
-
             self.canvas.blit(self.ax.bbox)
-
         else:
             self.canvas.draw_idle()
         return False
@@ -1608,7 +1582,6 @@ def press(self, event):
 
     def _press(self, event):
         """Button press handler"""
-        pass
 
     def release(self, event):
         """Button release event handler and validator"""
@@ -1624,7 +1597,6 @@ def release(self, event):
 
     def _release(self, event):
         """Button release event handler"""
-        pass
 
     def onmove(self, event):
         """Cursor move event handler and validator"""
@@ -1636,7 +1608,6 @@ def onmove(self, event):
 
     def _onmove(self, event):
         """Cursor move event handler"""
-        pass
 
     def on_scroll(self, event):
         """Mouse scroll event handler and validator"""
@@ -1645,7 +1616,6 @@ def on_scroll(self, event):
 
     def _on_scroll(self, event):
         """Mouse scroll event handler"""
-        pass
 
     def on_key_press(self, event):
         """Key press event handler and validator for all selection widgets"""
@@ -1665,7 +1635,6 @@ def on_key_press(self, event):
     def _on_key_press(self, event):
         """Key press event handler - use for widget-specific key press actions.
         """
-        pass
 
     def on_key_release(self, event):
         """Key release event handler and validator."""
@@ -1742,7 +1711,6 @@ class SpanSelector(_SelectorWidget):
     >>> fig.show()
 
     See also: :doc:`/gallery/widgets/span_selector`
-
     """
 
     def __init__(self, ax, onselect, direction, minspan=None, useblit=False,
@@ -1776,7 +1744,7 @@ def __init__(self, ax, onselect, direction, minspan=None, useblit=False,
         self.new_axes(ax)
 
     def new_axes(self, ax):
-        """Set SpanSelector to operate on a new Axes"""
+        """Set SpanSelector to operate on a new Axes."""
         self.ax = ax
         if self.canvas is not ax.figure.canvas:
             if self.canvas is not None:
@@ -1809,7 +1777,7 @@ def new_axes(self, ax):
         self.artists = [self.rect]
 
     def ignore(self, event):
-        """return *True* if *event* should be ignored"""
+        # docstring inherited
         return _SelectorWidget.ignore(self, event) or not self.visible
 
     def _press(self, event):
@@ -1912,7 +1880,8 @@ def _set_span_xy(self, event):
 
 
 class ToolHandles:
-    """Control handles for canvas tools.
+    """
+    Control handles for canvas tools.
 
     Parameters
     ----------
@@ -1928,7 +1897,6 @@ class ToolHandles:
 
     def __init__(self, ax, x, y, marker='o', marker_props=None, useblit=True):
         self.ax = ax
-
         props = dict(marker=marker, markersize=7, mfc='w', ls='none',
                      alpha=0.5, visible=False, label='_nolegend_')
         props.update(marker_props if marker_props is not None else {})
@@ -1972,8 +1940,7 @@ class RectangleSelector(_SelectorWidget):
     """
     Select a rectangular region of an axes.
 
-    For the cursor to remain responsive you must keep a reference to
-    it.
+    For the cursor to remain responsive you must keep a reference to it.
 
     Example usage::
 
@@ -2080,9 +2047,9 @@ def __init__(self, ax, onselect, drawtype='box',
         self.visible = True
         self.interactive = interactive
 
-        if drawtype == 'none':
-            drawtype = 'line'                        # draw a line but make it
-            self.visible = False                     # invisible
+        if drawtype == 'none':  # draw a line but make it invisible
+            drawtype = 'line'
+            self.visible = False
 
         if drawtype == 'box':
             if rectprops is None:
@@ -2400,8 +2367,7 @@ class EllipseSelector(RectangleSelector):
     """
     Select an elliptical region of an axes.
 
-    For the cursor to remain responsive you must keep a reference to
-    it.
+    For the cursor to remain responsive you must keep a reference to it.
 
     Example usage::
 
@@ -2507,7 +2473,6 @@ def onselect(verts):
         - 1 = left mouse button
         - 2 = center mouse button (scroll wheel)
         - 3 = right mouse button
-
     """
 
     def __init__(self, ax, onselect=None, useblit=True, lineprops=None,
@@ -2555,7 +2520,8 @@ def _onmove(self, event):
 
 
 class PolygonSelector(_SelectorWidget):
-    """Select a polygon region of an axes.
+    """
+    Select a polygon region of an axes.
 
     Place vertices with each mouse click, and make the selection by completing
     the polygon (clicking on the first vertex). Hold the *ctrl* key and click
@@ -2757,18 +2723,13 @@ def _draw_polygon(self):
 
     @property
     def verts(self):
-        """Get the polygon vertices.
-
-        Returns
-        -------
-        list
-            A list of the vertices of the polygon as ``(xdata, ydata)`` tuples.
-        """
+        """The polygon vertices, as a list of ``(x, y)`` pairs."""
         return list(zip(self._xs[:-1], self._ys[:-1]))
 
 
 class Lasso(AxesWidget):
-    """Selection curve of an arbitrary shape.
+    """
+    Selection curve of an arbitrary shape.
 
     The selected path can be used in conjunction with
     :func:`~matplotlib.path.Path.contains_point` to select data points
