Merge branch 'main' into AliasSystem/params/base

Author: seisman

.github/workflows/ci_tests.yaml

@@ -151,7 +151,7 @@ jobs:
           GH_TOKEN: ${{ github.token }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@7edac99f961f18b581bbd960d59d049f04c0002f # v6.4.1
+        uses: astral-sh/setup-uv@e92bafb6253dcd438e0484186d7669ea7a8ca1cc # v6.4.3
         with:
           activate-environment: true
           python-version: ${{ matrix.python-version }}

pygmt/alias.py

@@ -15,7 +15,7 @@ def _to_string(
     value: Any,
     prefix: str = "",  # Default to an empty string to simplify the code logic.
     mapping: Mapping | None = None,
-    separator: Literal["/", ","] | None = None,
+    sep: Literal["/", ","] | None = None,
     size: int | Sequence[int] | None = None,
     ndim: int = 1,
     name: str | None = None,
@@ -41,8 +41,8 @@ def _to_string(
     string.
 
     To avoid extra overhead, this function does not validate parameter combinations. For
-    example, if ``value`` is a sequence but ``separator`` is not specified, the function
-    will return a sequence of strings. In this case, ``prefix`` has no effect, but the
+    example, if ``value`` is a sequence but ``sep`` is not specified, the function will
+    return a sequence of strings. In this case, ``prefix`` has no effect, but the
     function does not check for such inconsistencies. The maintainer should ensure that
     the parameter combinations are valid.
 
@@ -54,7 +54,7 @@ def _to_string(
         The string to add as a prefix to the returned value.
     mapping
         A mapping dictionary to map PyGMT's long-form arguments to GMT's short-form.
-    separator
+    sep
         The separator to use if the value is a sequence.
     size
         Expected size of the 1-D sequence. It can be either an integer or a sequence of
@@ -97,15 +97,18 @@ def _to_string(
     ...
     pygmt...GMTValueError: Invalid value: 'invalid'. Expected one of: 'mean', ...
 
-    >>> _to_string((12, 34), separator="/")
+    >>> _to_string((12, 34), sep="/")
     '12/34'
-    >>> _to_string(("12p", "34p"), separator=",")
+    >>> _to_string(("12p", "34p"), sep=",")
     '12p,34p'
-    >>> _to_string(("12p", "34p"), prefix="+o", separator="/")
+    >>> _to_string(("12p", "34p"), prefix="+o", sep="/")
     '+o12p/34p'
 
     >>> _to_string(["xaf", "yaf", "WSen"])
     ['xaf', 'yaf', 'WSen']
+
+    >>> _to_string([[1, 2], [3, 4]], sep="/", ndim=2)
+    ['1/2', '3/4']
     """
     # None and False are converted to None.
     if value is None or value is False:
@@ -127,12 +130,12 @@ def _to_string(
 
     # Return the sequence if separator is not specified for options like '-B'.
     # True in a sequence will be converted to an empty string.
-    if separator is None:
+    if sep is None:
         return [str(item) if item is not True else "" for item in value]
     # Join the sequence of values with the separator.
     # "prefix" and "mapping" are ignored. We can enable them when needed.
-    _value = sequence_join(value, separator=separator, size=size, ndim=ndim, name=name)
-    return f"{prefix}{_value}"
+    _value = sequence_join(value, sep=sep, size=size, ndim=ndim, name=name)
+    return _value if is_nonstr_iter(_value) else f"{prefix}{_value}"
 
 
 class Alias:
@@ -149,7 +152,7 @@ class Alias:
         The string to add as a prefix to the returned value.
     mapping
         A mapping dictionary to map PyGMT's long-form arguments to GMT's short-form.
-    separator
+    sep
         The separator to use if the value is a sequence.
     size
         Expected size of the 1-D sequence. It can be either an integer or a sequence
@@ -160,7 +163,7 @@ class Alias:
 
     Examples
     --------
-    >>> par = Alias((3.0, 3.0), prefix="+o", separator="/")
+    >>> par = Alias((3.0, 3.0), prefix="+o", sep="/")
     >>> par._value
     '+o3.0/3.0'
 
@@ -179,7 +182,7 @@ def __init__(
         name: str | None = None,
         prefix: str = "",
         mapping: Mapping | None = None,
-        separator: Literal["/", ","] | None = None,
+        sep: Literal["/", ","] | None = None,
         size: int | Sequence[int] | None = None,
         ndim: int = 1,
     ):
@@ -190,7 +193,7 @@ def __init__(
             name=name,
             prefix=prefix,
             mapping=mapping,
-            separator=separator,
+            sep=sep,
             size=size,
             ndim=ndim,
         )
@@ -219,11 +222,11 @@ class AliasSystem(UserDict):
     ...     aliasdict = AliasSystem(
     ...         A=[
     ...             Alias(par1, name="par1"),
-    ...             Alias(par2, name="par2", prefix="+o", separator="/"),
+    ...             Alias(par2, name="par2", prefix="+o", sep="/"),
     ...         ],
     ...         B=Alias(frame, name="frame"),
     ...         D=Alias(repeat, name="repeat"),
-    ...         c=Alias(panel, name="panel", separator=","),
+    ...         c=Alias(panel, name="panel", sep=","),
     ...     ).merge(kwargs)
     ...     return build_arg_list(aliasdict)
     >>> func(

pygmt/datasets/load_remote_dataset.py

@@ -3,7 +3,7 @@
 """
 
 import contextlib
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from typing import Any, Literal, NamedTuple
 
 import xarray as xr
@@ -58,8 +58,8 @@ class GMTRemoteDataset(NamedTuple):
     description: str
     kind: Literal["grid", "image"]
     units: str | None
-    resolutions: dict[str, Resolution]
-    extra_attributes: dict[str, Any]
+    resolutions: Mapping[str, Resolution]
+    extra_attributes: Mapping[str, Any]
     crs: str | None = None
 
 

pygmt/datatypes/header.py

@@ -3,6 +3,7 @@
 """
 
 import ctypes as ctp
+from collections.abc import Mapping
 from typing import Any, ClassVar
 
 import numpy as np
@@ -199,7 +200,7 @@ def name(self) -> str:
         return "z"
 
     @property
-    def data_attrs(self) -> dict[str, Any]:
+    def data_attrs(self) -> Mapping[str, Any]:
         """
         Attributes for the data variable from the grid header.
         """

pygmt/helpers/utils.py

@@ -9,6 +9,7 @@
 import subprocess
 import sys
 import time
+import warnings
 import webbrowser
 from collections.abc import Iterable, Mapping, Sequence
 from itertools import islice
@@ -481,7 +482,7 @@ def non_ascii_to_octal(argstr: str, encoding: Encoding = "ISOLatin1+") -> str:
 
 
 def build_arg_list(  # noqa: PLR0912
-    kwdict: dict[str, Any],
+    kwdict: Mapping[str, Any],
     confdict: Mapping[str, Any] | None = None,
     infile: PathLike | Sequence[PathLike] | None = None,
     outfile: PathLike | None = None,
@@ -724,9 +725,11 @@ def args_in_kwargs(args: Sequence[str], kwargs: dict[str, Any]) -> bool:
     )
 
 
+# TODO(PyGMT>=0.19.0): Remove the deprecate_parameter decorator.
 def sequence_join(
     value: Any,
-    separator: str = "/",
+    sep: str = "/",
+    separator: str | None = None,
     size: int | Sequence[int] | None = None,
     ndim: int = 1,
     name: str | None = None,
@@ -741,8 +744,14 @@ def sequence_join(
     ----------
     value
         The 1-D or 2-D sequence of values to join.
+    sep
+        The separator to join the values.
     separator
         The separator to join the values.
+
+        .. versionchanged:: v0.17.0
+
+            Deprecated and will be removed in v0.19.0. Use ``sep`` instead.
     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
@@ -774,43 +783,53 @@ def sequence_join(
 
     >>> sequence_join([1, 2, 3, 4])
     '1/2/3/4'
-    >>> sequence_join([1, 2, 3, 4], separator=",")
+    >>> sequence_join([1, 2, 3, 4], sep=",")
     '1,2,3,4'
-    >>> sequence_join([1, 2, 3, 4], separator="/", size=4)
+    >>> sequence_join([1, 2, 3, 4], sep="/", size=4)
     '1/2/3/4'
-    >>> sequence_join([1, 2, 3, 4], separator="/", size=[2, 4])
+    >>> sequence_join([1, 2, 3, 4], sep="/", size=[2, 4])
     '1/2/3/4'
-    >>> sequence_join([1, 2, 3, 4], separator="/", size=[2, 4], ndim=2)
+    >>> sequence_join([1, 2, 3, 4], sep="/", size=[2, 4], ndim=2)
     '1/2/3/4'
-    >>> sequence_join([1, 2, 3, 4], separator="/", size=2)
+    >>> sequence_join([1, 2, 3, 4], sep="/", 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")
+    >>> sequence_join([1, 2, 3, 4, 5], sep="/", size=[2, 4], name="parname")
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Parameter 'parname': Expected ...
 
-    >>> sequence_join([[1, 2], [3, 4]], separator="/")
+    >>> sequence_join([[1, 2], [3, 4]], sep="/")
     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)
+    >>> sequence_join([[1, 2], [3, 4]], sep="/", ndim=2)
     ['1/2', '3/4']
-    >>> sequence_join([[1, 2], [3, 4]], separator="/", size=2, ndim=2)
+    >>> sequence_join([[1, 2], [3, 4]], sep="/", size=2, ndim=2)
     ['1/2', '3/4']
-    >>> sequence_join([[1, 2], [3, 4]], separator="/", size=4, ndim=2)
+    >>> sequence_join([[1, 2], [3, 4]], sep="/", 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)
+    >>> sequence_join([[1, 2], [3, 4]], sep="/", size=[2, 4], ndim=2)
     ['1/2', '3/4']
+    >>> sequence_join([1, 2, 3, 4], separator=",")
+    '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.
 
+    if separator is not None:
+        sep = separator  # Deprecated, use sep instead.
+        msg = (
+            "Parameter 'separator' has been deprecated since v0.17.0 and will be "
+            "removed in v0.19.0. Please use 'sep' instead."
+        )
+        warnings.warn(msg, category=FutureWarning, stacklevel=2)
+
     # Change size to a list to simplify the checks.
     size = [size] if isinstance(size, int) else size
     errmsg = {
@@ -829,7 +848,7 @@ def sequence_join(
                 f"but got {len(value)} values."
             )
             raise GMTInvalidInput(msg)
-        return separator.join(str(v) for v in value)
+        return sep.join(str(v) for v in value)
 
     # Now it must be a 2-D sequence.
     if ndim == 1:
@@ -838,4 +857,4 @@ def sequence_join(
     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]
+    return [sep.join(str(j) for j in sub) for sub in value]

pygmt/src/_common.py

@@ -244,55 +244,3 @@ def from_params(
             if set(param_list).issubset(set(params)):
                 return cls(convention, component=component)
         raise GMTValueError(params, description="focal mechanism parameters")
-
-
-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
-    ------
-    GMTValueError
-        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...GMTValueError: Invalid .... Expected ....
-    """
-    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]
-
-    raise GMTValueError(
-        resolution, choices=_valid_res, description="GSHHG coastline resolution"
-    )

pygmt/src/basemap.py

@@ -2,14 +2,14 @@
 basemap - Plot base maps and frames.
 """
 
+from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
 
 
 @fmt_docstring
 @use_alias(
     R="region",
-    J="projection",
     Jz="zscale",
     JZ="zsize",
     B="frame",
@@ -24,7 +24,7 @@
     t="transparency",
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
-def basemap(self, **kwargs):
+def basemap(self, projection=None, **kwargs):
     r"""
     Plot base maps and frames.
 
@@ -39,6 +39,7 @@ def basemap(self, **kwargs):
     Full GMT docs at :gmt-docs:`basemap.html`.
 
     {aliases}
+       - J=projection
 
     Parameters
     ----------
@@ -83,5 +84,8 @@ def basemap(self, **kwargs):
     {transparency}
     """
     self._activate_figure()
+    aliasdict = AliasSystem(
+        J=Alias(projection, name="projection"),
+    ).merge(kwargs)
     with Session() as lib:
-        lib.call_module(module="basemap", args=build_arg_list(kwargs))
+        lib.call_module(module="basemap", args=build_arg_list(aliasdict))