From a74bf6d22099ad1408643815aed72fbaaa0a2389 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Fri, 24 Jan 2025 10:01:04 +0100
Subject: [PATCH] MNT: Discourage arrow()
The arrow() design is broken beyond repair. Even though we currently only have to offer `annotate` as a workaround, we should make the limitations more prominent then just a note and we should steer users away.
This is a a step towards deprecation (#20387). Unfortunately the discussion of a replacement has stalled (#22435) and we have to revive it later. But that shound not hold us from pointing out the flaws
of arrow() more prominently.
---
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 c4967025e136..29d0a04cc77e 100644
--- a/lib/matplotlib/axes/_axes.py
+++ b/lib/matplotlib/axes/_axes.py
@@ -5432,10 +5432,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
@@ -5444,17 +5456,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
pFad - Phonifier reborn
Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.
Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.
Alternative Proxies:
Alternative Proxy
pFad Proxy
pFad v3 Proxy
pFad v4 Proxy