Merge branch 'main' into alias-system

Author: seisman

examples/gallery/histograms/blockm.py

@@ -18,7 +18,7 @@
 
 # Set the region for the plot
 region = [130, 152.5, 32.5, 52.5]
-# Define spacing in x- and y-direction (150x150 arc-minute blocks)
+# Define spacing in x- and y-directions (150x150 arc-minute blocks)
 spacing = "150m"
 
 fig = pygmt.Figure()

examples/gallery/images/grdlandmask.py

@@ -17,7 +17,7 @@
 # Assign a value of 0 for all water masses and a value of 1 for all land
 # masses.
 # Use shoreline data with (l)ow resolution and set the grid spacing to
-# 5 arc-minutes in x- and y-direction.
+# 5 arc-minutes in x- and y-directions.
 grid = pygmt.grdlandmask(region=region, spacing="5m", maskvalues=[0, 1], resolution="l")
 
 # Plot clipped grid

examples/tutorials/advanced/3d_perspective_image.py

@@ -27,8 +27,7 @@
     # Sets the view azimuth as 130 degrees, and the view elevation as 30
     # degrees
     perspective=[130, 30],
-    # Sets the x- and y-axis labels, and annotates the west, south, and east
-    # axes
+    # Sets the x- and y-axis labels, and annotates the west, south, and east axes
     frame=["xa", "ya", "WSnE"],
     # Sets a Mercator projection on a 15-centimeter figure
     projection="M15c",

examples/tutorials/advanced/cartesian_histograms.py

@@ -79,7 +79,7 @@
     fill="red3",
     pen="1p,darkgray,solid",
     histtype=0,
-    # Use horizontal bars. Note that the x- and y-axis are flipped, with the x-axis
+    # Use horizontal bars. Note that the x- and y-axes are flipped, with the x-axis
     # plotted vertically and the y-axis plotted horizontally.
     horizontal=True,
 )

examples/tutorials/advanced/insets.py

@@ -57,7 +57,7 @@
 # %%
 # When using **j** to set the anchor of the inset, the default location is in
 # contact with the nearby axis or axes. The offset of the inset can be set with
-# **+o**, followed by the offsets along the x- and y-axis. If only one offset
+# **+o**, followed by the offsets along the x- and y-axes. If only one offset
 # is passed, it is applied to both axes. Each offset can have its own unit. In
 # the example below, the inset is shifted 0.5 centimeters on the x-axis and
 # 0.2 centimeters on the y-axis.

examples/tutorials/basics/coastlines.py

@@ -27,9 +27,9 @@
 # 3. island-in-lake shore
 # 4. lake-in-island-in-lake shore
 #
-# You can specify which level you want to plot by passing the level number and
-# a GMT pen configuration. For example, to plot just the coastlines with 0.5p
-# thickness and black lines:
+# You can specify which level you want to plot by passing the level number and a GMT
+# pen configuration. For example, to plot just the coastlines with 0.5p thickness and
+# black lines:
 
 fig = pygmt.Figure()
 fig.basemap(region="g", projection="W15c", frame=True)
@@ -50,18 +50,14 @@
 # Resolutions
 # -----------
 #
-# The coastline database comes with 5 resolutions. The resolution drops by 80%
-# between levels:
-#
-# 1. ``"c"``: crude
-# 2. ``"l"``: low (default)
-# 3. ``"i"``: intermediate
-# 4. ``"h"``: high
-# 5. ``"f"``: full
+# The coastline database comes with 5 resolutions: ``"full"``, ``"high"``,
+# ``"intermediate"``, ``"low"``, and ``"crude"``. The resolution drops by 80% between
+# levels. The ``resolution`` parameter defaults to ``"auto"`` to automatically select
+# the best resolution given the chosen map scale.
 
 oahu = [-158.3, -157.6, 21.2, 21.8]
 fig = pygmt.Figure()
-for res in ["c", "l", "i", "h", "f"]:
+for res in ["crude", "low", "intermediate", "high", "full"]:
     fig.coast(resolution=res, shorelines="1p", region=oahu, projection="M5c")
     fig.shift_origin(xshift="5c")
 fig.show()
@@ -71,9 +67,9 @@
 # Land and water
 # --------------
 #
-# Use the ``land`` and ``water`` parameters to specify a fill color for land
-# and water bodies. The colors can be given by name or hex codes (like the ones
-# used in HTML and CSS):
+# Use the ``land`` and ``water`` parameters to specify a fill color for land and water
+# bodies. The colors can be given by name or hex codes (like the ones used in HTML and
+# CSS):
 
 fig = pygmt.Figure()
 fig.basemap(region="g", projection="W15c", frame=True)

pygmt/helpers/__init__.py

@@ -23,5 +23,6 @@
     is_nonstr_iter,
     launch_external_viewer,
     non_ascii_to_octal,
+    sequence_join,
 )
 from pygmt.helpers.validators import validate_output_table_type

pygmt/helpers/utils.py

@@ -711,3 +711,120 @@ def args_in_kwargs(args: Sequence[str], kwargs: dict[str, Any]) -> bool:
     return any(
         kwargs.get(arg) is not None and kwargs.get(arg) is not False for arg in args
     )
+
+
+def sequence_join(
+    value: Any,
+    separator: str = "/",
+    size: int | Sequence[int] | None = None,
+    ndim: int = 1,
+    name: str | None = None,
+) -> str | list[str] | None | Any:
+    """
+    Join a sequence of values into a string separated by a separator.
+
+    A 1-D sequence will be joined into a single string. A 2-D sequence will be joined
+    into a list of strings. Non-sequence values will be returned as is.
+
+    Parameters
+    ----------
+    value
+        The 1-D or 2-D sequence of values to join.
+    separator
+        The separator to join the values.
+    size
+        Expected size of the 1-D sequence. It can be either an integer or a sequence of
+        integers. If an integer, it is the expected size of the 1-D sequence. If it is a
+        sequence, it is the allowed sizes of the 1-D sequence.
+    ndim
+        The expected maximum number of dimensions of the sequence.
+    name
+        The name of the parameter to be used in the error message.
+
+    Returns
+    -------
+    joined_value
+        The joined string or list of strings.
+
+    Examples
+    --------
+    >>> sequence_join("1/2/3/4")
+    '1/2/3/4'
+    >>> sequence_join(None)
+    >>> sequence_join(True)
+    True
+    >>> sequence_join(False)
+    False
+
+    >>> sequence_join([])
+    Traceback (most recent call last):
+        ...
+    pygmt.exceptions.GMTInvalidInput: Expected a sequence but got an empty sequence.
+
+    >>> sequence_join([1, 2, 3, 4])
+    '1/2/3/4'
+    >>> sequence_join([1, 2, 3, 4], separator=",")
+    '1,2,3,4'
+    >>> sequence_join([1, 2, 3, 4], separator="/", size=4)
+    '1/2/3/4'
+    >>> sequence_join([1, 2, 3, 4], separator="/", size=[2, 4])
+    '1/2/3/4'
+    >>> sequence_join([1, 2, 3, 4], separator="/", size=[2, 4], ndim=2)
+    '1/2/3/4'
+    >>> sequence_join([1, 2, 3, 4], separator="/", size=2)
+    Traceback (most recent call last):
+        ...
+    pygmt.exceptions.GMTInvalidInput: Expected a sequence of 2 values, but got 4 values.
+    >>> sequence_join([1, 2, 3, 4, 5], separator="/", size=[2, 4], name="parname")
+    Traceback (most recent call last):
+        ...
+    pygmt.exceptions.GMTInvalidInput: Parameter 'parname': Expected ...
+
+    >>> sequence_join([[1, 2], [3, 4]], separator="/")
+    Traceback (most recent call last):
+        ...
+    pygmt.exceptions.GMTInvalidInput: Expected a 1-D ..., but a 2-D sequence is given.
+    >>> sequence_join([[1, 2], [3, 4]], separator="/", ndim=2)
+    ['1/2', '3/4']
+    >>> sequence_join([[1, 2], [3, 4]], separator="/", size=2, ndim=2)
+    ['1/2', '3/4']
+    >>> sequence_join([[1, 2], [3, 4]], separator="/", size=4, ndim=2)
+    Traceback (most recent call last):
+        ...
+    pygmt.exceptions.GMTInvalidInput: Expected a sequence of 4 values.
+    >>> sequence_join([[1, 2], [3, 4]], separator="/", size=[2, 4], ndim=2)
+    ['1/2', '3/4']
+    """
+    # Return the original value if it is not a sequence (e.g., None, bool, or str).
+    if not is_nonstr_iter(value):
+        return value
+    # Now it must be a sequence.
+
+    # Change size to a list to simplify the checks.
+    size = [size] if isinstance(size, int) else size
+    errmsg = {
+        "name": f"Parameter '{name}': " if name else "",
+        "sizes": ", ".join(str(s) for s in size) if size is not None else "",
+    }
+
+    if len(value) == 0:
+        msg = f"{errmsg['name']}Expected a sequence but got an empty sequence."
+        raise GMTInvalidInput(msg)
+
+    if not is_nonstr_iter(value[0]):  # 1-D sequence.
+        if size is not None and len(value) not in size:
+            msg = (
+                f"{errmsg['name']}Expected a sequence of {errmsg['sizes']} values, "
+                f"but got {len(value)} values."
+            )
+            raise GMTInvalidInput(msg)
+        return separator.join(str(v) for v in value)
+
+    # Now it must be a 2-D sequence.
+    if ndim == 1:
+        msg = f"{errmsg['name']}Expected a 1-D sequence, but a 2-D sequence is given."
+        raise GMTInvalidInput(msg)
+    if size is not None and any(len(i) not in size for i in value):
+        msg = f"{errmsg['name']}Expected a sequence of {errmsg['sizes']} values."
+        raise GMTInvalidInput(msg)
+    return [separator.join(str(j) for j in sub) for sub in value]

pygmt/src/_common.py

@@ -251,3 +251,56 @@ def from_params(
             f"{', '.join(params)}."
         )
         raise GMTInvalidInput(msg)
+
+
+def _parse_coastline_resolution(
+    resolution: Literal["auto", "full", "high", "intermediate", "low", "crude", None],
+) -> Literal["a", "f", "h", "i", "l", "c", None]:
+    """
+    Parse the 'resolution' parameter for coastline-related functions.
+
+    Parameters
+    ----------
+    resolution
+        The resolution of the coastline dataset to use. The available resolutions from
+        highest to lowest are: ``"full"``, ``"high"``, ``"intermediate"``, ``"low"``,
+        and ``"crude"``, which drops by 80% between levels. Alternatively, choose
+        ``"auto"`` to automatically select the most suitable resolution given the chosen
+        map scale or region. ``None`` means using the default resolution.
+
+    Returns
+    -------
+    The single-letter resolution code or ``None``.
+
+    Raises
+    ------
+    GMTInvalidInput
+        If the resolution is invalid.
+
+    Examples
+    --------
+    >>> _parse_coastline_resolution("full")
+    'f'
+    >>> _parse_coastline_resolution("f")
+    'f'
+    >>> _parse_coastline_resolution(None)
+    >>> _parse_coastline_resolution("invalid")
+    Traceback (most recent call last):
+    ...
+    pygmt.exceptions.GMTInvalidInput: Invalid resolution: 'invalid'. Valid values ...
+    """
+    if resolution is None:
+        return None
+
+    _valid_res = {"auto", "full", "high", "intermediate", "low", "crude"}
+
+    if resolution in _valid_res:  # Long-form arguments.
+        return resolution[0]  # type: ignore[return-value]
+
+    if resolution in {_res[0] for _res in _valid_res}:  # Short-form arguments.
+        return resolution  # type: ignore[return-value]
+
+    msg = (
+        f"Invalid resolution: '{resolution}'. Valid values are {', '.join(_valid_res)}."
+    )
+    raise GMTInvalidInput(msg)

pygmt/src/basemap.py

@@ -60,12 +60,12 @@ def basemap(self, frame=None, **kwargs):
         **+p**\ *pen*. Add **+g**\ *fill* to fill the scale panel [Default is
         no fill]. Append **+c**\ *clearance* where *clearance* is either gap,
         xgap/ygap, or lgap/rgap/bgap/tgap where these items are uniform,
-        separate in x- and y-direction, or individual side spacings between
-        scale and border. Append **+i** to draw a secondary, inner border as
-        well. We use a uniform gap between borders of 2p and the
+        separate x and y, or individual side spacings between scale and
+        border. Append **+i** to draw a secondary, inner border as well.
+        We use a uniform gap between borders of 2 points and the
         :gmt-term:`MAP_DEFAULTS_PEN` unless other values are specified. Append
-        **+r** to draw rounded rectangular borders instead, with a 6p corner
-        radius. You can override this radius by appending another value.
+        **+r** to draw rounded rectangular borders instead, with a 6-points
+        corner radius. You can override this radius by appending another value.
         Finally, append **+s** to draw an offset background shaded region.
         Here, *dx/dy* indicates the shift relative to the foreground frame
         [Default is ``"4p/-4p"``] and shade sets the fill style to use for