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

Use str instead of string as type in docstrings #14716

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
Jul 18, 2019
Merged

Use str instead of string as type in docstrings #14716

Show file tree
Hide file tree
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
2 changes: 1 addition & 1 deletion 2 lib/matplotlib/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1479,7 +1479,7 @@ def func(ax, *args, **kwargs): ...
replace_names : list of str or None, optional, default: None
The list of parameter names for which lookup into *data* should be
attempted. If None, replacement is attempted for all arguments.
label_namer : string, optional, default: None
label_namer : str, optional, default: None
If set e.g. to "namer" (which must be a kwarg in the function's
signature -- not as ``**kwargs``), if the *namer* argument passed in is
a (string) key of *data* and no *label* kwarg is passed, then use the
Expand Down
30 changes: 15 additions & 15 deletions 30 lib/matplotlib/animation.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -195,7 +195,7 @@ def setup(self, fig, outfile, dpi=None):
----------
fig : `~matplotlib.figure.Figure`
The figure object that contains the information for frames
outfile : string
outfile : str
The filename of the resulting movie file
dpi : int, optional
The DPI (or resolution) for the file. This controls the size
Expand Down Expand Up @@ -231,7 +231,8 @@ def saving(self, fig, outfile, dpi, *args, **kwargs):


class MovieWriter(AbstractMovieWriter):
'''Base class for writing movies.
"""
Base class for writing movies.

This is a base class for MovieWriter subclasses that write a movie frame
data to a pipe. You cannot instantiate this class directly.
Expand All @@ -240,39 +241,38 @@ class MovieWriter(AbstractMovieWriter):
Attributes
----------
frame_format : str
The format used in writing frame data, defaults to 'rgba'
The format used in writing frame data, defaults to 'rgba'.
fig : `~matplotlib.figure.Figure`
The figure to capture data from.
This must be provided by the sub-classes.

'''
"""

def __init__(self, fps=5, codec=None, bitrate=None, extra_args=None,
metadata=None):
'''MovieWriter

"""
Parameters
----------
fps : int
Framerate for movie.
codec : string or None, optional
The codec to use. If ``None`` (the default) the ``animation.codec``
rcParam is used.
codec : str or None, optional
The codec to use. If ``None`` (the default) :rc:`animation.codec`
is used.
bitrate : int or None, optional
The bitrate for the saved movie file, which is one way to control
the output file size and quality. The default value is ``None``,
which uses the ``animation.bitrate`` rcParam. A value of -1
implies that the bitrate should be determined automatically by the
underlying utility.
extra_args : list of strings or None, optional
which uses :rc:`animation.bitrate`. A value of -1 implies that
the bitrate should be determined automatically by the underlying
utility.
extra_args : list of str or None, optional
A list of extra string arguments to be passed to the underlying
movie utility. The default is ``None``, which passes the additional
arguments in the ``animation.extra_args`` rcParam.
arguments in :rc:`animation.extra_args`.
metadata : Dict[str, str] or None
A dictionary of keys and values for metadata to include in the
output file. Some keys that may be of use include:
title, artist, genre, subject, copyright, srcform, comment.
'''
"""
if self.__class__ is MovieWriter:
# TODO MovieWriter is still an abstract class and needs to be
# extended with a mixin. This should be clearer in naming
Expand Down
14 changes: 7 additions & 7 deletions 14 lib/matplotlib/axes/_axes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -364,7 +364,7 @@ def legend(self, *args, **kwargs):
The length of handles and labels should be the same in this
case. If they are not, they are truncated to the smaller length.

labels : sequence of strings, optional
labels : list of str, optional
A list of labels to show next to the artists.
Use this together with *handles*, if you need full control on what
is shown in the legend and the automatic mechanism described above
Expand Down Expand Up @@ -1061,7 +1061,7 @@ def hlines(self, y, xmin, xmax, colors='k', linestyles='solid',

linestyles : {'solid', 'dashed', 'dashdot', 'dotted'}, optional

label : string, optional, default: ''
label : str, optional, default: ''

Returns
-------
Expand Down Expand Up @@ -1139,7 +1139,7 @@ def vlines(self, x, ymin, ymax, colors='k', linestyles='solid',

linestyles : {'solid', 'dashed', 'dashdot', 'dotted'}, optional

label : string, optional, default: ''
label : str, optional, default: ''

Returns
-------
Expand Down Expand Up @@ -2218,7 +2218,7 @@ def bar(self, x, height, width=0.8, bottom=None, *, align="center",
linewidth : scalar or array-like, optional
Width of the bar edge(s). If 0, don't draw edges.

tick_label : string or array-like, optional
tick_label : str or array-like, optional
The tick labels of the bars.
Default: None (Use default numeric labels.)

Expand Down Expand Up @@ -2514,7 +2514,7 @@ def barh(self, y, width, height=0.8, left=None, *, align="center",
linewidth : scalar or array-like, optional
Width of the bar edge(s). If 0, don't draw edges.

tick_label : string or array-like, optional
tick_label : str or array-like, optional
The tick labels of the bars.
Default: None (Use default numeric labels.)

Expand Down Expand Up @@ -2862,7 +2862,7 @@ def pie(self, x, explode=None, labels=None, colors=None,
will cycle. If *None*, will use the colors in the currently
active cycle.

autopct : None (default), string, or function, optional
autopct : None (default), str, or function, optional
If not *None*, is a string or function used to label the wedges
with their numeric value. The label will be placed inside the
wedge. If it is a format string, the label will be ``fmt%pct``.
Expand Down Expand Up @@ -3097,7 +3097,7 @@ def errorbar(self, x, y, yerr=None, xerr=None,
See :doc:`/gallery/statistics/errorbar_features`
for an example on the usage of ``xerr`` and ``yerr``.

fmt : plot format string, optional, default: ''
fmt : str, optional, default: ''
The format for the data points / data lines. See `.plot` for
details.

Expand Down
6 changes: 3 additions & 3 deletions 6 lib/matplotlib/axes/_base.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2924,7 +2924,7 @@ def tick_params(self, axis='both', **kwargs):
Transparency of gridlines: 0 (transparent) to 1 (opaque).
grid_linewidth : float
Width of gridlines in points.
grid_linestyle : string
grid_linestyle : str
Any valid `~matplotlib.lines.Line2D` line style spec.

Examples
Expand Down Expand Up @@ -3755,7 +3755,7 @@ def xaxis_date(self, tz=None):

Parameters
----------
tz : string or `tzinfo` instance, optional
tz : str or `tzinfo` instance, optional
Timezone. Defaults to :rc:`timezone`.
"""
# should be enough to inform the unit conversion interface
Expand All @@ -3768,7 +3768,7 @@ def yaxis_date(self, tz=None):

Parameters
----------
tz : string or `tzinfo` instance, optional
tz : str or `tzinfo` instance, optional
Timezone. Defaults to :rc:`timezone`.
"""
self.yaxis.axis_date(tz)
Expand Down
18 changes: 9 additions & 9 deletions 18 lib/matplotlib/axes/_secondary_axes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,12 +121,12 @@ def set_location(self, location):

Parameters
----------
location : string or scalar
location : {'top', 'bottom', 'left', 'right'} or float
The position to put the secondary axis. Strings can be 'top' or
'bottom' for orientation='x' and 'right' or 'left' for
orientation='y', scalar can be a float indicating the relative
position on the parent axes to put the new axes, 0.0 being the
bottom (or left) and 1.0 being the top (or right).
orientation='y'. A float indicates the relative position on the
parent axes to put the new axes, 0.0 being the bottom (or left)
and 1.0 being the top (or right).
"""

# This puts the rectangle into figure-relative coordinates.
Expand Down Expand Up @@ -374,12 +374,12 @@ def set_color(self, color):

Parameters
----------
location : string or scalar
location : {'top', 'bottom', 'left', 'right'} or float
The position to put the secondary axis. Strings can be 'top' or
'bottom', for x-oriented axises or 'left' or 'right' for y-oriented axises
or a scalar can be a float indicating the relative position
on the axes to put the new axes (0 being the bottom (left), and 1.0 being
the top (right).)
'bottom' for orientation='x' and 'right' or 'left' for
orientation='y'. A float indicates the relative position on the
parent axes to put the new axes, 0.0 being the bottom (or left)
and 1.0 being the top (or right).

functions : 2-tuple of func, or Transform with an inverse

Expand Down
8 changes: 4 additions & 4 deletions 8 lib/matplotlib/backend_bases.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3168,8 +3168,8 @@ def trigger_tool(self, name):

Parameters
----------
name : string
Name (id) of the tool triggered from within the container
name : str
Copy link
Contributor

Choose a reason for hiding this comment

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

also add missing final dots in the sentences below? (throughout the docstrings you edited here)

Copy link
Member Author

Choose a reason for hiding this comment

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

Trying to not get carried away too far. Otherwise the PR gets endless and even more terrible to review. These sentences need rephrasing anyway. It's better to leave them alone for now and do everything in one go when I come back.

Name (id) of the tool triggered from within the container.
"""
self.toolmanager.trigger_tool(name, sender=self)

Expand All @@ -3184,7 +3184,7 @@ def add_toolitem(self, name, group, position, image, description, toggle):

Parameters
----------
name : string
name : str
Name of the tool to add, this gets used as the tool's ID and as the
default label of the buttons
group : String
Expand Down Expand Up @@ -3226,7 +3226,7 @@ def remove_toolitem(self, name):

Parameters
----------
name : string
name : str
Name of the tool to remove.
"""
raise NotImplementedError
Expand Down
16 changes: 8 additions & 8 deletions 16 lib/matplotlib/backend_managers.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,8 +163,8 @@ def get_tool_keymap(self, name):

Parameters
----------
name : string
Name of the Tool
name : str
Name of the Tool.

Returns
-------
Expand All @@ -184,8 +184,8 @@ def update_keymap(self, name, *keys):

Parameters
----------
name : string
Name of the Tool
name : str
Name of the Tool.
keys : keys to associate with the Tool
"""

Expand All @@ -207,8 +207,8 @@ def remove_tool(self, name):

Parameters
----------
name : string
Name of the Tool
name : str
Name of the Tool.
"""

tool = self.get_tool(name)
Expand Down Expand Up @@ -355,8 +355,8 @@ def trigger_tool(self, name, sender=None, canvasevent=None, data=None):

Parameters
----------
name : string
Name of the tool
name : str
Name of the tool.
sender : object
Object that wishes to trigger the tool
canvasevent : Event
Expand Down
2 changes: 1 addition & 1 deletion 2 lib/matplotlib/backend_tools.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ class ToolBase:
ToolManager that controls this Tool
figure : `FigureCanvas`
Figure instance that is affected by this Tool
name : string
name : str
Used as **Id** of the tool, has to be unique among tools of the same
ToolManager
"""
Expand Down
4 changes: 2 additions & 2 deletions 4 lib/matplotlib/backends/backend_pdf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -437,7 +437,7 @@ def __init__(self, filename, metadata=None):
Parameters
----------

filename : file-like object or string
filename : str or path-like or file-like
Copy link
Member

Choose a reason for hiding this comment

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

Is chaining or like this the style we want? Could do as str, path-like, or file-like which reads better to me....

Copy link
Member Author

Choose a reason for hiding this comment

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

That's how the numpydoc docstring guide describes it:

shape : int or tuple of int

Currently we use a comma for simple tuples, e.g. center : float, float.

I don't have a strong opinion on this, but if we change that, we need another convention for tuple to avoid ambiguity (could be (float, float)). Everything should be changed consistently throughout the docs and we should document it in "writing documentation".

Copy link
Member

Choose a reason for hiding this comment

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

If you use the Oxford comma it’s not ambiguous:

A, B, or c

A, B or c

Though I would tend to enclose tuples in brackets just to be clear

Output target; if a string, a file will be opened for writing.
metadata : dict from strings to strings and dates
Information dictionary object (see PDF reference section 10.2.1
Expand Down Expand Up @@ -2472,7 +2472,7 @@ def __init__(self, filename, keep_empty=True, metadata=None):

Parameters
----------
filename : str
filename : str or path-like or file-like
Plots using :meth:`PdfPages.savefig` will be written to a file at
this location. The file is opened at once and any older file with
the same name is overwritten.
Expand Down
2 changes: 1 addition & 1 deletion 2 lib/matplotlib/backends/backend_pgf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -989,7 +989,7 @@ def __init__(self, filename, *, keep_empty=True, metadata=None):

Parameters
----------
filename : str
filename : str or path-like
Plots using :meth:`PdfPages.savefig` will be written to a file at
this location. Any older file with the same name is overwritten.
keep_empty : bool, optional
Expand Down
4 changes: 2 additions & 2 deletions 4 lib/matplotlib/backends/qt_editor/_formlayout.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -491,8 +491,8 @@ def fedit(data, title="", comment="", icon=None, parent=None, apply=None):
(if Cancel button is pressed, return None)

data: datalist, datagroup
title: string
comment: string
title: str
comment: str
icon: QIcon instance
parent: parent QWidget
apply: apply callback (function)
Expand Down
4 changes: 2 additions & 2 deletions 4 lib/matplotlib/category.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ def convert(value, unit, axis):

Parameters
----------
value : string or iterable
value : str or iterable
Value or list of values to be converted.
unit : `.UnitData`
An object mapping strings to integers.
Expand Down Expand Up @@ -93,7 +93,7 @@ def default_units(data, axis):

Parameters
----------
data : string or iterable of strings
data : str or iterable of str
axis : `~matplotlib.axis.Axis`
axis on which the data is plotted

Expand Down
2 changes: 1 addition & 1 deletion 2 lib/matplotlib/cbook/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -360,7 +360,7 @@ def to_filehandle(fname, flag='r', return_opened=False, encoding=None):

Parameters
----------
fname : str or PathLike or file-like object
fname : str or path-like or file-like object
If `str` or `os.PathLike`, the file is opened using the flags specified
by *flag* and *encoding*. If a file-like object, it is passed through.
flag : str, default 'r'
Expand Down
8 changes: 4 additions & 4 deletions 8 lib/matplotlib/collections.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -906,7 +906,7 @@ def legend_elements(self, prop="colors", num="auto",
to a `~.ticker.Locator` being used to find useful locations.
If a list or array, use exactly those elements for the legend.
Finally, a `~.ticker.Locator` can be provided.
fmt : string, `~matplotlib.ticker.Formatter`, or None (default)
fmt : str, `~matplotlib.ticker.Formatter`, or None (default)
The format or formatter to use for the labels. If a string must be
a valid input for a `~.StrMethodFormatter`. If None (the default),
use a `~.ScalarFormatter`.
Expand Down Expand Up @@ -1240,8 +1240,8 @@ def __init__(self, segments, # Can be None.
antialiaseds : sequence, optional
A sequence of ones or zeros.

linestyles : string, tuple, optional
Either one of [ 'solid' | 'dashed' | 'dashdot' | 'dotted' ], or
linestyles : str or tuple, optional
Either one of {'solid', 'dashed', 'dashdot', 'dotted'}, or
a dash tuple. The dash tuple is::

(offset, onoffseq)
Expand All @@ -1252,7 +1252,7 @@ def __init__(self, segments, # Can be None.
norm : Normalize, optional
`~.colors.Normalize` instance.

cmap : string or Colormap, optional
cmap : str or Colormap, optional
Colormap name or `~.colors.Colormap` instance.

pickradius : float, optional
Expand Down
4 changes: 2 additions & 2 deletions 4 lib/matplotlib/contour.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ def clabel(self, levels=None, *,
A list of level values, that should be labeled. The list must be
a subset of ``cs.levels``. If not given, all levels are labeled.

fontsize : string or float, optional
fontsize : str or float, optional
Size in points or relative size e.g., 'smaller', 'x-large'.
See `.Text.set_size` for accepted string values.

Expand Down Expand Up @@ -92,7 +92,7 @@ def clabel(self, levels=None, *,
This spacing will be exact for labels at locations where the
contour is straight, less so for labels on curved contours.

fmt : string or dict, optional
fmt : str or dict, optional
A format string for the label. Default is '%1.3f'

Alternatively, this can be a dictionary matching contour levels
Expand Down
Loading
Morty Proxy This is a proxified and sanitized view of the page, visit original site.