Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 7bcf618

Browse filesBrowse files
ImportanceOfBeingErnestImportanceOfBeingErnest
authored
Merge pull request #12214 from timhoffm/doc-annotate
Improve docstring of Annoation
2 parents 0d8c6f8 + 83790a9 commit 7bcf618
Copy full SHA for 7bcf618

File tree

Expand file treeCollapse file tree

1 file changed

+116
-68
lines changed
Filter options
Expand file treeCollapse file tree

1 file changed

+116
-68
lines changed

‎lib/matplotlib/text.py

Copy file name to clipboardExpand all lines: lib/matplotlib/text.py
+116-68Lines changed: 116 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1950,110 +1950,132 @@ def draggable(self, state=None, use_blit=False):
19501950

19511951

19521952
class Annotation(Text, _AnnotationBase):
1953+
"""
1954+
An `.Annotation` is a `.Text` that can refer to a specific position *xy*.
1955+
Optionally an arrow pointing from the text to *xy* can be drawn.
1956+
1957+
Attributes
1958+
----------
1959+
xy
1960+
The annotated position.
1961+
xycoords
1962+
The coordinate system for *xy*.
1963+
arrow_patch
1964+
A `.FancyArrowPatch` to point from *xytext* to *xy*.
1965+
"""
1966+
19531967
def __str__(self):
19541968
return "Annotation(%g, %g, %r)" % (self.xy[0], self.xy[1], self._text)
19551969

1956-
@docstring.dedent_interpd
19571970
def __init__(self, s, xy,
19581971
xytext=None,
19591972
xycoords='data',
19601973
textcoords=None,
19611974
arrowprops=None,
19621975
annotation_clip=None,
19631976
**kwargs):
1964-
'''
1965-
Annotate the point ``xy`` with text ``s``.
1977+
"""
1978+
Annotate the point *xy* with text *s*.
1979+
1980+
In the simplest form, the text is placed at *xy*.
19661981
1967-
Additional kwargs are passed to `~matplotlib.text.Text`.
1982+
Optionally, the text can be displayed in another position *xytext*.
1983+
An arrow pointing from the text to the annotated point *xy* can then
1984+
be added by defining *arrowprops*.
19681985
19691986
Parameters
19701987
----------
1971-
19721988
s : str
19731989
The text of the annotation.
19741990
1975-
xy : iterable
1976-
Length 2 sequence specifying the *(x,y)* point to annotate.
1991+
xy : (float, float)
1992+
The point *(x,y)* to annotate.
1993+
1994+
xytext : (float, float), optional
1995+
The position *(x,y)* to place the text at.
1996+
If *None*, defaults to *xy*.
19771997
1978-
xytext : iterable, optional
1979-
Length 2 sequence specifying the *(x,y)* to place the text
1980-
at. If None, defaults to ``xy``.
1998+
xycoords : str, `.Artist`, `.Transform`, callable or tuple, optional
19811999
1982-
xycoords : str, Artist, Transform, callable or tuple, optional
2000+
The coordinate system that *xy* is given in. The following types
2001+
of values are supported:
19832002
1984-
The coordinate system that ``xy`` is given in.
2003+
- One of the following strings:
19852004
1986-
For a `str` the allowed values are:
2005+
================= =============================================
2006+
Value Description
2007+
================= =============================================
2008+
'figure points' Points from the lower left of the figure
2009+
'figure pixels' Pixels from the lower left of the figure
2010+
'figure fraction' Fraction of figure from lower left
2011+
'axes points' Points from lower left corner of axes
2012+
'axes pixels' Pixels from lower left corner of axes
2013+
'axes fraction' Fraction of axes from lower left
2014+
'data' Use the coordinate system of the object being
2015+
annotated (default)
2016+
'polar' *(theta,r)* if not native 'data' coordinates
2017+
================= =============================================
19872018
1988-
================= ===============================================
1989-
Property Description
1990-
================= ===============================================
1991-
'figure points' points from the lower left of the figure
1992-
'figure pixels' pixels from the lower left of the figure
1993-
'figure fraction' fraction of figure from lower left
1994-
'axes points' points from lower left corner of axes
1995-
'axes pixels' pixels from lower left corner of axes
1996-
'axes fraction' fraction of axes from lower left
1997-
'data' use the coordinate system of the object being
1998-
annotated (default)
1999-
'polar' *(theta,r)* if not native 'data' coordinates
2000-
================= ===============================================
2019+
- An `.Artist`: *xy* is interpreted as a fraction of the artists
2020+
`~matplotlib.transforms.Bbox`. E.g. *(0, 0)* would be the lower
2021+
left corner of the bounding box and *(0.5, 1)* would be the
2022+
center top of the bounding box.
20012023
2002-
If a `~matplotlib.artist.Artist` object is passed in the units are
2003-
fraction if it's bounding box.
2024+
- A `.Transform` to transform *xy* to screen coordinates.
20042025
2005-
If a `~matplotlib.transforms.Transform` object is passed
2006-
in use that to transform ``xy`` to screen coordinates
2026+
- A function with one of the following signatures::
20072027
2008-
If a callable it must take a
2009-
`~matplotlib.backend_bases.RendererBase` object as input
2010-
and return a `~matplotlib.transforms.Transform` or
2011-
`~matplotlib.transforms.Bbox` object
2028+
def transform(renderer) -> Bbox
2029+
def transform(renderer) -> Transform
20122030
2013-
If a `tuple` must be length 2 tuple of str, `Artist`,
2014-
`Transform` or callable objects. The first transform is
2015-
used for the *x* coordinate and the second for *y*.
2031+
where *renderer* is a `.RendererBase` subclass.
2032+
2033+
The result of the function is interpreted like the `.Artist` and
2034+
`.Transform` cases above.
2035+
2036+
- A tuple *(xcoords, ycoords)* specifying separate coordinate
2037+
systems for *x* and *y*. *xcoords* and *ycoords* must each be
2038+
of one of the above described types.
20162039
20172040
See :ref:`plotting-guide-annotation` for more details.
20182041
2019-
Defaults to ``'data'``
2042+
Defaults to 'data'.
20202043
2021-
textcoords : str, `Artist`, `Transform`, callable or tuple, optional
2022-
The coordinate system that ``xytext`` is given, which
2023-
may be different than the coordinate system used for
2024-
``xy``.
2044+
textcoords : str, `.Artist`, `.Transform`, callable or tuple, optional
2045+
The coordinate system that *xytext* is given in.
20252046
2026-
All ``xycoords`` values are valid as well as the following
2047+
All *xycoords* values are valid as well as the following
20272048
strings:
20282049
20292050
================= =========================================
2030-
Property Description
2051+
Value Description
20312052
================= =========================================
2032-
'offset points' offset (in points) from the *xy* value
2033-
'offset pixels' offset (in pixels) from the *xy* value
2053+
'offset points' Offset (in points) from the *xy* value
2054+
'offset pixels' Offset (in pixels) from the *xy* value
20342055
================= =========================================
20352056
2036-
defaults to the input of ``xycoords``
2057+
Defaults to the value of *xycoords*, i.e. use the same coordinate
2058+
system for annotation point and text position.
20372059
20382060
arrowprops : dict, optional
2039-
If not None, properties used to draw a
2040-
`~matplotlib.patches.FancyArrowPatch` arrow between ``xy`` and
2041-
``xytext``.
2061+
The properties used to draw a
2062+
`~matplotlib.patches.FancyArrowPatch` arrow between the
2063+
positions *xy* and *xytext*.
20422064
2043-
If `arrowprops` does not contain the key ``'arrowstyle'`` the
2065+
If *arrowprops* does not contain the key 'arrowstyle' the
20442066
allowed keys are:
20452067
20462068
========== ======================================================
20472069
Key Description
20482070
========== ======================================================
2049-
width the width of the arrow in points
2050-
headwidth the width of the base of the arrow head in points
2051-
headlength the length of the arrow head in points
2052-
shrink fraction of total length to 'shrink' from both ends
2053-
? any key to :class:`matplotlib.patches.FancyArrowPatch`
2071+
width The width of the arrow in points
2072+
headwidth The width of the base of the arrow head in points
2073+
headlength The length of the arrow head in points
2074+
shrink Fraction of total length to shrink from both ends
2075+
? Any key to :class:`matplotlib.patches.FancyArrowPatch`
20542076
========== ======================================================
20552077
2056-
If the `arrowprops` contains the key ``'arrowstyle'`` the
2078+
If *arrowprops* contains the key 'arrowstyle' the
20572079
above keys are forbidden. The allowed values of
20582080
``'arrowstyle'`` are:
20592081
@@ -2091,25 +2113,32 @@ def __init__(self, s, xy,
20912113
? any key for :class:`matplotlib.patches.PathPatch`
20922114
=============== ==================================================
20932115
2094-
Defaults to None
2116+
Defaults to None, i.e. no arrow is drawn.
20952117
2096-
annotation_clip : bool, optional
2097-
Controls the visibility of the annotation when it goes
2118+
annotation_clip : bool or None, optional
2119+
Whether to draw the annotation when the annotation point *xy* is
20982120
outside the axes area.
20992121
2100-
If `True`, the annotation will only be drawn when the
2101-
``xy`` is inside the axes. If `False`, the annotation will
2102-
always be drawn regardless of its position.
2122+
- If *True*, the annotation will only be drawn when *xy* is
2123+
within the axes.
2124+
- If *False*, the annotation will always be drawn.
2125+
- If *None*, the annotation will only be drawn when *xy* is
2126+
within the axes and *xycoords* is 'data'.
2127+
2128+
Defaults to *None*.
21032129
2104-
The default is `None`, which behave as `True` only if
2105-
*xycoords* is "data".
2130+
**kwargs
2131+
Additional kwargs are passed to `~matplotlib.text.Text`.
21062132
21072133
Returns
21082134
-------
2109-
Annotation
2135+
annotation : `.Annotation`
21102136
2111-
'''
2137+
See Also
2138+
--------
2139+
:ref:`plotting-guide-annotation`.
21122140
2141+
"""
21132142
_AnnotationBase.__init__(self,
21142143
xy,
21152144
xycoords=xycoords,
@@ -2163,6 +2192,11 @@ def contains(self, event):
21632192

21642193
@property
21652194
def xyann(self):
2195+
"""
2196+
The the text position.
2197+
2198+
See also *xytext* in `.Annotation`.
2199+
"""
21662200
return self.get_position()
21672201

21682202
@xyann.setter
@@ -2171,14 +2205,26 @@ def xyann(self, xytext):
21712205

21722206
@property
21732207
def anncoords(self):
2208+
"""The coordinate system to use for `.Annotation.xyann`."""
21742209
return self._textcoords
21752210

21762211
@anncoords.setter
21772212
def anncoords(self, coords):
21782213
self._textcoords = coords
21792214

21802215
get_anncoords = anncoords.fget
2216+
get_anncoords.__doc__ = """
2217+
Return the coordinate system to use for `.Annotation.xyann`.
2218+
2219+
See also *xycoords* in `.Annotation`.
2220+
"""
2221+
21812222
set_anncoords = anncoords.fset
2223+
set_anncoords.__doc__ = """
2224+
Set the coordinate system to use for `.Annotation.xyann`.
2225+
2226+
See also *xycoords* in `.Annotation`.
2227+
"""
21822228

21832229
def set_figure(self, fig):
21842230
if self.arrow_patch is not None:
@@ -2353,7 +2399,9 @@ def get_window_extent(self, renderer=None):
23532399
return Bbox.union(bboxes)
23542400

23552401
arrow = property(
2356-
fget=cbook.deprecated("3.0")(lambda self: None),
2402+
fget=cbook.deprecated("3.0", message="arrow was deprecated in "
2403+
"Matplotlib 3.0 and will be removed in 3.2. Use arrow_patch "
2404+
"instead.")(lambda self: None),
23572405
fset=cbook.deprecated("3.0")(lambda self, value: None))
23582406

23592407

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.