From 30dc9735fd98be0017b91f6f34718ab5a6661297 Mon Sep 17 00:00:00 2001 From: Ruth Comer <10599679+rcomer@users.noreply.github.com> Date: Sat, 25 Jan 2025 20:40:38 +0000 Subject: [PATCH] Backport PR #29509: MNT: Discourage arrow() --- lib/matplotlib/axes/_axes.py | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index 564783a6352c..96946fba1e92 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -5471,10 +5471,22 @@ def on_changed(collection): @_docstring.interpd def arrow(self, x, y, dx, dy, **kwargs): """ - Add an arrow to the Axes. + [*Discouraged*] Add an arrow to the Axes. This draws an arrow from ``(x, y)`` to ``(x+dx, y+dy)``. + .. admonition:: Discouraged + + The use of this method is discouraged because it is not guaranteed + that the arrow renders reasonably. For example, the resulting arrow + is affected by the Axes aspect ratio and limits, which may distort + the arrow. + + Consider using `~.Axes.annotate` without a text instead, e.g. :: + + ax.annotate("", xytext=(0, 0), xy=(0.5, 0.5), + arrowprops=dict(arrowstyle="->")) + Parameters ---------- %(FancyArrow)s @@ -5483,17 +5495,6 @@ def arrow(self, x, y, dx, dy, **kwargs): ------- `.FancyArrow` The created `.FancyArrow` object. - - Notes - ----- - The resulting arrow is affected by the Axes aspect ratio and limits. - This may produce an arrow whose head is not square with its stem. To - create an arrow whose head is square with its stem, - use :meth:`annotate` for example: - - >>> ax.annotate("", xy=(0.5, 0.5), xytext=(0, 0), - ... arrowprops=dict(arrowstyle="->")) - """ # Strip away units for the underlying patch since units # do not make sense to most patch-like code