API reference: Shorten supported argument types in docstrings (#2746)

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

Author: yvonnefroehlich

pygmt/helpers/decorators.py

@@ -16,7 +16,7 @@
 
 COMMON_DOCSTRINGS = {
     "area_thresh": r"""
-        area_thresh : int or float or str
+        area_thresh : float or str
             *min_area*\ [/*min_level*/*max_level*][**+a**\[**g**\|\ **i**]\
             [**s**\|\ **S**]][**+l**\|\ **r**][**+p**\ *percent*].
             Features with an area smaller than *min_area* in km\ :sup:`2` or of
@@ -105,7 +105,7 @@
             that do not match the pattern. Append **i** for case insensitive
             matching. This does not apply to headers or segment headers.""",
     "frame": r"""
-        frame : bool or str or list
+        frame : bool, str, or list
             Set map boundary
             :doc:`frame and axes attributes </tutorials/basics/frames>`. """,
     "gap": r"""
@@ -247,7 +247,7 @@
               used then the columns given to ``outcols`` correspond to the
               order after the ``incols`` selection has taken place.""",
     "panel": r"""
-        panel : bool or int or list
+        panel : bool, int, or list
             [*row,col*\|\ *index*].
             Select a specific subplot panel. Only allowed when in subplot
             mode. Use ``panel=True`` to advance to the next panel in the
@@ -298,7 +298,7 @@
                   more of the columns equal NaN [Default skips record only
                   if values in all specified *cols* equal NaN].""",
     "spacing": r"""
-        spacing : int or float or str or list or tuple
+        spacing : float, str, or list
             *x_inc*\ [**+e**\|\ **n**][/\ *y_inc*\ [**+e**\|\ **n**]].
             *x_inc* [and optionally *y_inc*] is the grid spacing.
 
@@ -329,7 +329,7 @@
             the registration have already been initialized; use ``spacing`` and
             ``registration`` to override these values.""",
     "transparency": r"""
-        transparency : int or float
+        transparency : float
             Set transparency level, in [0-100] percent range
             [Default is ``0``, i.e., opaque].
             Only visible when PDF or raster format output is selected.
@@ -400,7 +400,7 @@ def fmt_docstring(module_func):
     ...
     ...     Parameters
     ...     ----------
-    ...     data : str or {table-like}
+    ...     data : str, {table-like}
     ...         Pass in either a file name to an ASCII data table, a 2-D
     ...         {table-classes}.
     ...     {region}
@@ -416,7 +416,7 @@ def fmt_docstring(module_func):
     <BLANKLINE>
     Parameters
     ----------
-    data : str or numpy.ndarray or pandas.DataFrame or xarray.Dataset or geo...
+    data : str, numpy.ndarray, pandas.DataFrame, xarray.Dataset, or geo...
         Pass in either a file name to an ASCII data table, a 2-D
         :class:`numpy.ndarray`, a :class:`pandas.DataFrame`, an
         :class:`xarray.Dataset` made up of 1-D :class:`xarray.DataArray`
@@ -444,13 +444,15 @@ def fmt_docstring(module_func):
             aliases.append(f"- {arg} = {alias}")
         filler_text["aliases"] = "\n".join(aliases)
 
-    filler_text["table-like"] = " or ".join(
-        [
-            "numpy.ndarray",
-            "pandas.DataFrame",
-            "xarray.Dataset",
-            "geopandas.GeoDataFrame",
-        ]
+    filler_text["table-like"] = (
+        ", ".join(
+            [
+                "numpy.ndarray",
+                "pandas.DataFrame",
+                "xarray.Dataset",
+            ]
+        )
+        + ", or geopandas.GeoDataFrame"
     )
     filler_text["table-classes"] = (
         ":class:`numpy.ndarray`, a :class:`pandas.DataFrame`, an\n"

pygmt/src/binstats.py

@@ -48,7 +48,7 @@ def binstats(data, **kwargs):
 
     Parameters
     ----------
-    data : str or {table-like}
+    data : str, {table-like}
         A file name of an ASCII data table or a 2-D
         {table-classes}.
     outgrid : str or None
@@ -78,7 +78,7 @@ def binstats(data, **kwargs):
         - **u** for maximum (upper)
         - **U** for maximum of negative values only
         - **z** for the sum
-    empty : float or int
+    empty : float
         Set the value assigned to empty nodes [Default is NaN].
     normalize : bool
         Normalize the resulting grid values by the area represented by the

pygmt/src/blockm.py

@@ -105,7 +105,7 @@ def blockmean(data=None, x=None, y=None, z=None, outfile=None, **kwargs):
 
     Parameters
     ----------
-    data : str or {table-like}
+    data : str, {table-like}
         Pass in (x, y, z) or (longitude, latitude, elevation) values by
         providing a file name to an ASCII data table, a 2-D
         {table-classes}.
@@ -201,7 +201,7 @@ def blockmedian(data=None, x=None, y=None, z=None, outfile=None, **kwargs):
 
     Parameters
     ----------
-    data : str or {table-like}
+    data : str, {table-like}
         Pass in (x, y, z) or (longitude, latitude, elevation) values by
         providing a file name to an ASCII data table, a 2-D
         {table-classes}.
@@ -288,7 +288,7 @@ def blockmode(data=None, x=None, y=None, z=None, outfile=None, **kwargs):
 
     Parameters
     ----------
-    data : str or {table-like}
+    data : str, {table-like}
         Pass in (x, y, z) or (longitude, latitude, elevation) values by
         providing a file name to an ASCII data table, a 2-D
         {table-classes}.

pygmt/src/coast.py

@@ -81,7 +81,7 @@ def coast(self, **kwargs):
         and (**c**\ )rude.
     land : str
         Select filling or clipping of "dry" areas.
-    rivers : int or str or list
+    rivers : int, str, or list
         *river*\ [/*pen*].
         Draw rivers. Specify the type of rivers and [optionally] append
         pen attributes [Default is ``"0.25p,black,solid"``].
@@ -128,7 +128,7 @@ def coast(self, **kwargs):
         [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\
         **+w**\ *length*.
         Draw a simple map scale centered on the reference point specified.
-    borders : int or str or list
+    borders : int, str, or list
         *border*\ [/*pen*].
         Draw political boundaries. Specify the type of boundary and
         [optionally] append pen attributes
@@ -146,7 +146,7 @@ def coast(self, **kwargs):
         a = All boundaries (1-3)
     water : str
         Select filling or clipping of "wet" areas.
-    shorelines : int or str or list
+    shorelines : int, str, or list
         [*level*\ /]\ *pen*.
         Draw shorelines [Default is no shorelines]. Append pen attributes
         [Default is ``"0.25p,black,solid"``] which

pygmt/src/colorbar.py

@@ -96,13 +96,13 @@ def colorbar(self, **kwargs):
     scale : float
         Multiply all z-values in the CPT by the provided scale. By default,
         the CPT is used as is.
-    shading : str or list or bool
+    shading : str, list, or bool
         Add illumination effects. Passing a single numerical value sets the
         range of intensities from -value to +value. If not specified, 1 is
         used. Alternatively, set ``shading=[low, high]`` to specify an
         asymmetric intensity range from *low* to *high*. [Default is no
         illumination].
-    equalsize : int or float or str
+    equalsize : float or str
         [**i**]\ [*gap*].
         Equal-sized color rectangles. By default, the rectangles are scaled
         according to the z-range in the CPT (see also ``zfile``). If *gap* is

pygmt/src/contour.py

@@ -46,7 +46,7 @@ def contour(self, data=None, x=None, y=None, z=None, **kwargs):
 
     Parameters
     ----------
-    data : str or {table-like}
+    data : str, {table-like}
         Pass in (x, y, z) or (longitude, latitude, elevation) values by
         providing a file name to an ASCII data table, a 2-D
         {table-classes}.

pygmt/src/grd2cpt.py

@@ -110,7 +110,7 @@ def grd2cpt(grid, **kwargs):
         *start*, where we automatically build monotonically increasing
         labels from *start* (a single letter or an integer). Additionally
         append **-** to build ranges *start*-*start+1* as labels instead.
-    nlevels : bool or int or str
+    nlevels : bool, int, or str
         Set to ``True`` to create a linear color table by using the grid
         z-range as the new limits in the CPT. Alternatively, set *nlevels*
         to resample the color table into *nlevels* equidistant slices.

pygmt/src/grdclip.py

@@ -56,16 +56,16 @@ def grdclip(grid, **kwargs):
         The name of the output netCDF file with extension .nc to store the grid
         in.
     {region}
-    above : str or list or tuple
+    above : str or list
         [*high*, *above*].
         Set all data[i] > *high* to *above*.
-    below : str or list or tuple
+    below : str or list
         [*low*, *below*].
         Set all data[i] < *low* to *below*.
-    between : str or list or tuple
+    between : str or list
         [*low*, *high*, *between*].
         Set all data[i] >= *low* and <= *high* to *between*.
-    new : str or list or tuple
+    new : str or list
         [*old*, *new*].
         Set all data[i] == *old* to *new*. This is mostly useful when
         your data are known to be integer values.

pygmt/src/grdcontour.py

@@ -53,7 +53,7 @@ def grdcontour(self, grid, **kwargs):
           angle (col 3).
         - A fixed contour interval *cont_int* or a single contour with
           +\ *cont_int*.
-    annotation : str,  int, or list
+    annotation : str, int, or list
         Specify or disable annotated contour levels, modifies annotated
         contours specified in ``interval``.
 

pygmt/src/grdcut.py

@@ -53,7 +53,7 @@ def grdcut(grid, **kwargs):
         in.
     {projection}
     {region}
-    extend : bool or int or float
+    extend : bool or float
         Allow grid to be extended if new ``region`` exceeds existing
         boundaries. Give a value to initialize nodes outside current region.
     circ_subregion : str