matplotlib · timhoffm · Feb 6, 2021 · Feb 4, 2021
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -462,18 +462,19 @@ Use ``array-like`` for homogeneous numeric sequences, which could
 typically be a numpy.array. Dimensionality may be specified using ``2D``,
 ``3D``, ``n-dimensional``. If you need to have variables denoting the
 sizes of the dimensions, use capital letters in brackets
-(``array-like (M, N)``). When referring to them in the text they are easier
-read and no special formatting is needed.
+(``(M, N) array-like``). When referring to them in the text they are easier
+read and no special formatting is needed. Use ``array`` instead of
+``array-like`` for return types if the returned object is indeed a numpy array.
 
 ``float`` is the implicit default dtype for array-likes. For other dtypes
 use ``array-like of int``.
 
 Some possible uses::
 
   2D array-like
-  array-like (N)
-  array-like (M, N)
-  array-like (M, N, 3)
+  (N,) array-like
+  (M, N) array-like
+  (M, N, 3) array-like
   array-like of int
 
 Non-numeric homogeneous sequences are described as lists, e.g.::

diff --git a/examples/lines_bars_and_markers/hat_graph.py b/examples/lines_bars_and_markers/hat_graph.py
@@ -22,7 +22,7 @@ def hat_graph(ax, xlabels, values, group_labels):
         The Axes to plot into.
     xlabels : list of str
         The category names to be displayed on the x-axis.
-    values : array-like (M, N)
+    values : (M, N) array-like
         The data values.
         Rows are the groups (len(group_labels) == M).
         Columns are the categories (len(xlabels) == N).

diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -3622,7 +3622,7 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
             95% confidence intervals. Values between 1000 and 10000 are
             recommended.
 
-        usermedians : array-like, optional
+        usermedians : 1D array-like, optional
             A 1D array-like of length ``len(x)``.  Each entry that is not
             `None` forces the value of the median for the corresponding
             dataset.  For entries that are `None`, the medians are computed
@@ -5747,8 +5747,8 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
 
         Parameters
         ----------
-        C : array-like
-            A scalar 2D array. The values will be color-mapped.
+        C : 2D array-like
+            The color-mapped values.
 
         X, Y : array-like, optional
             The coordinates of the corners of quadrilaterals of a pcolormesh::
@@ -5991,8 +5991,8 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
 
         Parameters
         ----------
-        C : array-like
-            A scalar 2D array. The values will be color-mapped.
+        C : 2D array-like
+            The color-mapped values.
 
         X, Y : array-like, optional
             The coordinates of the corners of quadrilaterals of a pcolormesh::
@@ -6227,7 +6227,7 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
 
         Parameters
         ----------
-        C : array-like(M, N)
+        C : array-like
             The image data. Supported array shapes are:
 
             - (M, N): an image with scalar data. The data is visualized
@@ -7748,7 +7748,7 @@ def spy(self, Z, precision=0, marker=None, markersize=None,
 
         Parameters
         ----------
-        Z : array-like (M, N)
+        Z : (M, N) array-like
             The array to be plotted.
 
         precision : float or 'present', default: 0
@@ -7872,7 +7872,7 @@ def matshow(self, Z, **kwargs):
 
         Parameters
         ----------
-        Z : array-like(M, N)
+        Z : (M, N) array-like
             The matrix to be displayed.
 
         Returns

diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -297,16 +297,12 @@ def draw_gouraud_triangle(self, gc, points, colors, transform):
         ----------
         gc : `.GraphicsContextBase`
             The graphics context.
-
-        points : array-like, shape=(3, 2)
+        points : (3, 2) array-like
             Array of (x, y) points for the triangle.
-
-        colors : array-like, shape=(3, 4)
+        colors : (3, 4) array-like
             RGBA colors for each point of the triangle.
-
         transform : `matplotlib.transforms.Transform`
             An affine transform to apply to the points.
-
         """
         raise NotImplementedError
 
@@ -317,12 +313,10 @@ def draw_gouraud_triangles(self, gc, triangles_array, colors_array,
 
         Parameters
         ----------
-        points : array-like, shape=(N, 3, 2)
+        points : (N, 3, 2) array-like
             Array of *N* (x, y) points for the triangles.
-
-        colors : array-like, shape=(N, 3, 4)
+        colors : (N, 3, 4) array-like
             Array of *N* RGBA colors for each point of the triangles.
-
         transform : `matplotlib.transforms.Transform`
             An affine transform to apply to the points.
         """
@@ -502,7 +496,7 @@ def draw_image(self, gc, x, y, im, transform=None):
             The distance in physical units (i.e., dots or pixels) from the
             bottom side of the canvas.
 
-        im : array-like, shape=(N, M, 4), dtype=np.uint8
+        im : (N, M, 4) array-like of np.uint8
             An array of RGBA pixels.
 
         transform : `matplotlib.transforms.Affine2DBase`

diff --git a/lib/matplotlib/bezier.py b/lib/matplotlib/bezier.py
@@ -204,12 +204,12 @@ def __call__(self, t):
 
         Parameters
         ----------
-        t : float (k,) array_like
+        t : (k,) array-like
             Points at which to evaluate the curve.
 
         Returns
         -------
-        float (k, d) array_like
+        (k, d) array
             Value of the curve for each point in *t*.
         """
         t = np.asarray(t)
@@ -246,7 +246,7 @@ def polynomial_coefficients(self):
 
         Returns
         -------
-        float, (n+1, d) array_like
+        (n+1, d) array
             Coefficients after expanding in polynomial basis, where :math:`n`
             is the degree of the bezier curve and :math:`d` its dimension.
             These are the numbers (:math:`C_j`) such that the curve can be
@@ -282,10 +282,10 @@ def axis_aligned_extrema(self):
 
         Returns
         -------
-        dims : int, array_like
+        dims : array of int
             Index :math:`i` of the partial derivative which is zero at each
             interior extrema.
-        dzeros : float, array_like
+        dzeros : array of float
             Of same size as dims. The :math:`t` such that :math:`d/dx_i B(t) =
             0`
         """
@@ -313,7 +313,7 @@ def split_bezier_intersecting_with_closedpath(
 
     Parameters
     ----------
-    bezier : array-like(N, 2)
+    bezier : (N, 2) array-like
         Control points of the Bezier segment. See `.BezierSegment`.
     inside_closedpath : callable
         A function returning True if a given point (x, y) is inside the

diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py
@@ -537,7 +537,7 @@ def set_offsets(self, offsets):
 
         Parameters
         ----------
-        offsets : array-like (N, 2) or (2,)
+        offsets : (N, 2) or (2,) array-like
         """
         offsets = np.asanyarray(offsets, float)
         if offsets.shape == (2,):  # Broadcast (2,) -> (1, 2) but nothing else.
@@ -1714,15 +1714,11 @@ def __init__(self, widths, heights, angles, units='points', **kwargs):
         ----------
         widths : array-like
             The lengths of the first axes (e.g., major axis lengths).
-
         heights : array-like
             The lengths of second axes.
-
         angles : array-like
             The angles of the first axes, degrees CCW from the x-axis.
-
         units : {'points', 'inches', 'dots', 'width', 'height', 'x', 'y', 'xy'}
-
             The units in which majors and minors are given; 'width' and
             'height' refer to the dimensions of the axes, while 'x' and 'y'
             refer to the *offsets* data units. 'xy' differs from all others in

diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py
@@ -440,12 +440,12 @@ def _create_lookup_table(N, data, gamma=1.0):
     N : int
         The number of elements of the created lookup table; at least 1.
 
-    data : Mx3 array-like or callable
+    data : (M, 3) array-like or callable
         Defines the mapping :math:`f`.
 
-        If a Mx3 array-like, the rows define values (x, y0, y1). The x values
-        must start with x=0, end with x=1, and all x values be in increasing
-        order.
+        If a (M, 3) array-like, the rows define values (x, y0, y1).  The x
+        values must start with x=0, end with x=1, and all x values be in
+        increasing order.
 
         A value between :math:`x_i` and :math:`x_{i+1}` is mapped to the range
         :math:`y^1_{i-1} \ldots y^0_i` by linear interpolation.
@@ -581,7 +581,7 @@ def __call__(self, X, alpha=None, bytes=False):
             return the RGBA values ``X*100`` percent along the Colormap line.
             For integers, X should be in the interval ``[0, Colormap.N)`` to
             return RGBA values *indexed* from the Colormap with index ``X``.
-        alpha : float, array-like, None
+        alpha : float or array-like or None
             Alpha must be a scalar between 0 and 1, a sequence of such
             floats with shape matching X, or None.
         bytes : bool
@@ -1959,9 +1959,8 @@ def hillshade(self, elevation, vert_exag=1, dx=1, dy=1, fraction=1.):
 
         Parameters
         ----------
-        elevation : array-like
-            A 2D array (or equivalent) of the height values used to generate an
-            illumination map
+        elevation : 2D array-like
+            The height values used to generate an illumination map
         vert_exag : number, optional
             The amount to exaggerate the elevation values by when calculating
             illumination. This can be used either to correct for differences in
@@ -2057,9 +2056,8 @@ def shade(self, data, cmap, norm=None, blend_mode='overlay', vmin=None,
 
         Parameters
         ----------
-        data : array-like
-            A 2D array (or equivalent) of the height values used to generate a
-            shaded map.
+        data : 2D array-like
+            The height values used to generate a shaded map.
         cmap : `~matplotlib.colors.Colormap`
             The colormap used to color the *data* array. Note that this must be
             a `~matplotlib.colors.Colormap` instance.  For example, rather than

diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py
@@ -1539,7 +1539,7 @@ def _initialize_x_y(self, z):
             If not given, they are assumed to be integer indices, i.e.
             ``X = range(M)``, ``Y = range(N)``.
 
-        Z : array-like(N, M)
+        Z : (M, N) array-like
             The height values over which the contour is drawn.
 
         levels : int or array-like, optional

diff --git a/lib/matplotlib/path.py b/lib/matplotlib/path.py
@@ -102,14 +102,11 @@ def __init__(self, vertices, codes=None, _interpolation_steps=1,
 
         Parameters
         ----------
-        vertices : array-like
-            The ``(N, 2)`` float array, masked array or sequence of pairs
-            representing the vertices of the path.
-
-            If *vertices* contains masked values, they will be converted
-            to NaNs which are then handled correctly by the Agg
-            PathIterator and other consumers of path data, such as
-            :meth:`iter_segments`.
+        vertices : (N, 2) array-like
+            The path vertices, as an array, masked array or sequence of pairs.
+            Masked values, if any, will be converted to NaNs, which are then
+            handled correctly by the Agg PathIterator and other consumers of
+            path data, such as :meth:`iter_segments`.
         codes : array-like or None, optional
             n-length array integers representing the codes of the path.
             If not None, codes must be the same length as vertices.

diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -2368,7 +2368,7 @@ def matshow(A, fignum=None, **kwargs):
 
     Parameters
     ----------
-    A : array-like(M, N)
+    A : 2D array-like
         The matrix to be displayed.
 
     fignum : None or int or False

diff --git a/lib/matplotlib/stackplot.py b/lib/matplotlib/stackplot.py
@@ -4,8 +4,8 @@
 http://stackoverflow.com/questions/2225995/how-can-i-create-stacked-line-graph-with-matplotlib
 
 (http://stackoverflow.com/users/66549/doug)
-
 """
+
 import numpy as np
 
 from matplotlib import _api
@@ -21,10 +21,9 @@ def stackplot(axes, x, *args,
 
     Parameters
     ----------
-    x : array-like (N)
-
-    y : 2D array (M, N) or sequence of array-like (N)
+    x : (N,) array-like
 
+    y : (M, N) array-like
         The data is assumed to be unstacked. Each of the following
         calls is legal::
 

diff --git a/lib/matplotlib/tri/triangulation.py b/lib/matplotlib/tri/triangulation.py
@@ -9,22 +9,22 @@ class Triangulation:
 
     Parameters
     ----------
-    x, y : array-like of shape (npoints)
+    x, y : (npoints,) array-like
         Coordinates of grid points.
-    triangles : int array-like of shape (ntri, 3), optional
+    triangles : (ntri, 3) array-like of int, optional
         For each triangle, the indices of the three points that make
         up the triangle, ordered in an anticlockwise manner.  If not
         specified, the Delaunay triangulation is calculated.
-    mask : bool array-like of shape (ntri), optional
+    mask : (ntri,) array-like of bool, optional
         Which triangles are masked out.
 
     Attributes
     ----------
-    triangles : int array-like of shape (ntri, 3)
+    triangles : (ntri, 3) array of int
         For each triangle, the indices of the three points that make
         up the triangle, ordered in an anticlockwise manner. If you want to
         take the *mask* into account, use `get_masked_triangles` instead.
-    mask : bool array of shape (ntri, 3)
+    mask : (ntri, 3) array of bool
         Masked out triangles.
     is_delaunay : bool
         Whether the Triangulation is a calculated Delaunay

diff --git a/lib/matplotlib/tri/tricontour.py b/lib/matplotlib/tri/tricontour.py
@@ -153,15 +153,15 @@ def _contour_args(self, args, kwargs):
 x, y : array-like, optional
     The coordinates of the values in *Z*.
 
-triangles : int array-like of shape (ntri, 3), optional
+triangles : (ntri, 3) array-like of int, optional
     For each triangle, the indices of the three points that make up the
     triangle, ordered in an anticlockwise manner.  If not specified, the
     Delaunay triangulation is calculated.
 
-mask : bool array-like of shape (ntri), optional
+mask : (ntri,) array-like of bool, optional
     Which triangles are masked out.
 
-Z : array-like(N, M)
+Z : 2D array-like
     The height values over which the contour is drawn.
 
 levels : int or array-like, optional

diff --git a/lib/matplotlib/tri/triinterpolate.py b/lib/matplotlib/tri/triinterpolate.py
@@ -242,7 +242,7 @@ class LinearTriInterpolator(TriInterpolator):
     ----------
     triangulation : `~matplotlib.tri.Triangulation`
         The triangulation to interpolate over.
-    z : array-like of shape (npoints,)
+    z : (npoints,) array-like
         Array of values, defined at grid points, to interpolate between.
     trifinder : `~matplotlib.tri.TriFinder`, optional
         If this is not specified, the Triangulation's default TriFinder will
@@ -305,7 +305,7 @@ class CubicTriInterpolator(TriInterpolator):
     ----------
     triangulation : `~matplotlib.tri.Triangulation`
         The triangulation to interpolate over.
-    z : array-like of shape (npoints,)
+    z : (npoints,) array-like
         Array of values, defined at grid points, to interpolate between.
     kind : {'min_E', 'geom', 'user'}, optional
         Choice of the smoothing algorithm, in order to compute

diff --git a/lib/matplotlib/tri/trirefine.py b/lib/matplotlib/tri/trirefine.py
@@ -136,7 +136,7 @@ def refine_field(self, z, triinterpolator=None, subdiv=3):
 
         Parameters
         ----------
-        z : array-like of length ``n_points``
+        z : (npoints,) array-like
             Values of the field to refine, defined at the nodes of the
             encapsulated triangulation. (``n_points`` is the number of points
             in the initial triangulation)

diff --git a/lib/matplotlib/tri/tritools.py b/lib/matplotlib/tri/tritools.py
@@ -143,7 +143,7 @@ def get_flat_tri_mask(self, min_circle_ratio=0.01, rescale=True):
 
         Returns
         -------
-        bool array-like
+        array of bool
             Mask to apply to encapsulated triangulation.
             All the initially masked triangles remain masked in the
             *new_mask*.