Deprecate Artist.{set,get}_contains.

anntzer · anntzer · commit 739aeb99f9da · 2020-03-10T04:53:42.000+01:00
I don't think it makes sense to allow overriding contains() checks per instance -- and if someone really need that, they can use a custom artist subclass or even just monkeypatch the contains method; if they need it for pick events there's still Artist.set_picker which is not going away. This came in in 8111a3a (2007) and was apparently never used or tested.
diff --git a/doc/api/next_api_changes/deprecations.rst b/doc/api/next_api_changes/deprecations.rst
@@ -142,8 +142,13 @@ 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.
+`.Line2D.set_picker` no longer sets the artist's custom-contain() check.
+
+``Artist.set_contains``, ``Artist.get_contains``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Setting a custom method overridding `.Artist.contains` is deprecated.
+There is no replacement, but you may still customize pick events using
+`.Artist.set_picker`.
 
 `~matplotlib.colorbar.Colorbar` methods
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -383,7 +383,7 @@ def _default_contains(self, mouseevent, figure=None):
         """
         Base impl. for checking whether a mouseevent happened in an artist.
 
-        1. If the artist defines a custom checker, use it.
+        1. If the artist defines a custom checker, use it (deprecated).
         2. If the artist figure is known and the event did not occur in that
            figure (by checking its ``canvas`` attribute), reject it.
         3. Otherwise, return `None, {}`, indicating that the subclass'
@@ -396,7 +396,7 @@ def _default_contains(self, mouseevent, figure=None):
                 return inside, info
             # subclass-specific implementation follows
 
-        The `canvas` kwarg is provided for the implementation of
+        The *figure* kwarg is provided for the implementation of
         `Figure.contains`.
         """
         if callable(self._contains):
@@ -406,7 +406,8 @@ def _default_contains(self, mouseevent, figure=None):
         return None, {}
 
     def contains(self, mouseevent):
-        """Test whether the artist contains the mouse event.
+        """
+        Test whether the artist contains the mouse event.
 
         Parameters
         ----------
@@ -420,17 +421,14 @@ def contains(self, mouseevent):
             An artist-specific dictionary of details of the event context,
             such as which points are contained in the pick radius. See the
             individual Artist subclasses for details.
-
-        See Also
-        --------
-        set_contains, get_contains
         """
         inside, info = self._default_contains(mouseevent)
         if inside is not None:
             return inside, info
         _log.warning("%r needs 'contains' method", self.__class__.__name__)
         return False, {}
 
+    @cbook.deprecated("3.3", alternative="set_picker")
     def set_contains(self, picker):
         """
         Define a custom contains test for the artist.
@@ -458,6 +456,7 @@ def contains(artist: Artist, event: MouseEvent) -> bool, dict
             raise TypeError("picker is not a callable")
         self._contains = picker
 
+    @cbook.deprecated("3.3", alternative="get_picker")
     def get_contains(self):
         """
         Return the custom contains function of the artist if set, or *None*.
