8000 Merge pull request #12214 from timhoffm/doc-annotate · matplotlib/matplotlib@7bcf618 · GitHub
[go: up one dir, main page]
Skip to content

Commit 7bcf618

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

File tree

1 file changed

+116
-68
lines changed

1 file changed

+116
-68
lines changed

‎lib/matplotlib/text.py

Lines 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