8000 Use docstring interpolation instead. · matplotlib/matplotlib@649eb06 · GitHub
[go: up one dir, main page]
Skip to content

Commit 649eb06

Browse files
anntzeranntzer
committed
Use docstring interpolation instead.
1 parent 46ec637 commit 649eb06

File tree

5 files changed

+108
-75
lines changed

5 files changed

+108
-75
lines changed

‎lib/matplotlib/axes/_axes.py

Lines changed: 43 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -4320,6 +4320,7 @@ def invalid_shape_exception(csize, xsize):
43204320
"edgecolors", "c", "facecolor",
43214321
"facecolors", "color"],
43224322
label_namer="y")
4323+
@_docstring.interpd
43234324
def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
43244325
vmin=None, vmax=None, alpha=None, linewidths=None, *,
43254326
edgecolors=None, plotnonfinite=False, **kwargs):
@@ -4366,10 +4367,11 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
43664367
See :mod:`matplotlib.markers` for more information about marker
43674368
styles.
43684369
4369-
cmap, norm, vmin, vmax
4370-
Data normalization and colormapping parameters for *c*; only used
4371-
if *c* is an array of floats. See `~.Axes.imshow` for a detailed
4372-
description.
4370+
%(cmap_doc)s
4371+
4372+
%(norm_doc)s
4373+
4374+
%(vmin_vmax_doc)s
43734375
43744376
alpha : float, default: None
43754377
The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -4642,9 +4644,11 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,
46424644
46434645
Other Parameters
46444646
----------------
4645-
cmap, norm, vmin, vmax
4646-
Data normalization and colormapping parameters. See `~.Axes.imshow`
4647-
for a detailed description.
4647+
%(cmap_doc)s
4648+
4649+
%(norm_doc)s
4650+
4651+
%(vmin_vmax_doc)s
46484652
46494653
alpha : float between 0 and 1, optional
46504654
The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -5276,6 +5280,7 @@ def fill_betweenx(self, y, x1, x2=0, where=None,
52765280
# the documentation for *norm*, *vmax* and *vmin* together.
52775281
@_api.make_keyword_only("3.5", "aspect")
52785282
@_preprocess_data()
5283+
@_docstring.interpd
52795284
def imshow(self, X, cmap=None, norm=None, aspect=None,
52805285
interpolation=None, alpha=None,
52815286
vmin=None, vmax=None, origin=None, extent=None, *,
@@ -5314,34 +5319,11 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
53145319
53155320
Out-of-range RGB(A) values are clipped.
53165321
5317-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
5318-
The Colormap instance or registered colormap name used to map
5319-
scalar data to colors. This parameter is ignored for RGB(A) data.
5320-
5321-
norm : str or `~matplotlib.colors.Normalize`, optional
5322-
The normalization method used to scale scalar data to the [0, 1]
5323-
range before mapping to colors using *cmap*. By default, a linear
5324-
scaling mapping the lowest value to 0 and the highest to 1 is used.
5325-
This parameter is ignored for RGB(A) data.
5326-
5327-
If given, this can be one of the following:
5328-
5329-
- An instance of `.Normalize` or one of its subclasses
5330-
(see :doc:`/tutorials/colors/colormapnorms`).
5331-
- A scale name, i.e. one of "linear", "log", "symlog", "logit",
5332-
etc. For a full list of available scales call
5333-
`matplotlib.scales.get_scale_names()`.
5334-
In that case, a suitable `.Normalize` subclass is dynamically
5335-
generated and instantiated.
5336-
5337-
vmin, vmax : float, optional
5338-
When using scalar data and no explicit *norm*, *vmin* and *vmax*
5339-
define the data range that the colormap covers. By default, the
5340-
colormap covers the complete value range of the supplied data. It
5341-
is an error to use *vmin*/*vmax* when a *norm* instance is given
5342-
(but using a `str` *norm* name together with *vmin*/*vmax* is
5343-
acceptable). When using RGB(A) data, parameters *vmin*/*vmax* are
5344-
ignored.
5322+
%(cmap_doc)s
5323+
5324+
%(norm_doc)s
5325+
5326+
%(vmin_vmax_doc)s
53455327
53465328
aspect : {'equal', 'auto'} or float, default: :rc:`image.aspect`
53475329
The aspect ratio of the Axes. This parameter is particularly
@@ -5664,7 +5646,8 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
56645646
Parameters
56655647
----------
56665648
C : 2D array-like
5667-
The color-mapped values.
5649+
The color-mapped values. Color-mapping is controlled by *cmap*,
5650+
*norm*, *vmin*, and *vmax*.
56685651
56695652
X, Y : array-like, optional
56705653
The coordinates of the corners of quadrilaterals of a pcolormesh::
@@ -5711,9 +5694,11 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
57115694
See :doc:`/gallery/images_contours_and_fields/pcolormesh_grids`
57125695
for more description.
57135696
5714-
cmap, norm, vmin, vmax
5715-
Data normalization and colormapping parameters for *C*. See
5716-
`~.Axes.imshow` for a detailed description.
5697+
%(cmap_doc)s
5698+
5699+
%(norm_doc)s
5700+
5701+
%(vmin_vmax_doc)s
57175702
57185703
edgecolors : {'none', None, 'face', color, color sequence}, optional
57195704
The color of the edges. Defaults to 'none'. Possible values:
@@ -5894,7 +5879,8 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
58945879
Parameters
58955880
----------
58965881
C : 2D array-like
5897-
The color-mapped values.
5882+
The color-mapped values. Color-mapping is controlled by *cmap*,
5883+
*norm*, *vmin*, and *vmax*.
58985884
58995885
X, Y : array-like, optional
59005886
The coordinates of the corners of quadrilaterals of a pcolormesh::
@@ -5925,9 +5911,11 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
59255911
expanded as needed into the appropriate 2D arrays, making a
59265912
rectangular grid.
59275913
5928-
cmap, norm, vmin, vmax
5929-
Data normalization and colormapping parameters for *C*. See
5930-
`~.Axes.imshow` for a detailed description.
5914+
%(cmap_doc)s
5915+
5916+
%(norm_doc)s
5917+
5918+
%(vmin_vmax_doc)s
59315919
59325920
edgecolors : {'none', None, 'face', color, color sequence}, optional
59335921
The color of the edges. Defaults to 'none'. Possible values:
@@ -6117,8 +6105,8 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
61176105
C : array-like
61186106
The image data. Supported array shapes are:
61196107
6120-
- (M, N): an image with scalar data. The data is visualized
6121-
using a colormap.
6108+
- (M, N): an image with scalar data. Color-mapping is controlled
6109+
by *cmap*, *norm*, *vmin*, and *vmax*.
61226110
- (M, N, 3): an image with RGB values (0-1 float or 0-255 int).
61236111
- (M, N, 4): an image with RGBA values (0-1 float or 0-255 int),
61246112
i.e. including transparency.
@@ -6161,9 +6149,11 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
61616149
61626150
These arguments can only be passed positionally.
61636151
6164-
cmap, norm, vmin, vmax
6165-
Data normalization and colormapping parameters for *C*. See
6166-
`~.Axes.imshow` for a detailed description.
6152+
%(cmap_doc)s
6153+
6154+
%(norm_doc)s
6155+
6156+
%(vmin_vmax_doc)s
61676157
61686158
alpha : float, default: None
61696159
The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -6918,9 +6908,11 @@ def hist2d(self, x, y, bins=10, range=None, density=False, weights=None,
69186908
69196909
Other Parameters
69206910
----------------
6921-
cmap, norm, vmin, vmax
6922-
Data normalization and colormapping parameters. See `~.Axes.imshow`
6923-
for a detailed description.
6911+
%(cmap_doc)s
6912+
6913+
%(norm_doc)s
6914+
6915+
%(vmin_vmax_doc)s
69246916
69256917
alpha : ``0 <= scalar <= 1`` or ``None``, optional
69266918
The alpha blending value.

‎lib/matplotlib/cm.py

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -633,3 +633,35 @@ def changed(self):
633633
"""
634634
self.callbacks.process('changed', self)
635635
self.stale = True
636+
637+
638+
# The docstrings here must be generic enough to apply to all relevant methods.
639+
mpl._docstring.interpd.update(
640+
cmap_doc="""\
641+
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
642+
The Colormap instance or registered colormap name used to map scalar data
643+
to colors. This parameter is ignored for RGB(A) data.""",
644+
norm_doc="""\
645+
norm : str or `~matplotlib.colors.Normalize`, optional
646+
The normalization method used to scale scalar data to the [0, 1] range
647+
before mapping to colors using *cmap*. By default, a linear scaling mapping
648+
the lowest value to 0 and the highest to 1 is used. This parameter is
649+
ignored for RGB(A) data.
650+
651+
If given, this can be one of the following:
652+
653+
- An instance of `.Normalize` or one of its subclasses
654+
(see :doc:`/tutorials/colors/colormapnorms`).
655+
- A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a
656+
list of available scales, call `matplotlib.scale.get_scale_names()`.
657+
In that case, a suitable `.Normalize` subclass is dynamically generated
658+
and instantiated.""",
659+
vmin_vmax_doc="""\
660+
vmin, vmax : float, optional
661+
When using scalar data and no explicit *norm*, *vmin* and *vmax* define
662+
the data range that the colormap covers. By default, the colormap covers
663+
the complete value range of the supplied data. It is an error to use
664+
*vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm*
665+
name together with *vmin*/*vmax* is acceptable). When using RGB(A) data,
666+
parameters *vmin*/*vmax* are ignored.""",
667+
)

‎lib/matplotlib/contour.py

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1588,7 +1588,8 @@ def _initialize_x_y(self, z):
15881588
``X = range(N)``, ``Y = range(M)``.
15891589
15901590
Z : (M, N) array-like
1591-
The height values over which the contour is drawn.
1591+
The height values over which the contour is drawn. Color-mapping is
15 179B 92+
controlled by *cmap*, *norm*, *vmin*, and *vmax*.
15921593
15931594
levels : int or array-like, optional
15941595
Determines the number and positions of the contour lines / regions.
@@ -1631,11 +1632,11 @@ def _initialize_x_y(self, z):
16311632
alpha : float, default: 1
16321633
The alpha blending value, between 0 (transparent) and 1 (opaque).
16331634
1634-
cmap, norm, vmin, vmax
1635-
Data normalization and colormapping parameters for *Z*. See `~.Axes.imshow`
1636-
for a detailed description.
1635+
%(cmap_doc)s
16371636
1638-
*cmap* cannot be given together with *colors*.
1637+
%(norm_doc)s
1638+
1639+
%(vmin_vmax_doc)s
16391640
16401641
If *vmin* or *vmax* are not given, the default color scaling is based on
16411642
*levels*.
@@ -1782,4 +1783,5 @@ def _initialize_x_y(self, z):
17821783
<https://en.wikipedia.org/wiki/Marching_squares>`_ algorithm to
17831784
compute contour locations. More information can be found in
17841785
`ContourPy documentation <https://contourpy.readthedocs.io>`_.
1785-
""")
1786+
""" % _docstring.interpd.params,
1787+
)

‎lib/matplotlib/figure.py

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2676,6 +2676,7 @@ def set_canvas(self, canvas):
26762676
"""
26772677
self.canvas = canvas
26782678

2679+
@_docstring.interpd
26792680
def figimage(self, X, xo=0, yo=0, alpha=None, norm=None, cmap=None,
26802681
vmin=None, vmax=None, origin=None, resize=False, **kwargs):
26812682
"""
@@ -2689,19 +2690,23 @@ def figimage(self, X, xo=0, yo=0, alpha=None, norm=None, cmap=None,
26892690
X
26902691
The image data. This is an array of one of the following shapes:
26912692
2692-
- MxN: luminance (grayscale) values
2693-
- MxNx3: RGB values
2694-
- MxNx4: RGBA values
2693+
- (M, N): an image with scalar data. Color-mapping is controlled
2694+
by *cmap*, *norm*, *vmin*, and *vmax*.
2695+
- (M, N, 3): an image with RGB values (0-1 float or 0-255 int).
2696+
- (M, N, 4): an image with RGBA values (0-1 float or 0-255 int),
2697+
i.e. including transparency.
26952698
26962699
xo, yo : int
26972700
The *x*/*y* image offset in pixels.
26982701
26992702
alpha : None or float
27002703
The alpha blending value.
27012704
2702-
cmap, norm, vmin, vmax
2703-
Data normalization and colormapping parameters for *X*. See
2704-
`~.Axes.imshow` for a detailed description.
2705+
%(cmap_doc)s
2706+
2707+
%(norm_doc)s
2708+
2709+
%(vmin_vmax_doc)s
27052710
27062711
origin : {'upper', 'lower'}, default: :rc:`image.origin`
27072712
Indicates where the [0, 0] index of the array is in the upper left

‎lib/matplotlib/tri/tricontour.py

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -82,12 +82,12 @@ def _contour_args(self, args, kwargs):
8282

8383

8484
_docstring.interpd.update(_tricontour_doc="""
85-
Draw contour %(type)s on an unstructured triangular grid.
85+
Draw contour %%(type)s on an unstructured triangular grid.
8686
8787
Call signatures::
8888
89-
%(func)s(triangulation, Z, [levels], ...)
90-
%(func)s(x, y, Z, [levels], *, [triangles=triangles], [mask=mask], ...)
89+
%%(func)s(triangulation, Z, [levels], ...)
90+
%%(func)s(x, y, Z, [levels], *, [triangles=triangles], [mask=mask], ...)
9191
9292
The triangular grid can be specified either by passing a `.Triangulation`
9393
object as the first parameter, or by passing the points *x*, *y* and
@@ -96,7 +96,7 @@ def _contour_args(self, args, kwargs):
9696
*triangles* are given, the triangulation is calculated on the fly.
9797
9898
It is possible to pass *triangles* positionally, i.e.
99-
``%(func)s(x, y, triangles, Z, ...)``. However, this is discouraged. For more
99+
``%%(func)s(x, y, triangles, Z, ...)``. However, this is discouraged. For more
100100
clarity, pass *triangles* via keyword argument.
101101
102102
Parameters
@@ -109,7 +109,8 @@ def _contour_args(self, args, kwargs):
109109
This is mutually exclusive with specifying *triangulation*.
110110
111111
Z : array-like
112-
The height values over which the contour is drawn.
112+
The height values over which the contour is drawn. Color-mapping is
113+
controlled by *cmap*, *norm*, *vmin*, and *vmax*.
113114
114115
levels : int or array-like, optional
115116
Determines the number and positions of the contour lines / regions.
@@ -128,7 +129,7 @@ def _contour_args(self, args, kwargs):
128129
Other Parameters
129130
----------------
130131
colors : color string or sequence of colors, optional
131-
The colors of the levels, i.e., the contour %(type)s.
132+
The colors of the levels, i.e., the contour %%(type)s.
132133
133134
The sequence is cycled for the levels in ascending order. If the sequence
134135
is shorter than the number of levels, it's repeated.
@@ -143,11 +144,11 @@ def _contour_args(self, args, kwargs):
143144
alpha : float, default: 1
144145
The alpha blending value, between 0 (transparent) and 1 (opaque).
145146
146-
cmap, norm, vmin, vmax
147-
Data normalization and colormapping parameters for *Z*. See `~.Axes.imshow`
148-
for a detailed description.
147+
%(cmap_doc)s
149148
150-
*cmap* cannot be given together with *colors*.
149+
%(norm_doc)s
150+
151+
%(vmin_vmax_doc)s
151152
152153
If *vmin* or *vmax* are not given, the default color scaling is based on
153154
*levels*.
@@ -177,7 +178,7 @@ def _contour_args(self, args, kwargs):
177178
Defaults to `~.ticker.MaxNLocator`.
178179
179180
extend : {'neither', 'both', 'min', 'max'}, default: 'neither'
180-
Determines the ``%(func)s``-coloring of values that are outside the
181+
Determines the ``%%(func)s``-coloring of values that are outside the
181182
*levels* range.
182183
183184
If 'neither', values outside the *levels* range are not colored. If 'min',
@@ -205,7 +206,8 @@ def _contour_args(self, args, kwargs):
205206
antialiased : bool, optional
206207
Enable antialiasing, overriding the defaults. For
207208
filled contours, the default is *True*. For line contours,
208-
it is taken from :rc:`lines.antialiased`.""")
209+
it is taken from :rc:`lines.antialiased`.""" % _docstring.interpd.params,
210+
)
209211

210212

211213
@_docstring.Substitution(func='tricontour', type='lines')

0 commit comments

Comments
 (0)
0