Movatterモバイル変換

[0]ホーム
URL:

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

 Sign up
Appearance settings

Commit25ca6ee

Browse files
committed
Improve docstring of Annoation
1 parent03b07fb commit25ca6ee

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
classAnnotation(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 betweenthe
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-
widththe width of the arrow in points
2083-
headwidththe width of the base of the arrow head in points
2084-
headlengththe length of the arrow head in points
2085-
shrinkfraction of total length to'shrink' from both ends
2086-
?any key to :class:`matplotlib.patches.FancyArrowPatch`
2104+
widthThe width of the arrow in points
2105+
headwidthThe width of the base of the arrow head in points
2106+
headlengthThe length of the arrow head in points
2107+
shrinkFraction of total length to shrink from both ends
2108+
?Any key to :class:`matplotlib.patches.FancyArrowPatch`
20872109
========== ======================================================
20882110
2089-
Ifthe `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-
Controlsthevisibility of the annotationwhen it goes
2151+
annotation_clip : bool or None, optional
2152+
Whether to drawtheannotation when the annotationpoint *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
defxyann(self):
2228+
"""
2229+
The the text position.
2230+
2231+
See also *xytext* in `.Annotation`.
2232+
"""
21992233
returnself.get_position()
22002234

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

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

22092244
@anncoords.setter
22102245
defanncoords(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
defset_figure(self,fig):
22172263
ifself.arrow_patchisnotNone:
@@ -2386,8 +2432,10 @@ def get_window_extent(self, renderer=None):
23862432
returnBbox.union(bboxes)
23872433

23882434
arrow=property(
2389-
fget=cbook.deprecated("3.0")(lambdaself:None),
2390-
fset=cbook.deprecated("3.0")(lambdaself,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.")(lambdaself:None),
2438+
fset=cbook.deprecated("3.0",lambdaself,value:None))
23912439

23922440

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

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp