Deprecate Text.get_prop_tup.

anntzer · anntzer · commit 92d1577cf728 · 2021-04-01T09:16:14.000+02:00
get_prop_tup was intended as a general caching mechanism for reusing
Text layouts, but it ended up only being used by _get_layout (which
backends have to call anyways to handle multiline text).  Note that in
fact, if we really wanted to make backends use that info for caching,
whether e.g. the text color needs to be taken into account would likely
depend on the backend's own caching mechanism.

Replace it by a private `_get_layout_cache_key`, which does not take
color into account (color doesn't affect layout), which will later allow
removing a color-must-be-hashable check.
diff --git a/doc/api/next_api_changes/deprecations/19575-AL.rst b/doc/api/next_api_changes/deprecations/19575-AL.rst
@@ -0,0 +1,4 @@
+``Text.get_prop_tup``
+~~~~~~~~~~~~~~~~~~~~~
+... is deprecated with no replacements (because the `.Text` class cannot know
+whether a backend needs to update cache e.g. when the text's color changes).
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
@@ -284,13 +284,28 @@ def update_from(self, other):
         self._linespacing = other._linespacing
         self.stale = True
 
+    def _get_layout_cache_key(self, renderer=None):
+        """
+        Return a hashable tuple of properties that lets `_get_layout` know
+        whether a previously computed layout can be reused.
+        """
+        x, y = self.get_unitless_position()
+        renderer = renderer or self._renderer
+        return (
+            x, y, self.get_text(), hash(self._fontproperties),
+            self._verticalalignment, self._horizontalalignment,
+            self._linespacing,
+            self._rotation, self._rotation_mode, self._transform_rotates_text,
+            self.figure.dpi, weakref.ref(renderer),
+        )
+
     def _get_layout(self, renderer):
         """
         Return the extent (bbox) of the text together with
         multiple-alignment information. Note that it returns an extent
         of a rotated text when necessary.
         """
-        key = self.get_prop_tup(renderer=renderer)
+        key = self._get_layout_cache_key(renderer=renderer)
         if key in self._cached:
             return self._cached[key]
 
@@ -831,6 +846,8 @@ def get_position(self):
         # specified with 'set_x' and 'set_y'.
         return self._x, self._y
 
+    # When removing, also remove the hash(color) check in set_color()
+    @_api.deprecated("3.5")
     def get_prop_tup(self, renderer=None):
         """
         Return a hashable tuple of properties.
@@ -938,7 +955,8 @@ def set_color(self, color):
         # out at draw time for simplicity.
         if not cbook._str_equal(color, "auto"):
             mpl.colors._check_color_like(color=color)
-        # Make sure it is hashable, or get_prop_tup will fail.
+        # Make sure it is hashable, or get_prop_tup will fail (remove this once
+        # get_prop_tup is removed).
         try:
             hash(color)
         except TypeError:
