From 877ec2966da2731e014913c142177e54db288444 Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Tue, 8 Apr 2025 20:08:27 -0400 Subject: [PATCH] Backport PR #29803: DOC: Improve FancyArrowPatch docstring --- lib/matplotlib/patches.py | 87 ++++++++++++++++++++++++++++----------- 1 file changed, 64 insertions(+), 23 deletions(-) diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py index f47c8abee32d..736b1e77e1ac 100644 --- a/lib/matplotlib/patches.py +++ b/lib/matplotlib/patches.py @@ -2335,7 +2335,7 @@ def get_styles(cls): @classmethod def pprint_styles(cls): """Return the available styles as pretty-printed string.""" - table = [('Class', 'Name', 'Attrs'), + table = [('Class', 'Name', 'Parameters'), *[(cls.__name__, # Add backquotes, as - and | have special meaning in reST. f'``{name}``', @@ -4159,49 +4159,90 @@ def __init__(self, posA=None, posB=None, *, patchA=None, patchB=None, shrinkA=2, shrinkB=2, mutation_scale=1, mutation_aspect=1, **kwargs): """ - There are two ways for defining an arrow: + **Defining the arrow position and path** - - If *posA* and *posB* are given, a path connecting two points is - created according to *connectionstyle*. The path will be - clipped with *patchA* and *patchB* and further shrunken by - *shrinkA* and *shrinkB*. An arrow is drawn along this - resulting path using the *arrowstyle* parameter. + There are two ways to define the arrow position and path: - - Alternatively if *path* is provided, an arrow is drawn along this - path and *patchA*, *patchB*, *shrinkA*, and *shrinkB* are ignored. + - **Start, end and connection**: + The typical approach is to define the start and end points of the + arrow using *posA* and *posB*. The curve between these two can + further be configured using *connectionstyle*. + + If given, the arrow curve is clipped by *patchA* and *patchB*, + allowing it to start/end at the border of these patches. + Additionally, the arrow curve can be shortened by *shrinkA* and *shrinkB* + to create a margin between start/end (after possible clipping) and the + drawn arrow. + + - **path**: Alternatively if *path* is provided, an arrow is drawn along + this Path. In this case, *connectionstyle*, *patchA*, *patchB*, + *shrinkA*, and *shrinkB* are ignored. + + **Styling** + + The *arrowstyle* defines the styling of the arrow head, tail and shaft. + The resulting arrows can be styled further by setting the `.Patch` + properties such as *linewidth*, *color*, *facecolor*, *edgecolor* + etc. via keyword arguments. Parameters ---------- - posA, posB : (float, float), default: None - (x, y) coordinates of arrow tail and arrow head respectively. + posA, posB : (float, float), optional + (x, y) coordinates of start and end point of the arrow. + The actually drawn start and end positions may be modified + through *patchA*, *patchB*, *shrinkA*, and *shrinkB*. - path : `~matplotlib.path.Path`, default: None + *posA*, *posB* are exclusive of *path*. + + path : `~matplotlib.path.Path`, optional If provided, an arrow is drawn along this path and *patchA*, *patchB*, *shrinkA*, and *shrinkB* are ignored. + *path* is exclusive of *posA*, *posB*. + arrowstyle : str or `.ArrowStyle`, default: 'simple' - The `.ArrowStyle` with which the fancy arrow is drawn. If a - string, it should be one of the available arrowstyle names, with - optional comma-separated attributes. The optional attributes are - meant to be scaled with the *mutation_scale*. The following arrow - styles are available: + The styling of arrow head, tail and shaft. This can be + + - `.ArrowStyle` or one of its subclasses + - The shorthand string name (e.g. "->") as given in the table below, + optionally containing a comma-separated list of style parameters, + e.g. "->, head_length=10, head_width=5". + + The style parameters are scaled by *mutation_scale*. + + The following arrow styles are available. See also + :doc:`/gallery/text_labels_and_annotations/fancyarrow_demo`. %(ArrowStyle:table)s + Only the styles ``<|-``, ``-|>``, ``<|-|>`` ``simple``, ``fancy`` + and ``wedge`` contain closed paths and can be filled. + connectionstyle : str or `.ConnectionStyle` or None, optional, \ default: 'arc3' - The `.ConnectionStyle` with which *posA* and *posB* are connected. - If a string, it should be one of the available connectionstyle - names, with optional comma-separated attributes. The following - connection styles are available: + `.ConnectionStyle` with which *posA* and *posB* are connected. + This can be + + - `.ConnectionStyle` or one of its subclasses + - The shorthand string name as given in the table below, e.g. "arc3". %(ConnectionStyle:table)s + Ignored if *path* is provided. + patchA, patchB : `~matplotlib.patches.Patch`, default: None - Head and tail patches, respectively. + Optional Patches at *posA* and *posB*, respectively. If given, + the arrow path is clipped by these patches such that head and tail + are at the border of the patches. + + Ignored if *path* is provided. shrinkA, shrinkB : float, default: 2 - Shrink amount, in points, of the tail and head of the arrow respectively. + Shorten the arrow path at *posA* and *posB* by this amount in points. + This allows to add a margin between the intended start/end points and + the arrow. + + Ignored if *path* is provided. mutation_scale : float, default: 1 Value with which attributes of *arrowstyle* (e.g., *head_length*)