Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 25ca6ee

Browse files
timhoffmtimhoffm
committed
Improve docstring of Annoation
1 parent 03b07fb commit 25ca6ee

File tree

1 file changed

+117
-69
lines changed

1 file changed

+117
-69
lines changed

‎lib/matplotlib/text.py

Lines changed: 117 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -1983,110 +1983,132 @@ def draggable(self, state=None, use_blit=False):
19831983

19841984

19851985
class Annotation(Text, _AnnotationBase):
1986+
"""
1987+
An `.Annotation` is a `.Text` that can refer to a specific position *xy*.
1988+
Optionally an arrow pointing from the text to *xy* can be drawn.
1989+
1990+
Attributes
1991+
----------
1992+
xy
1993+
The annotated position.
1994+
xycoords
1995+
The coordinate system for *xy*.
1996+
arrow_patch
1997+
A `.FancyArrowPatch` to point from *xytext* to *xy*.
1998+
"""
1999+
19862000
def __str__(self):
19872001
return "Annotation(%g, %g, %r)" % (self.xy[0], self.xy[1], self._text)
19882002

1989-
@docstring.dedent_interpd
19902003
def __init__(self, s, xy,
19912004
xytext=None,
19922005
xycoords='data',
19932006
textcoords=None,
19942007
arrowprops=None,
19952008
annotation_clip=None,
19962009
**kwargs):
1997-
'''
1998-
Annotate the point ``xy`` with text ``s``.
2010+
"""
2011+
Annotate the point *xy* with text *s*.
2012+
2013+
In the simplest form, the text is placed at *xy*.
19992014
2000-
Additional kwargs are passed to `~matplotlib.text.Text`.
2015+
Optionally, the text can be displayed in another position *xytext*.
2016+
An arrow pointing from the text to the annotated point *xy* can then
2017+
be added by defining *arrowprops*.
20012018
20022019
Parameters
20032020
----------
2004-
20052021
s : str
20062022
The text of the annotation.
20072023
2008-
xy : iterable
2009-
Length 2 sequence specifying the *(x,y)* point to annotate.
2024+
xy : (float, float)
2025+
The point *(x,y)* to annotate.
2026+
2027+
xytext : (float, float), optional
2028+
The position *(x,y)* to place the text at.
2029+
If *None*, defaults to *xy*.
20102030
2011-
xytext : iterable, optional
2012-
Length 2 sequence specifying the *(x,y)* to place the text
2013-
at. If None, defaults to ``xy``.
2031+
xycoords : str, `.Artist`, `.Transform`, callable or tuple, optional
20142032
2015-
xycoords : str, Artist, Transform, callable or tuple, optional
2033+
The coordinate system that *xy* is given in. The following types
2034+
of values are supported:
20162035
2017-
The coordinate system that ``xy`` is given in.
2036+
- One of the following strings:
20182037
2019-
For a `str` the allowed values are:
2038+
================= =============================================
2039+
Value Description
2040+
================= =============================================
2041+
'figure points' Points from the lower left of the figure
2042+
'figure pixels' Pixels from the lower left of the figure
2043+
'figure fraction' Fraction of figure from lower left
2044+
'axes points' Points from lower left corner of axes
2045+
'axes pixels' Pixels from lower left corner of axes
2046+
'axes fraction' Fraction of axes from lower left
2047+
'data' Use the coordinate system of the object being
2048+
annotated (default)
2049+
'polar' *(theta,r)* if not native 'data' coordinates
2050+
================= =============================================
20202051
2021-
================= ===============================================
2022-
Property Description
2023-
================= ===============================================
2024-
'figure points' points from the lower left of the figure
2025-
'figure pixels' pixels from the lower left of the figure
2026-
'figure fraction' fraction of figure from lower left
2027-
'axes points' points from lower left corner of axes
2028-
'axes pixels' pixels from lower left corner of axes
2029-
'axes fraction' fraction of axes from lower left
2030-
'data' use the coordinate system of the object being
2031-
annotated (default)
2032-
'polar' *(theta,r)* if not native 'data' coordinates
2033-
================= ===============================================
2052+
- An `.Artist`: *xy* is interpreted as a fraction of the artists
2053+
`~matplotlib.transforms.Bbox`. E.g. *(0, 0)* would be the lower
2054+
left corner of the bounding box and *(0.5, 1)* would be the
2055+
center top of the bounding box.
20342056
2035-
If a `~matplotlib.artist.Artist` object is passed in the units are
2036-
fraction if it's bounding box.
2057+
- A `.Transform` to transform *xy* to screen coordinates.
20372058
2038-
If a `~matplotlib.transforms.Transform` object is passed
2039-
in use that to transform ``xy`` to screen coordinates
2059+
- A function with one of the following signatures::
20402060
2041-
If a callable it must take a
2042-
`~matplotlib.backend_bases.RendererBase` object as input
2043-
and return a `~matplotlib.transforms.Transform` or
2044-
`~matplotlib.transforms.Bbox` object
2061+
def transform(renderer) -> Bbox
2062+
def transform(renderer) -> Transform
20452063
2046-
If a `tuple` must be length 2 tuple of str, `Artist`,
2047-
`Transform` or callable objects. The first transform is
2048-
used for the *x* coordinate and the second for *y*.
2064+
where *renderer* is a `.RendererBase` subclass.
2065+
2066+
The result of the function is interpreted like the `.Artist` and
2067+
`.Transform` cases above.
2068+
2069+
- A tuple *(xcoords, ycoords)* specifying separate coordinate
2070+
systems for *x* and *y*. *xcoords* and *ycoords* must each be
2071+
of one of the above described types.
20492072
20502073
See :ref:`plotting-guide-annotation` for more details.
20512074
2052-
Defaults to ``'data'``
2075+
Defaults to 'data'.
20532076
2054-
textcoords : str, `Artist`, `Transform`, callable or tuple, optional
2055-
The coordinate system that ``xytext`` is given, which
2056-
may be different than the coordinate system used for
2057-
``xy``.
2077+
textcoords : str, `.Artist`, `.Transform`, callable or tuple, optional
2078+
The coordinate system that *xytext* is given in.
20582079
2059-
All ``xycoords`` values are valid as well as the following
2080+
All *xycoords* values are valid as well as the following
20602081
strings:
20612082
20622083
================= =========================================
2063-
Property Description
2084+
Value Description
20642085
================= =========================================
2065-
'offset points' offset (in points) from the *xy* value
2066-
'offset pixels' offset (in pixels) from the *xy* value
2086+
'offset points' Offset (in points) from the *xy* value
2087+
'offset pixels' Offset (in pixels) from the *xy* value
20672088
================= =========================================
20682089
2069-
defaults to the input of ``xycoords``
2090+
Defaults to the value of *xycoords*, i.e. use the same coordinate
2091+
system for annotation point and text position.
20702092
20712093
arrowprops : dict, optional
2072-
If not None, properties used to draw a
2073-
`~matplotlib.patches.FancyArrowPatch` arrow between ``xy`` and
2074-
``xytext``.
2094+
The properties used to draw a
2095+
`~matplotlib.patches.FancyArrowPatch` arrow between the
2096+
positions *xy* and *xytext*.
20752097
2076-
If `arrowprops` does not contain the key ``'arrowstyle'`` the
2098+
If *arrowprops* does not contain the key 'arrowstyle' the
20772099
allowed keys are:
20782100
20792101
========== ======================================================
20802102
Key Description
20812103
========== ======================================================
2082-
width the width of the arrow in points
2083-
headwidth the width of the base of the arrow head in points
2084-
headlength the length of the arrow head in points
2085-
shrink fraction of total length to 'shrink' from both ends
2086-
? any key to :class:`matplotlib.patches.FancyArrowPatch`
2104+
width The width of the arrow in points
2105+
headwidth The width of the base of the arrow head in points
2106+
headlength The length of the arrow head in points
2107+
shrink Fraction of total length to shrink from both ends
2108+
? Any key to :class:`matplotlib.patches.FancyArrowPatch`
20872109
========== ======================================================
20882110
2089-
If the `arrowprops` contains the key ``'arrowstyle'`` the
2111+
If *arrowprops* contains the key 'arrowstyle' the
20902112
above keys are forbidden. The allowed values of
20912113
``'arrowstyle'`` are:
20922114
@@ -2124,25 +2146,32 @@ def __init__(self, s, xy,
21242146
? any key for :class:`matplotlib.patches.PathPatch`
21252147
=============== ==================================================
21262148
2127-
Defaults to None
2149+
Defaults to None, i.e. no arrow is drawn.
21282150
2129-
annotation_clip : bool, optional
2130-
Controls the visibility of the annotation when it goes
2151+
annotation_clip : bool or None, optional
2152+
Whether to draw the annotation when the annotation point *xy* is
21312153
outside the axes area.
21322154
2133-
If `True`, the annotation will only be drawn when the
2134-
``xy`` is inside the axes. If `False`, the annotation will
2135-
always be drawn regardless of its position.
2155+
- If *True*, the annotation will only be drawn when *xy* is
2156+
within the axes.
2157+
- If *False*, the annotation will always be drawn.
2158+
- If *None*, the annotation will only be drawn when *xy* is
2159+
within the axes and *xycoords* is 'data'.
2160+
2161+
Defaults to *None*.
21362162
2137-
The default is `None`, which behave as `True` only if
2138-
*xycoords* is "data".
2163+
**kwargs
2164+
Additional kwargs are passed to `~matplotlib.text.Text`.
21392165
21402166
Returns
21412167
-------
2142-
Annotation
2168+
annotation : `.Annotation`
21432169
2144-
'''
2170+
See Also
2171+
--------
2172+
:ref:`plotting-guide-annotation`.
21452173
2174+
"""
21462175
_AnnotationBase.__init__(self,
21472176
xy,
21482177
xycoords=xycoords,
@@ -2196,6 +2225,11 @@ def contains(self, event):
21962225

21972226
@property
21982227
def xyann(self):
2228+
"""
2229+
The the text position.
2230+
2231+
See also *xytext* in `.Annotation`.
2232+
"""
21992233
return self.get_position()
22002234

22012235
@xyann.setter
@@ -2204,14 +2238,26 @@ def xyann(self, xytext):
22042238

22052239
@property
22062240
def anncoords(self):
2241+
"""The coordinate system to use for `.Annotation.xyann`."""
22072242
return self._textcoords
22082243

22092244
@anncoords.setter
22102245
def anncoords(self, coords):
22112246
self._textcoords = coords
22122247

22132248
get_anncoords = anncoords.fget
2249+
get_anncoords.__doc__ = """
2250+
Return the coordinate system to use for `.Annotation.xyann`.
2251+
2252+
See also *xycoords* in `.Annotation`.
2253+
"""
2254+
22142255
set_anncoords = anncoords.fset
2256+
set_anncoords.__doc__ = """
2257+
Set the coordinate system to use for `.Annotation.xyann`.
2258+
2259+
See also *xycoords* in `.Annotation`.
2260+
"""
22152261

22162262
def set_figure(self, fig):
22172263
if self.arrow_patch is not None:
@@ -2386,8 +2432,10 @@ def get_window_extent(self, renderer=None):
23862432
return Bbox.union(bboxes)
23872433

23882434
arrow = property(
2389-
fget=cbook.deprecated("3.0")(lambda self: None),
2390-
fset=cbook.deprecated("3.0")(lambda self, value: None))
2435+
fget=cbook.deprecated("3.0", message="arrow was deprecated in "
2436+
"Matplotlib 3.0 and will be removed in 3.2. Use arrow_patch "
2437+
"instead.")(lambda self: None),
2438+
fset=cbook.deprecated("3.0", lambda self, value: None))
23912439

23922440

23932441
docstring.interpd.update(Annotation=Annotation.__init__.__doc__)

0 commit comments

Comments
 (0)