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

Skip to content

Changed docstrings in Text #11513

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 26, 2018
Merged

Changed docstrings in Text #11513

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
165 changes: 122 additions & 43 deletions lib/matplotlib/text.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,7 @@ def __init__(self,
**kwargs
):
"""
Create a `Text` instance at *x*, *y* with string *text*.
Create a `.Text` instance at *x*, *y* with string *text*.

Valid kwargs are
%(Text)s
Expand Down Expand Up @@ -200,7 +200,9 @@ def contains(self, mouseevent):
In the case of text, a hit is true anywhere in the
axis-aligned bounding-box containing the text.

Returns True or False.
Returns
-------
bool : bool
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

with returns, you don't necessarily have to use this syntax. You could also write:

Returns
-------
bool

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can but it often looks ugly, because it get bold and not formatted like for example here.

I am not sure if it is a bug in numpydocs because the documentation says that the return name is optional but the type is rendered as a name (bold) when the name is omitted.

"""
if callable(self._contains):
return self._contains(self, mouseevent)
Expand Down Expand Up @@ -430,17 +432,19 @@ def _get_layout(self, renderer):

def set_bbox(self, rectprops):
"""
Draw a bounding box around self. rectprops are any settable
properties for a FancyBboxPatch, e.g., facecolor='red', alpha=0.5.

t.set_bbox(dict(facecolor='red', alpha=0.5))

The default boxstyle is 'square'. The mutation
scale of the FancyBboxPatch is set to the fontsize.
Draw a bounding box around self.

Parameters
----------
rectprops : FancyBboxPatch prop dict
rectprops : dict with properties for `.patches.FancyBboxPatch`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

The default boxstyle is 'square'. The mutation
scale of the `.patches.FancyBboxPatch` is set to the fontsize.

Examples
--------
::

t.set_bbox(dict(facecolor='red', alpha=0.5))
"""

if rectprops is not None:
Expand Down Expand Up @@ -476,7 +480,8 @@ def set_bbox(self, rectprops):

def get_bbox_patch(self):
"""
Return the bbox Patch, or None if the FancyBboxPatch is not made.
Return the bbox Patch, or None if the `.patches.FancyBboxPatch`
is not made.
"""
return self._bbox_patch

Expand Down Expand Up @@ -510,7 +515,8 @@ def update_bbox_position_size(self, renderer):

def _draw_bbox(self, renderer, posx, posy):
"""
Update the location and size of the bbox (FancyBboxPatch), and draw.
Update the location and size of the bbox (`.patches.FancyBboxPatch`),
and draw.
"""

x_box, y_box, w_box, h_box = _get_textbox(self, renderer)
Expand All @@ -532,11 +538,11 @@ def _update_clip_properties(self):

def set_clip_box(self, clipbox):
"""
Set the artist's clip :class:`~matplotlib.transforms.Bbox`.
Set the artist's clip `~.transforms.Bbox`.

Parameters
----------
clipbox : matplotlib.transforms.Bbox
clipbox : `matplotlib.transforms.Bbox`
"""
super().set_clip_box(clipbox)
self._update_clip_properties()
Expand All @@ -545,10 +551,10 @@ def set_clip_path(self, path, transform=None):
"""
Set the artist's clip path, which may be:

* a :class:`~matplotlib.patches.Patch` (or subclass) instance
* a `~matplotlib.patches.Patch` (or subclass) instance

* a :class:`~matplotlib.path.Path` instance, in which case
an optional :class:`~matplotlib.transforms.Transform`
* a `~matplotlib.path.Path` instance, in which case
an optional `~matplotlib.transforms.Transform`
instance may be provided, which will be applied to the
path before using it for clipping.

Expand All @@ -558,9 +564,8 @@ def set_clip_path(self, path, transform=None):
rectangle, this method will set the clipping box to the
corresponding rectangle and set the clipping path to *None*.

ACCEPTS: [ (:class:`~matplotlib.path.Path`,
:class:`~matplotlib.transforms.Transform`) |
:class:`~matplotlib.patches.Patch` | None ]
ACCEPTS: { (`.path.Path`, `.transforms.Transform`),
`.patches.Patch`, None }
"""
super().set_clip_path(path, transform)
self._update_clip_properties()
Expand Down Expand Up @@ -689,7 +694,7 @@ def _get_wrapped_text(self):
@artist.allow_rasterization
def draw(self, renderer):
"""
Draws the :class:`Text` object to the given *renderer*.
Draws the `.Text` object to the given *renderer*.
"""
if renderer is not None:
self._renderer = renderer
Expand Down Expand Up @@ -761,35 +766,77 @@ def get_color(self):
return self._color

def get_fontproperties(self):
"Return the :class:`~font_manager.FontProperties` object"
"Return the `.font_manager.FontProperties` object"
return self._fontproperties

def get_fontfamily(self):
"Return the list of font families used for font lookup"
"""
Return the list of font families used for font lookup

See Also
--------
.font_manager.FontProperties.get_family
"""
return self._fontproperties.get_family()

def get_fontname(self):
"Return the font name as string"
"""
Return the font name as string

See Also
--------
.font_manager.FontProperties.get_name
"""
return self._fontproperties.get_name()

def get_fontstyle(self):
"Return the font style as string"
"""
Return the font style as string

See Also
--------
.font_manager.FontProperties.get_style
"""
return self._fontproperties.get_style()

def get_fontsize(self):
"Return the font size as integer"
"""
Return the font size as integer

See Also
--------
.font_manager.FontProperties.get_size_in_points
"""
return self._fontproperties.get_size_in_points()

def get_fontvariant(self):
"Return the font variant as a string"
"""
Return the font variant as a string

See Also
--------
.font_manager.FontProperties.get_variant
"""
return self._fontproperties.get_variant()

def get_fontweight(self):
"Get the font weight as string or number"
"""
Get the font weight as string or number

See Also
--------
.font_manager.FontProperties.get_weight
"""
return self._fontproperties.get_weight()

def get_stretch(self):
'Get the font stretch as a string or number'
"""
Get the font stretch as a string or number

See Also
--------
.font_manager.FontProperties.get_stretch
"""
return self._fontproperties.get_stretch()

def get_horizontalalignment(self):
Expand Down Expand Up @@ -844,7 +891,7 @@ def get_verticalalignment(self):

def get_window_extent(self, renderer=None, dpi=None):
'''
Return a :class:`~matplotlib.transforms.Bbox` object bounding
Return a `~matplotlib.transforms.Bbox` object bounding
the text, in display units.

In addition to being used internally, this is useful for
Expand All @@ -853,9 +900,9 @@ def get_window_extent(self, renderer=None, dpi=None):
*renderer* defaults to the _renderer attribute of the text
object. This is not assigned until the first execution of
:meth:`draw`, so you must use this kwarg if you want
to call :meth:`get_window_extent` prior to the first
:meth:`draw`. For getting web page regions, it is
simpler to call the method after saving the figure.
to call `.get_window_extent` prior to the first `draw`. For
getting web page regions, it is simpler to call the method after
saving the figure.

*dpi* defaults to self.figure.dpi; the renderer dpi is
irrelevant. For the web application, if figure.dpi is not
Expand Down Expand Up @@ -889,14 +936,13 @@ def set_backgroundcolor(self, color):
"""
Set the background color of the text by updating the bbox.

.. seealso::

:meth:`set_bbox`
To change the position of the bounding box.

Parameters
----------
color : color

See Also
--------
.set_bbox : To change the position of the bounding box
"""
if self._bbox_patch is None:
self.set_bbox(dict(facecolor=color, edgecolor=color))
Expand Down Expand Up @@ -946,7 +992,7 @@ def set_multialignment(self, align):

Parameters
----------
align: {'left', 'right', 'center'}
align : {'left', 'right', 'center'}
"""
legal = ('center', 'right', 'left')
if align not in legal:
Expand Down Expand Up @@ -978,6 +1024,10 @@ def set_fontfamily(self, fontname):
----------
fontname : {FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', \
'monospace'}

See Also
--------
.font_manager.FontProperties.set_family
"""
self._fontproperties.set_family(fontname)
self.stale = True
Expand All @@ -989,6 +1039,10 @@ def set_fontvariant(self, variant):
Parameters
----------
variant : {'normal', 'small-caps'}

See Also
--------
.font_manager.FontProperties.set_variant
"""
self._fontproperties.set_variant(variant)
self.stale = True
Expand All @@ -1000,6 +1054,10 @@ def set_fontstyle(self, fontstyle):
Parameters
----------
fontstyle : {'normal', 'italic', 'oblique'}

See Also
--------
.font_manager.FontProperties.set_style
"""
self._fontproperties.set_style(fontstyle)
self.stale = True
Expand All @@ -1013,6 +1071,10 @@ def set_fontsize(self, fontsize):
----------
fontsize : {size in points, 'xx-small', 'x-small', 'small', 'medium', \
'large', 'x-large', 'xx-large'}

See Also
--------
.font_manager.FontProperties.set_size
"""
self._fontproperties.set_size(fontsize)
self.stale = True
Expand All @@ -1026,6 +1088,10 @@ def set_fontweight(self, weight):
weight : {a numeric value in range 0-1000, 'ultralight', 'light', \
'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', \
'demi', 'bold', 'heavy', 'extra bold', 'black'}

See Also
--------
.font_manager.FontProperties.set_weight
"""
self._fontproperties.set_weight(weight)
self.stale = True
Expand All @@ -1039,6 +1105,10 @@ def set_fontstretch(self, stretch):
stretch : {a numeric value in range 0-1000, 'ultra-condensed', \
'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', \
'expanded', 'extra-expanded', 'ultra-expanded'}

See Also
--------
.font_manager.FontProperties.set_stretch
"""
self._fontproperties.set_stretch(stretch)
self.stale = True
Expand Down Expand Up @@ -1144,12 +1214,11 @@ def is_math_text(s, usetex=None):

def set_fontproperties(self, fp):
"""
Set the font properties that control the text. *fp* must be a
:class:`matplotlib.font_manager.FontProperties` object.
Set the font properties that control the text.

Parameters
----------
fp : matplotlib.font_manager.FontProperties
fp : `.font_manager.FontProperties`
"""
if isinstance(fp, str):
fp = FontProperties(fp)
Expand Down Expand Up @@ -1184,9 +1253,19 @@ def get_usetex(self):

def set_fontname(self, fontname):
"""
alias for set_family
alias for `.set_family`

One-way alias only: the getter differs.

Parameters
----------
fontname : {FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', \
'monospace'}

See Also
--------
.font_manager.FontProperties.set_family

"""
return self.set_family(fontname)

Expand Down