Improve the alias system to support single-letter option flags

Author: seisman

pygmt/alias.py

@@ -3,11 +3,12 @@
 """
 
 import dataclasses
+import warnings
 from collections import defaultdict
 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
 
 
@@ -247,7 +248,6 @@ def __init__(self, **kwargs):
         """
         # Keyword dictionary with an empty string as default value.
         self.kwdict = defaultdict(str)
-
         for option, aliases in kwargs.items():
             if not is_nonstr_iter(aliases):  # A single alias.
                 self.kwdict[option] = aliases._value
@@ -263,3 +263,38 @@ def __init__(self, **kwargs):
                         # A repeatable option should have only one alias, so break.
                         self.kwdict[option] = alias._value
                         break
+
+        # Dictionary mapping option flags to their alias objects.
+        self._aliasdict = {}
+        for option, aliases in kwargs.items():
+            if not is_nonstr_iter(aliases):
+                self._aliasdict[option] = [aliases.name]
+            else:
+                self._aliasdict[option] = [alias.name for alias in aliases]
+
+    def merge(self, kwargs):
+        """
+        Merge additional keyword arguments into the existing keyword dictionary.
+
+        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 in kwargs.
+        for short_param, value in kwargs.items():
+            if self._aliasdict.get(short_param):
+                long_form = ", ".join(repr(r) for r in self._aliasdict.get(short_param))
+
+            # Long-form exists and is already given.
+            if short_param in self.kwdict and self.kwdict[short_param] is not None:
+                msg = f"Parameters in short-form {short_param!r} and long-form {long_form} can't coexist."
+                raise GMTInvalidInput(msg)
+
+            # Long-form exists, but not given.
+            if short_param in self._aliasdict:
+                msg = (
+                    f"Short-form parameter {short_param!r} is not recommended. "
+                    f"Use long-form parameter {long_form} instead."
+                )
+                warnings.warn(msg, category=SyntaxWarning, stacklevel=2)
+            self.kwdict[short_param] = value
+        return self

pygmt/src/basemap.py

@@ -2,17 +2,15 @@
 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",
     L="map_scale",
     F="box",
     Td="rose",
@@ -23,8 +21,8 @@
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
-def basemap(self, **kwargs):
+@kwargs_to_strings(c="sequence_comma", p="sequence")
+def basemap(self, region=None, projection=None, frame=None, **kwargs):
     r"""
     Plot base maps and frames.
 
@@ -83,5 +81,12 @@ def basemap(self, **kwargs):
     {transparency}
     """
     self._activate_figure()
+
+    alias = AliasSystem(
+        R=Alias(region, name="region", separator="/", size=[4, 6]),
+        J=Alias(projection, name="projection"),
+        B=Alias(frame, name="frame"),
+    ).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(alias.kwdict))

pygmt/tests/test_alias_system.py

@@ -0,0 +1,71 @@
+"""
+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, **kwargs):
+    """
+    A simple function to test the alias system.
+    """
+    alias = 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")],
+    ).merge(kwargs)
+    return build_arg_list(alias.kwdict)
+
+
+def test_alias_system_one_alias():
+    """
+    Test that the alias system works with a single alias.
+    """
+    assert func(projection="X10c") == ["-JX10c"]
+    assert func(projection="H10c", region=[0, 10, 0, 20]) == ["-JH10c", "-R0/10/0/20"]
+    assert func(frame=["WSen", "xaf", "yaf"]) == ["-BWSen", "-Bxaf", "-Byaf"]
+
+
+def test_alias_system_one_alias_short_form():
+    """
+    Test that the alias system works when short-form parameters coexist.
+    """
+    # 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="can't coexist"):
+        func(projection="X10c", J="H10c")
+
+
+def test_alias_system_multiple_aliases():
+    """
+    Test that the alias system works with multiple aliases.
+    """
+    assert func(label="abcd", text="efg") == ["-Uabcd+tefg"]
+
+
+def test_alias_system_multiple_aliases_short_form():
+    """
+    Test that the alias system works with multiple aliases when short-form parameters
+    are used.
+    """
+    with pytest.warns(
+        SyntaxWarning,
+        match="Short-form parameter 'U' is not recommended. Use long-form parameter 'label', 'text' instead.",
+    ):
+        assert func(U="abcd+tefg") == ["-Uabcd+tefg"]
+
+    with pytest.raises(GMTInvalidInput, match="can't coexist"):
+        func(label="abcd", U="efg")
+
+    with pytest.raises(GMTInvalidInput, match="can't coexist"):
+        func(text="efg", U="efg")