Skip to content

Commit 97fafd1

Browse files
anntzeranntzer
committed
Use docstring interpolation instead.
1 parent 5f1eabd commit 97fafd1

5 files changed

Lines changed: 69 additions & 71 deletions

File tree

‎lib/matplotlib/axes/_axes.py‎

Lines changed: 15 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,7 @@ 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_norm_vmin_vmax_doc)s
43734371
43744372
alpha : float, default: None
43754373
The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -4642,9 +4640,7 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,
46424640
46434641
Other Parameters
46444642
----------------
4645-
cmap, norm, vmin, vmax
4646-
Data normalization and colormapping parameters. See `~.Axes.imshow`
4647-
for a detailed description.
4643+
%(cmap_norm_vmin_vmax_doc)s
46484644
46494645
alpha : float between 0 and 1, optional
46504646
The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -5276,6 +5272,7 @@ def fill_betweenx(self, y, x1, x2=0, where=None,
52765272
# the documentation for *norm*, *vmax* and *vmin* together.
52775273
@_api.make_keyword_only("3.5", "aspect")
52785274
@_preprocess_data()
5275+
@_docstring.interpd
52795276
def imshow(self, X, cmap=None, norm=None, aspect=None,
52805277
interpolation=None, alpha=None,
52815278
vmin=None, vmax=None, origin=None, extent=None, *,
@@ -5314,34 +5311,7 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
53145311
53155312
Out-of-range RGB(A) values are clipped.
53165313
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.
5314+
%(cmap_norm_vmin_vmax_doc)s
53455315
53465316
aspect : {'equal', 'auto'} or float, default: :rc:`image.aspect`
53475317
The aspect ratio of the Axes. This parameter is particularly
@@ -5664,7 +5634,8 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
56645634
Parameters
56655635
----------
56665636
C : 2D array-like
5667-
The color-mapped values.
5637+
The color-mapped values. Color-mapping is controlled by *cmap*,
5638+
*norm*, *vmin*, and *vmax*.
56685639
56695640
X, Y : array-like, optional
56705641
The coordinates of the corners of quadrilaterals of a pcolormesh::
@@ -5711,9 +5682,7 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
57115682
See :doc:`/gallery/images_contours_and_fields/pcolormesh_grids`
57125683
for more description.
57135684
5714-
cmap, norm, vmin, vmax
5715-
Data normalization and colormapping parameters for *C*. See
5716-
`~.Axes.imshow` for a detailed description.
5685+
%(cmap_norm_vmin_vmax_doc)s
57175686
57185687
edgecolors : {'none', None, 'face', color, color sequence}, optional
57195688
The color of the edges. Defaults to 'none'. Possible values:
@@ -5894,7 +5863,8 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
58945863
Parameters
58955864
----------
58965865
C : 2D array-like
5897-
The color-mapped values.
5866+
The color-mapped values. Color-mapping is controlled by *cmap*,
5867+
*norm*, *vmin*, and *vmax*.
58985868
58995869
X, Y : array-like, optional
59005870
The coordinates of the corners of quadrilaterals of a pcolormesh::
@@ -5925,9 +5895,7 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
59255895
expanded as needed into the appropriate 2D arrays, making a
59265896
rectangular grid.
59275897
5928-
cmap, norm, vmin, vmax
5929-
Data normalization and colormapping parameters for *C*. See
5930-
`~.Axes.imshow` for a detailed description.
5898+
%(cmap_norm_vmin_vmax_doc)s
59315899
59325900
edgecolors : {'none', None, 'face', color, color sequence}, optional
59335901
The color of the edges. Defaults to 'none'. Possible values:
@@ -6117,8 +6085,8 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
61176085
C : array-like
61186086
The image data. Supported array shapes are:
61196087
6120-
- (M, N): an image with scalar data. The data is visualized
6121-
using a colormap.
6088+
- (M, N): an image with scalar data. Color-mapping is controlled
6089+
by *cmap*, *norm*, *vmin*, and *vmax*.
61226090
- (M, N, 3): an image with RGB values (0-1 float or 0-255 int).
61236091
- (M, N, 4): an image with RGBA values (0-1 float or 0-255 int),
61246092
i.e. including transparency.
@@ -6161,9 +6129,7 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
61616129
61626130
These arguments can only be passed positionally.
61636131
6164-
cmap, norm, vmin, vmax
6165-
Data normalization and colormapping parameters for *C*. See
6166-
`~.Axes.imshow` for a detailed description.
6132+
%(cmap_norm_vmin_vmax_doc)s
61676133
61686134
alpha : float, default: None
61696135
The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -6918,9 +6884,7 @@ def hist2d(self, x, y, bins=10, range=None, density=False, weights=None,
69186884
69196885
Other Parameters
69206886
----------------
6921-
cmap, norm, vmin, vmax
6922-
Data normalization and colormapping parameters. See `~.Axes.imshow`
6923-
for a detailed description.
6887+
%(cmap_norm_vmin_vmax_doc)s
69246888
69256889
alpha : ``0 <= scalar <= 1`` or ``None``, optional
69266890
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
@@ -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
1592+
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,7 @@ 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.
1637-
1638-
*cmap* cannot be given together with *colors*.
1635+
## cmap_norm_vmin_vmax_doc ##
16391636
16401637
If *vmin* or *vmax* are not given, the default color scaling is based on
16411638
*levels*.
@@ -1782,4 +1779,7 @@ def _initialize_x_y(self, z):
17821779
<https://en.wikipedia.org/wiki/Marching_squares>`_ algorithm to
17831780
compute contour locations. More information can be found in
17841781
`ContourPy documentation <https://contourpy.readthedocs.io>`_.
1785-
""")
1782+
""".replace(
1783+
"## cmap_norm_vmin_vmax_doc ##",
1784+
_docstring.interpd.params["cmap_norm_vmin_vmax_doc"])
1785+
)

‎lib/matplotlib/figure.py‎

Lines changed: 7 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,19 @@ 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_norm_vmin_vmax_doc)s
27052706
27062707
origin : {'upper', 'lower'}, default: :rc:`image.origin`
27072708
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
@@ -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.
@@ -143,11 +144,7 @@ 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.
149-
150-
*cmap* cannot be given together with *colors*.
147+
## cmap_norm_vmin_vmax_doc ##
151148
152149
If *vmin* or *vmax* are not given, the default color scaling is based on
153150
*levels*.
@@ -205,7 +202,10 @@ def _contour_args(self, args, kwargs):
205202
antialiased : bool, optional
206203
Enable antialiasing, overriding the defaults. For
207204
filled contours, the default is *True*. For line contours,
208-
it is taken from :rc:`lines.antialiased`.""")
205+
it is taken from :rc:`lines.antialiased`.""".replace(
206+
"## cmap_norm_vmin_vmax_doc ##",
207+
_docstring.interpd.params["cmap_norm_vmin_vmax_doc"])
208+
)
209209

210210

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

0 commit comments

Comments
 (0)