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

Commit 319a3ea

Browse files
anntzeranntzer
committed
Use docstring interpolation instead.
1 parent 7e82efa commit 319a3ea

File tree

5 files changed

+69
-71
lines changed

5 files changed

+69
-71
lines changed

‎lib/matplotlib/axes/_axes.py

Lines changed: 15 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -4314,6 +4314,7 @@ def invalid_shape_exception(csize, xsize):
43144314
"edgecolors", "c", "facecolor",
43154315
"facecolors", "color"],
43164316
label_namer="y")
4317+
@_docstring.interpd
43174318
def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
43184319
vmin=None, vmax=None, alpha=None, linewidths=None, *,
43194320
edgecolors=None, plotnonfinite=False, **kwargs):
@@ -4360,10 +4361,7 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
43604361
See :mod:`matplotlib.markers` for more information about marker
43614362
styles.
43624363
4363-
cmap, norm, vmin, vmax
4364-
Data normalization and colormapping parameters for *c*; only used
4365-
if *c* is an array of floats. See `~.Axes.imshow` for a detailed
4366-
description.
4364+
%(cmap_norm_vmin_vmax_doc)s
43674365
43684366
alpha : float, default: None
43694367
The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -4636,9 +4634,7 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,
46364634
46374635
Other Parameters
46384636
----------------
4639-
cmap, norm, vmin, vmax
4640-
Data normalization and colormapping parameters. See `~.Axes.imshow`
4641-
for a detailed description.
4637+
%(cmap_norm_vmin_vmax_doc)s
46424638
46434639
alpha : float between 0 and 1, optional
46444640
The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -5270,6 +5266,7 @@ def fill_betweenx(self, y, x1, x2=0, where=None,
52705266
# the documentation for *norm*, *vmax* and *vmin* together.
52715267
@_api.make_keyword_only("3.5", "aspect")
52725268
@_preprocess_data()
5269+
@_docstring.interpd
52735270
def imshow(self, X, cmap=None, norm=None, aspect=None,
52745271
interpolation=None, alpha=None,
52755272
vmin=None, vmax=None, origin=None, extent=None, *,
@@ -5308,34 +5305,7 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
53085305
53095306
Out-of-range RGB(A) values are clipped.
53105307
5311-
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
5312-
The Colormap instance or registered colormap name used to map
5313-
scalar data to colors. This parameter is ignored for RGB(A) data.
5314-
5315-
norm : str or `~matplotlib.colors.Normalize`, optional
5316-
The normalization method used to scale scalar data to the [0, 1]
5317-
range before mapping to colors using *cmap*. By default, a linear
5318-
scaling mapping the lowest value to 0 and the highest to 1 is used.
5319-
This parameter is ignored for RGB(A) data.
5320-
5321-
If given, this can be one of the following:
5322-
5323-
- An instance of `.Normalize` or one of its subclasses
5324-
(see :doc:`/tutorials/colors/colormapnorms`).
5325-
- A scale name, i.e. one of "linear", "log", "symlog", "logit",
5326-
etc. For a full list of available scales call
5327-
`matplotlib.scales.get_scale_names()`.
5328-
In that case, a suitable `.Normalize` subclass is dynamically
5329-
generated and instantiated.
5330-
5331-
vmin, vmax : float, optional
5332-
When using scalar data and no explicit *norm*, *vmin* and *vmax*
5333-
define the data range that the colormap covers. By default, the
5334-
colormap covers the complete value range of the supplied data. It
5335-
is an error to use *vmin*/*vmax* when a *norm* instance is given
5336-
(but using a `str` *norm* name together with *vmin*/*vmax* is
5337-
acceptable). When using RGB(A) data, parameters *vmin*/*vmax* are
5338-
ignored.
5308+
%(cmap_norm_vmin_vmax_doc)s
53395309
53405310
aspect : {'equal', 'auto'} or float, default: :rc:`image.aspect`
53415311
The aspect ratio of the Axes. This parameter is particularly
@@ -5657,7 +5627,8 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
56575627
Parameters
56585628
----------
56595629
C : 2D array-like
5660-
The color-mapped values.
5630+
The color-mapped values. Color-mapping is controlled by *cmap*,
5631+
*norm*, *vmin*, and *vmax*.
56615632
56625633
X, Y : array-like, optional
56635634
The coordinates of the corners of quadrilaterals of a pcolormesh::
@@ -5704,9 +5675,7 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
57045675
See :doc:`/gallery/images_contours_and_fields/pcolormesh_grids`
57055676
for more description.
57065677
5707-
cmap, norm, vmin, vmax
5708-
Data normalization and colormapping parameters for *C*. See
5709-
`~.Axes.imshow` for a detailed description.
5678+
%(cmap_norm_vmin_vmax_doc)s
57105679
57115680
edgecolors : {'none', None, 'face', color, color sequence}, optional
57125681
The color of the edges. Defaults to 'none'. Possible values:
@@ -5887,7 +5856,8 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
58875856
Parameters
58885857
----------
58895858
C : 2D array-like
5890-
The color-mapped values.
5859+
The color-mapped values. Color-mapping is controlled by *cmap*,
5860+
*norm*, *vmin*, and *vmax*.
58915861
58925862
X, Y : array-like, optional
58935863
The coordinates of the corners of quadrilaterals of a pcolormesh::
@@ -5918,9 +5888,7 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
59185888
expanded as needed into the appropriate 2D arrays, making a
59195889
rectangular grid.
59205890
5921-
cmap, norm, vmin, vmax
5922-
Data normalization and colormapping parameters for *C*. See
5923-
`~.Axes.imshow` for a detailed description.
5891+
%(cmap_norm_vmin_vmax_doc)s
59245892
59255893
edgecolors : {'none', None, 'face', color, color sequence}, optional
59265894
The color of the edges. Defaults to 'none'. Possible values:
@@ -6110,8 +6078,8 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
61106078
C : array-like
61116079
The image data. Supported array shapes are:
61126080
6113-
- (M, N): an image with scalar data. The data is visualized
6114-
using a colormap.
6081+
- (M, N): an image with scalar data. Color-mapping is controlled
6082+
by *cmap*, *norm*, *vmin*, and *vmax*.
61156083
- (M, N, 3): an image with RGB values (0-1 float or 0-255 int).
61166084
- (M, N, 4): an image with RGBA values (0-1 float or 0-255 int),
61176085
i.e. including transparency.
@@ -6154,9 +6122,7 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
61546122
61556123
These arguments can only be passed positionally.
61566124
6157-
cmap, norm, vmin, vmax
6158-
Data normalization and colormapping parameters for *C*. See
6159-
`~.Axes.imshow` for a detailed description.
6125+
%(cmap_norm_vmin_vmax_doc)s
61606126
61616127
alpha : float, default: None
61626128
The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -6911,9 +6877,7 @@ def hist2d(self, x, y, bins=10, range=None, density=False, weights=None,
69116877
69126878
Other Parameters
69136879
----------------
6914-
cmap, norm, vmin, vmax
6915-
Data normalization and colormapping parameters. See `~.Axes.imshow`
6916-
for a detailed description.
6880+
%(cmap_norm_vmin_vmax_doc)s
69176881
69186882
alpha : ``0 <= scalar <= 1`` or ``None``, optional
69196883
The alpha blending value.

‎lib/matplotlib/cm.py

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

‎lib/matplotlib/contour.py

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1586,7 +1586,8 @@ def _initialize_x_y(self, z):
15861586
``X = range(N)``, ``Y = range(M)``.
15871587
15881588
Z : (M, N) array-like
1589 E377 -
The height values over which the contour is drawn.
1589+
The height values over which the contour is drawn. Color-mapping is
1590+
controlled by *cmap*, *norm*, *vmin*, and *vmax*.
15901591
15911592
levels : int or array-like, optional
15921593
Determines the number and positions of the contour lines / regions.
@@ -1629,11 +1630,7 @@ def _initialize_x_y(self, z):
16291630
alpha : float, default: 1
16301631
The alpha blending value, between 0 (transparent) and 1 (opaque).
16311632
1632-
cmap, norm, vmin, vmax
1633-
Data normalization and colormapping parameters for *Z*. See `~.Axes.imshow`
1634-
for a detailed description.
1635-
1636-
*cmap* cannot be given together with *colors*.
1633+
## cmap_norm_vmin_vmax_doc ##
16371634
16381635
If *vmin* or *vmax* are not given, the default color scaling is based on
16391636
*levels*.
@@ -1780,4 +1777,7 @@ def _initialize_x_y(self, z):
17801777
<https://en.wikipedia.org/wiki/Marching_squares>`_ algorithm to
17811778
compute contour locations. More information can be found in
17821779
`ContourPy documentation <https://contourpy.readthedocs.io>`_.
1783-
""")
1780+
""".replace(
1781+
"## cmap_norm_vmin_vmax_doc ##",
1782+
_docstring.interpd.params["cmap_norm_vmin_vmax_doc"])
1783+
)

‎lib/matplotlib/figure.py

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2653,6 +2653,7 @@ def set_canvas(self, canvas):
26532653
"""
26542654
self.canvas = canvas
26552655

2656+
@_docstring.interpd
26562657
def figimage(self, X, xo=0, yo=0, alpha=None, norm=None, cmap=None,
26572658
vmin=None, vmax=None, origin=None, resize=False, **kwargs):
26582659
"""
@@ -2666,19 +2667,19 @@ def figimage(self, X, xo=0, yo=0, alpha=None, norm=None, cmap=None,
26662667
X
26672668
The image data. This is an array of one of the following shapes:
26682669
2669-
- MxN: luminance (grayscale) values
2670-
- MxNx3: RGB values
2671-
- MxNx4: RGBA values
< F438 /td>
2670+
- (M, N): an image with scalar data. Color-mapping is controlled
2671+
by *cmap*, *norm*, *vmin*, and *vmax*.
2672+
- (M, N, 3): an image with RGB values (0-1 float or 0-255 int).
2673+
- (M, N, 4): an image with RGBA values (0-1 float or 0-255 int),
2674+
i.e. including transparency.
26722675
26732676
xo, yo : int
26742677
The *x*/*y* image offset in pixels.
26752678
26762679
alpha : None or float
26772680
The alpha blending value.
26782681
2679-
cmap, norm, vmin, vmax
2680-
Data normalization and colormapping parameters for *X*. See
2681-
`~.Axes.imshow` for a detailed description.
2682+
%(cmap_norm_vmin_vmax_doc)s
26822683
26832684
origin : {'upper', 'lower'}, default: :rc:`image.origin`
26842685
Indicates where the [0, 0] index of the array is in the upper left

‎lib/matplotlib/tri/tricontour.py

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -146,7 +146,8 @@ def _contour_args(self, args, kwargs):
146146
Which triangles are masked out.
147147
148148
Z : 2D array-like
149-
The height values over which the contour is drawn.
149+
The height values over which the contour is drawn. Color-mapping is
150+
controlled by *cmap*, *norm*, *vmin*, and *vmax*.
150151
151152
levels : int or array-like, optional
152153
Determines the number and positions of the contour lines / regions.
@@ -180,11 +181,7 @@ def _contour_args(self, args, kwargs):
180181
alpha : float, default: 1
181182
The alpha blending value, between 0 (transparent) and 1 (opaque).
182183
183-
cmap, norm, vmin, vmax
184-
Data normalization and colormapping parameters for *Z*. See `~.Axes.imshow`
185-
for a detailed description.
186-
187-
*cmap* cannot be given together with *colors*.
184+
## cmap_norm_vmin_vmax_doc ##
188185
189186
If *vmin* or *vmax* are not given, the default color scaling is based on
190187
*levels*.
@@ -242,7 +239,10 @@ def _contour_args(self, args, kwargs):
242239
antialiased : bool, optional
243240
Enable antialiasing, overriding the defaults. For
244241
filled contours, the default is *True*. For line contours,
245-
it is taken from :rc:`lines.antialiased`.""")
242+
it is taken from :rc:`lines.antialiased`.""".replace(
243+
"## cmap_norm_vmin_vmax_doc ##",
244+
_docstring.interpd.params["cmap_norm_vmin_vmax_doc"])
245+
)
246246

247247

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

0 commit comments

Comments
 (0)
0