New Alias System: Add the AliasSystem class

pygmt/alias.py

@@ -2,10 +2,12 @@
 The PyGMT alias system to convert PyGMT's long-form arguments to GMT's short-form.
 """
 
+import warnings
+from collections import UserDict
 from collections.abc import Mapping, Sequence
 from typing import Any, Literal
 
-from pygmt.exceptions import GMTValueError
+from pygmt.exceptions import GMTInvalidInput, GMTValueError
 from pygmt.helpers.utils import is_nonstr_iter, sequence_join
 
 
@@ -192,3 +194,120 @@ def __init__(
             size=size,
             ndim=ndim,
         )
+
+
+class AliasSystem(UserDict):
+    """
+    Alias system for mapping PyGMT's long-form parameters to GMT's short-form options.
+
+    This class is initialized with keyword arguments, where each key is a GMT option
+    flag, and the corresponding value is an ``Alias`` object or a list of ``Alias``
+    objects.
+
+    This class inherits from ``UserDict``, which allows it to behave like a dictionary
+    and can be passed to the ``build_arg_list`` function. It also provides the ``merge``
+    method to update the alias dictionary with additional keyword arguments.
+
+    Examples
+    --------
+    >>> from pygmt.alias import Alias, AliasSystem
+    >>> from pygmt.helpers import build_arg_list
+    >>>
+    >>> def func(
+    ...     par0, par1=None, par2=None, frame=False, repeat=None, panel=None, **kwargs
+    ... ):
+    ...     aliasdict = AliasSystem(
+    ...         A=[
+    ...             Alias(par1, name="par1"),
+    ...             Alias(par2, name="par2", prefix="+o", separator="/"),
+    ...         ],
+    ...         B=Alias(frame, name="frame"),
+    ...         D=Alias(repeat, name="repeat"),
+    ...         c=Alias(panel, name="panel", separator=","),
+    ...     ).merge(kwargs)
+    ...     return build_arg_list(aliasdict)
+    >>> func(
+    ...     "infile",
+    ...     par1="mytext",
+    ...     par2=(12, 12),
+    ...     frame=True,
+    ...     repeat=[1, 2, 3],
+    ...     panel=(1, 2),
+    ...     J="X10c/10c",
+    ... )
+    ['-Amytext+o12/12', '-B', '-D1', '-D2', '-D3', '-JX10c/10c', '-c1,2']
+    """
+
+    def __init__(self, **kwargs):
+        """
+        Initialize the alias system as a dictionary with current parameter values.
+        """
+        # Store the aliases in a dictionary, to be used in the merge() method.
+        self.aliasdict = kwargs
+
+        # The value of each key in kwargs is an Alias object or a sequence of Alias
+        # objects. If it is a single Alias object, we will use its _value property. If
+        # it is a sequence of Alias objects, we will concatenate their _value properties
+        # into a single string.
+        #
+        # Note that alias._value is converted by the _to_string method and can only be
+        # None, string or sequence of strings.
+        # - None means the parameter is not specified.
+        # - Sequence of strings means this is a repeatable option, so it can only have
+        #   one long-form parameter.
+        kwdict = {}
+        for option, aliases in kwargs.items():
+            if isinstance(aliases, Sequence):  # A sequence of Alias objects.
+                values = [alias._value for alias in aliases if alias._value is not None]
+                if values:
+                    kwdict[option] = "".join(values)
+            elif aliases._value is not None:  # A single Alias object and not None.
+                kwdict[option] = aliases._value
+        super().__init__(kwdict)
+
+    def merge(self, kwargs: Mapping[str, Any]):
+        """
+        Update the dictionary with additional keyword arguments.
+
+        This method is necessary to allow users to use the single-letter parameters for
+        option flags that are not aliased.
+        """
+        # Loop over short-form parameters passed via kwargs.
+        for short_param, value in kwargs.items():
+            # Check if long-form parameters exist and given.
+            long_param_exists = short_param in self.aliasdict
+            long_param_given = short_param in self
+
+            # Update the dictionary with the short-form parameter anyway.
+            self[short_param] = value
+
+            # Long-form parameters do not exist.
+            if not long_param_exists:
+                continue
+
+            # Long-form parameters exist.
+            aliases = self.aliasdict.get(short_param)
+            if not isinstance(aliases, Sequence):  # Single Alias object.
+                _msg_long = f"Use long-form parameter {aliases.name!r} instead."
+            else:  # Sequence of Alias objects.
+                _params = [f"{v.name!r}" for v in aliases if not v.prefix]
+                _modifiers = [f"{v.name!r} ({v.prefix})" for v in aliases if v.prefix]
+                _msg_long = (
+                    f"Use long-form parameters {', '.join(_params)}, "
+                    f"with optional parameters {', '.join(_modifiers)} instead."
+                )
+
+            # Long-form parameters are already specified.
+            if long_param_given:
+                msg = (
+                    f"Short-form parameter {short_param!r} conflicts with long-form "
+                    f"parameters and is not recommended. {_msg_long}"
+                )
+                raise GMTInvalidInput(msg)
+
+            # Long-form parameters are not specified.
+            msg = (
+                f"Short-form parameter {short_param!r} is not recommended. {_msg_long}"
+            )
+            warnings.warn(msg, category=SyntaxWarning, stacklevel=2)
+        return self

pygmt/tests/test_alias_system.py

@@ -0,0 +1,97 @@
+"""
+Tests for the alias system.
+"""
+
+import pytest
+from pygmt.alias import Alias, AliasSystem
+from pygmt.exceptions import GMTInvalidInput
+from pygmt.helpers import build_arg_list
+
+
+def func(
+    projection=None,
+    region=None,
+    frame=None,
+    label=None,
+    text=None,
+    offset=None,
+    **kwargs,
+):
+    """
+    A simple function to test the alias system.
+    """
+    aliasdict = AliasSystem(
+        J=Alias(projection, name="projection"),
+        R=Alias(region, name="region", separator="/", size=[4, 6]),
+        B=Alias(frame, name="frame"),
+        U=[
+            Alias(label, name="label"),
+            Alias(text, name="text", prefix="+t"),
+            Alias(offset, name="offset", prefix="+o", separator="/"),
+        ],
+    ).merge(kwargs)
+    return build_arg_list(aliasdict)
+
+
+def test_alias_system_long_form():
+    """
+    Test that the alias system works with long-form parameters.
+    """
+    # One parameter
+    assert func(projection="X10c") == ["-JX10c"]
+    # Multiple parameters.
+    assert func(projection="H10c", region=[0, 10, 0, 20]) == ["-JH10c", "-R0/10/0/20"]
+    # Repeatable parameters.
+    assert func(frame=["WSen", "xaf", "yaf"]) == ["-BWSen", "-Bxaf", "-Byaf"]
+    # Multiple long-form parameters.
+    assert func(label="abcd", text="efg", offset=(12, 12)) == ["-Uabcd+tefg+o12/12"]
+    assert func(
+        projection="H10c",
+        region=[0, 10, 0, 20],
+        label="abcd",
+        text="efg",
+        offset=(12, 12),
+        frame=["WSen", "xaf", "yaf"],
+    ) == ["-BWSen", "-Bxaf", "-Byaf", "-JH10c", "-R0/10/0/20", "-Uabcd+tefg+o12/12"]
+
+
+def test_alias_system_one_alias_short_form():
+    """
+    Test that the alias system works when short-form parameters coexist.
+    """
+    # Long-form does not exist.
+    assert func(A="abc") == ["-Aabc"]
+
+    # Long-form exists but is not given, and short-form is given.
+    with pytest.warns(
+        SyntaxWarning,
+        match="Short-form parameter 'J' is not recommended. Use long-form parameter 'projection' instead.",
+    ):
+        assert func(J="X10c") == ["-JX10c"]
+
+    # Coexistence of long-form and short-form parameters.
+    with pytest.raises(
+        GMTInvalidInput,
+        match="Short-form parameter 'J' conflicts with long-form parameters and is not recommended. Use long-form parameter 'projection' instead.",
+    ):
+        func(projection="X10c", J="H10c")
+
+
+def test_alias_system_multiple_aliases_short_form():
+    """
+    Test that the alias system works with multiple aliases when short-form parameters
+    are used.
+    """
+    _msg_long = r"Use long-form parameters 'label', with optional parameters 'text' \(\+t\), 'offset' \(\+o\) instead."
+    # Long-form exists but is not given, and short-form is given.
+    msg = rf"Short-form parameter 'U' is not recommended. {_msg_long}"
+    with pytest.warns(SyntaxWarning, match=msg):
+        assert func(U="abcd+tefg") == ["-Uabcd+tefg"]
+
+    # Coexistence of long-form and short-form parameters.
+    msg = rf"Short-form parameter 'U' conflicts with long-form parameters and is not recommended. {_msg_long}"
+    with pytest.raises(GMTInvalidInput, match=msg):
+        func(label="abcd", U="efg")
+
+    with pytest.raises(GMTInvalidInput, match=msg):
+        func(text="efg", U="efg")