Deprecate public use of get_path_in_displaycoord.

anntzer · anntzer · commit d3136e77e79f · 2021-06-13T13:58:25.000+02:00
It is a helper for FancyArrowPatch and ConnectionPatch, but no other
Artists expose such a method, while the normal approach is just to apply
`get_transform()` to `get_path()` (which is documented as an
alternative).

This may help future changes in the ArrowStyle API (e.g. allowing the
tip and the body to have different linestyles).
diff --git a/doc/api/next_api_changes/deprecations/20428-AL.rst b/doc/api/next_api_changes/deprecations/20428-AL.rst
@@ -0,0 +1,4 @@
+``FancyArrowPatch.get_path_in_displaycoord`` and ``ConnectionPath.get_path_in_displaycoord``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+... are deprecated.  The path in display coordinates can still be obtained, as
+for other patches, using ``patch.get_transform().transform_path(patch.get_path())``.
diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
@@ -4354,17 +4354,15 @@ def get_mutation_aspect(self):
                 else 1)  # backcompat.
 
     def get_path(self):
-        """
-        Return the path of the arrow in the data coordinates. Use
-        get_path_in_displaycoord() method to retrieve the arrow path
-        in display coordinates.
-        """
-        _path, fillable = self.get_path_in_displaycoord()
+        """Return the path of the arrow in the data coordinates."""
+        # The path is generated in display coordinates, then converted back to
+        # data coordinates.
+        _path, fillable = self._get_path_in_displaycoord()
         if np.iterable(fillable):
             _path = Path.make_compound_path(*_path)
         return self.get_transform().inverted().transform_path(_path)
 
-    def get_path_in_displaycoord(self):
+    def _get_path_in_displaycoord(self):
         """Return the mutated path of the arrow in display coordinates."""
         dpi_cor = self._dpi_cor
 
@@ -4389,18 +4387,22 @@ def get_path_in_displaycoord(self):
 
         return _path, fillable
 
+    get_path_in_displaycoord = _api.deprecate_privatize_attribute(
+        "3.5",
+        alternative="self.get_transform().transform_path(self.get_path())")
+
     def draw(self, renderer):
         if not self.get_visible():
             return
 
         with self._bind_draw_path_function(renderer) as draw_path:
 
             # FIXME : dpi_cor is for the dpi-dependency of the linewidth. There
-            # could be room for improvement.  Maybe get_path_in_displaycoord
+            # could be room for improvement.  Maybe _get_path_in_displaycoord
             # could take a renderer argument, but get_path should be adapted
             # too.
             self._dpi_cor = renderer.points_to_pixels(1.)
-            path, fillable = self.get_path_in_displaycoord()
+            path, fillable = self._get_path_in_displaycoord()
 
             if not np.iterable(fillable):
                 path = [path]
@@ -4612,7 +4614,7 @@ def get_annotation_clip(self):
         """
         return self._annotation_clip
 
-    def get_path_in_displaycoord(self):
+    def _get_path_in_displaycoord(self):
         """Return the mutated path of the arrow in display coordinates."""
         dpi_cor = self._dpi_cor
         posA = self._get_xy(self.xy1, self.coords1, self.axesA)
