matplotlib · timhoffm · Jan 10, 2020 · Jan 8, 2020 · jklymak · Jan 9, 2020
diff --git a/doc/api/next_api_changes/deprecations.rst b/doc/api/next_api_changes/deprecations.rst
@@ -135,3 +135,12 @@ access the transform classes from the :mod:`.scale` module.
 ``TexManager.cachedir``
 ~~~~~~~~~~~~~~~~~~~~~~~
 Use `matplotlib.get_cachedir()` instead.
+
+Setting `.Line2D`\'s pickradius via `.Line2D.set_picker`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Setting a `.Line2D`\'s pickradius (i.e. the tolerance for pick events
+and containment checks) via `.Line2D.set_picker` is deprecated.  Use
+`.Line2D.set_pickradius` instead.
+
+`.Line2D.set_picker` no longer sets the artist's custom-contain() check.  Use
+``Line2D.set_contains`` instead.
diff --git a/examples/event_handling/legend_picking.py b/examples/event_handling/legend_picking.py
@@ -5,45 +5,39 @@

 Enable picking on the legend to toggle the original line on and off
 """
+
 import numpy as np
 import matplotlib.pyplot as plt

-t = np.arange(0.0, 0.2, 0.1)
-y1 = 2*np.sin(2*np.pi*t)
-y2 = 4*np.sin(2*np.pi*2*t)
+
+t = np.linspace(0, 1)
+y1 = 2 * np.sin(2*np.pi*t)
+y2 = 4 * np.sin(2*np.pi*2*t)

 fig, ax = plt.subplots()
 ax.set_title('Click on legend line to toggle line on/off')
-line1, = ax.plot(t, y1, lw=2, label='1 HZ')
-line2, = ax.plot(t, y2, lw=2, label='2 HZ')
-leg = ax.legend(loc='upper left', fancybox=True, shadow=True)
-leg.get_frame().set_alpha(0.4)
+line1, = ax.plot(t, y1, lw=2, label='1 Hz')
+line2, = ax.plot(t, y2, lw=2, label='2 Hz')
+leg = ax.legend(fancybox=True, shadow=True)

-
-# we will set up a dict mapping legend line to orig line, and enable
-# picking on the legend line
 lines = [line1, line2]
-lined = dict()
+lined = {}  # Will map legend lines to original lines.
 for legline, origline in zip(leg.get_lines(), lines):
-    legline.set_picker(5)  # 5 pts tolerance
+    legline.set_picker(True)  # Enable picking on the legend line.
    lined[legline] = origline


 def on_pick(event):
-    # on the pick event, find the orig line corresponding to the
-    # legend proxy line, and toggle the visibility
+    # On the pick event, find the original line corresponding to the legend
+    # proxy line, and toggle its visibility.
    legline = event.artist
    origline = lined[legline]
-    vis = not origline.get_visible()
-    origline.set_visible(vis)
+    visible = not origline.get_visible()
+    origline.set_visible(visible)
    # Change the alpha on the line in the legend so we can see what lines
-    # have been toggled
-    if vis:
-        legline.set_alpha(1.0)
-    else:
-        legline.set_alpha(0.2)
+    # have been toggled.
+    legline.set_alpha(1.0 if visible else 0.2)
    fig.canvas.draw()

 fig.canvas.mpl_connect('pick_event', on_pick)
-
 plt.show()
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -516,7 +516,7 @@ def set_picker(self, picker):

        Parameters
        ----------
-        picker : None or bool or float or callable
+        picker : None or bool or callable
            This can be one of the following:

            - *None*: Picking is disabled for this artist (default).
@@ -525,14 +525,6 @@ def set_picker(self, picker):
              artist will fire a pick event if the mouse event is over
              the artist.

-            - A float: If picker is a number it is interpreted as an
-              epsilon tolerance in points and the artist will fire
-              off an event if it's data is within epsilon of the mouse
-              event.  For some artists like lines and patch collections,
-              the artist may provide additional data to the pick event
-              that is generated, e.g., the indices of the data within
-              epsilon of the pick event
-
            - A function: If picker is callable, it is a user supplied
              function which determines whether the artist is hit by the
              mouse event::
@@ -543,6 +535,10 @@ def set_picker(self, picker):
              artist, return *hit=True* and props is a dictionary of
              properties you want added to the PickEvent attributes.

+            - *deprecated*: For `.Line2D` only, *picker* can also be a float
+              that sets the tolerance for checking whether an event occurred
+              "on" the line; this is deprecated.  Use `.Line2D.set_pickradius`
+              instead.
        """
        self._picker = picker


diff --git a/lib/matplotlib/lines.py b/lib/matplotlib/lines.py
@@ -399,8 +399,6 @@ def __init__(self, xdata, ydata,
        self.update(kwargs)
        self.pickradius = pickradius
        self.ind_offset = 0
-        if isinstance(self._picker, Number):
-            self.pickradius = self._picker

        self._xorig = np.asarray([])
        self._yorig = np.asarray([])
@@ -603,16 +601,12 @@ def get_markevery(self):
        return self._markevery

    def set_picker(self, p):
-        """Sets the event picker details for the line.
-
-        Parameters
-        ----------
-        p : float or callable[[Artist, Event], Tuple[bool, dict]]
-            If a float, it is used as the pick radius in points.
-        """
-        if callable(p):
-            self._contains = p
-        else:
+        # docstring inherited
+        if isinstance(p, Number) and not isinstance(p, bool):
+            # After deprecation, the whole method can be deleted and inherited.
+            cbook.warn_deprecated(
+                "3.3", message="Setting the line's pick radius via set_picker "
+                "is deprecated; use set_pickradius instead.")
            self.pickradius = p
        self._picker = p