MNT: deprecate arrow

jklymak · jklymak · commit 5801bfa8d52f · 2022-02-04T09:26:33.000+01:00
diff --git a/doc/api/next_api_changes/deprecations/22382-JK.rst b/doc/api/next_api_changes/deprecations/22382-JK.rst
@@ -0,0 +1,8 @@
+``arrow`` method is deprecated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The `~.axes.Axes.arrow` method is deprecated, and is scheduled to be
+removed in Matplotlib 3.9.  It only produces properly shaped
+arrow heads if the aspect ratio of the axes is 1, and the parameters to
+control the size of the arrow heads is in data space, and hence
+unintuitive.  Users should use `~.axes.Axes.annotate` to create arrows.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -4892,6 +4892,7 @@ def on_changed(collection):
 
         return collection
 
+    @_api.deprecated("3.6", alternative='annotate', removal='3.9')
     @docstring.dedent_interpd
     def arrow(self, x, y, dx, dy, **kwargs):
         """
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -31,7 +31,7 @@
 from numpy.testing import (
     assert_allclose, assert_array_equal, assert_array_almost_equal)
 from matplotlib import rc_context
-from matplotlib.cbook import MatplotlibDeprecationWarning
+from matplotlib._api import MatplotlibDeprecationWarning
 
 # Note: Some test cases are run twice: once normally and once with labeled data
 #       These two must be defined in the same test function or need to have
@@ -591,24 +591,27 @@ def test_arrow_simple():
         (length_includes_head, shape, head_starts_at_zero) = kwarg
         theta = 2 * np.pi * i / 12
         # Draw arrow
-        ax.arrow(0, 0, np.sin(theta), np.cos(theta),
-                 width=theta/100,
-                 length_includes_head=length_includes_head,
-                 shape=shape,
-                 head_starts_at_zero=head_starts_at_zero,
-                 head_width=theta / 10,
-                 head_length=theta / 10)
+        with pytest.warns(MatplotlibDeprecationWarning):
+            ax.arrow(0, 0, np.sin(theta), np.cos(theta),
+                     width=theta/100,
+                     length_includes_head=length_includes_head,
+                     shape=shape,
+                     head_starts_at_zero=head_starts_at_zero,
+                     head_width=theta / 10,
+                     head_length=theta / 10)
 
 
 def test_arrow_empty():
     _, ax = plt.subplots()
     # Create an empty FancyArrow
-    ax.arrow(0, 0, 0, 0, head_length=0)
+    with pytest.warns(MatplotlibDeprecationWarning):
+        ax.arrow(0, 0, 0, 0, head_length=0)
 
 
 def test_arrow_in_view():
     _, ax = plt.subplots()
-    ax.arrow(1, 1, 1, 1)
+    with pytest.warns(MatplotlibDeprecationWarning):
+        ax.arrow(1, 1, 1, 1)
     assert ax.get_xlim() == (0.8, 2.2)
     assert ax.get_ylim() == (0.8, 2.2)
 
diff --git a/lib/matplotlib/tests/test_patches.py b/lib/matplotlib/tests/test_patches.py
@@ -14,6 +14,7 @@
 from matplotlib import (
     collections as mcollections, colors as mcolors, patches as mpatches,
     path as mpath, transforms as mtransforms, rcParams)
+from matplotlib._api import MatplotlibDeprecationWarning
 
 import sys
 on_win = (sys.platform == 'win32')
@@ -604,7 +605,8 @@ def test_fancyarrow_units():
 
 def test_fancyarrow_setdata():
     fig, ax = plt.subplots()
-    arrow = ax.arrow(0, 0, 10, 10, head_length=5, head_width=1, width=.5)
+    with pytest.warns(MatplotlibDeprecationWarning):
+        arrow = ax.arrow(0, 0, 10, 10, head_length=5, head_width=1, width=.5)
     expected1 = np.array(
       [[13.54, 13.54],
        [10.35,  9.65],
