New alias system

Author: seisman

pygmt/alias.py

@@ -0,0 +1,40 @@
+import inspect
+from collections import defaultdict
+from typing import NamedTuple
+
+from pygmt.helpers import is_nonstr_iter
+
+
+class Alias(NamedTuple):
+    name: str
+    flag: str
+    modifier: str
+    separator: str
+
+
+def sequence_to_str(seq, separator):
+    return separator.join(str(item) for item in seq)
+
+
+def convert_aliases():
+    """
+    Convert PyGMT parameters to GMT options.
+
+    The caller function must have the special variable ``_aliases`` defined.
+    """
+    # Get the local namespace of the caller function
+    p_locals = inspect.currentframe().f_back.f_locals
+    params = p_locals.pop("kwargs", {}) | p_locals
+
+    # Define a dict to store GMT option flags and arguments
+    options = defaultdict(lambda: "")
+    for alias in p_locals.get("_aliases"):
+        value = params.get(alias.name)
+        if value in (None, False):  # None or False are skipped
+            continue
+        if value is True:  # Convert True to an empty string
+            value = ""
+        if alias.separator is not None and is_nonstr_iter(value):
+            value = sequence_to_str(value, alias.separator)
+        options[alias.flag] += f"{alias.modifier}{value}"
+    return dict(options)

pygmt/src/info.py

@@ -2,29 +2,28 @@
 info - Get information about data tables.
 """
 import numpy as np
+from pygmt.alias import Alias, convert_aliases
 from pygmt.clib import Session
 from pygmt.helpers import (
     GMTTempFile,
     build_arg_string,
     fmt_docstring,
-    kwargs_to_strings,
-    use_alias,
 )
 
 
 @fmt_docstring
-@use_alias(
-    C="per_column",
-    I="spacing",
-    T="nearest_multiple",
-    V="verbose",
-    a="aspatial",
-    f="coltypes",
-    i="incols",
-    r="registration",
-)
-@kwargs_to_strings(I="sequence", i="sequence_comma")
-def info(data, **kwargs):
+def info(
+    data,
+    per_column=None,
+    spacing=None,
+    nearest_multiple=None,
+    verbose=None,
+    aspatial=None,
+    coltypes=None,
+    incols=None,
+    registration=None,
+    **kwargs,
+):
     r"""
     Get information about data tables.
 
@@ -43,8 +42,6 @@ def info(data, **kwargs):
 
     Full option list at :gmt-docs:`gmtinfo.html`
 
-    {aliases}
-
     Parameters
     ----------
     data : str, {table-like}
@@ -79,17 +76,30 @@ def info(data, **kwargs):
         - :class:`numpy.ndarray` if either of the above parameters are used.
         - str if none of the above parameters are used.
     """
+    _aliases = [
+        Alias("per_column", "C", "", ""),
+        Alias("spacing", "I", "", "/"),
+        Alias("nearest_multiple", "T", "", ""),
+        Alias("verbose", "V", "", ""),
+        Alias("aspatial", "a", "", ""),
+        Alias("coltypes", "f", "", ""),
+        Alias("incols", "i", "", ","),
+        Alias("registration", "r", "", ""),
+    ]
+
+    options = convert_aliases()
+
     with Session() as lib:
         file_context = lib.virtualfile_from_data(check_kind="vector", data=data)
         with GMTTempFile() as tmpfile:
             with file_context as fname:
                 lib.call_module(
                     module="info",
-                    args=build_arg_string(kwargs, infile=fname, outfile=tmpfile.name),
+                    args=build_arg_string(options, infile=fname, outfile=tmpfile.name),
                 )
             result = tmpfile.read()
 
-        if any(kwargs.get(arg) is not None for arg in ["C", "I", "T"]):
+        if any(arg is not None for arg in (per_column, spacing, nearest_multiple)):
             # Converts certain output types into a numpy array
             # instead of a raw string that is less useful.
             if result.startswith(("-R", "-T")):  # e.g. -R0/1/2/3 or -T0/9/1

pygmt/src/timestamp.py

@@ -7,8 +7,9 @@
 from typing import TYPE_CHECKING
 
 from packaging.version import Version
+from pygmt.alias import Alias, convert_aliases
 from pygmt.clib import Session, __gmt_version__
-from pygmt.helpers import build_arg_string, kwargs_to_strings
+from pygmt.helpers import build_arg_string, is_nonstr_iter
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -17,7 +18,6 @@
 __doctest_skip__ = ["timestamp"]
 
 
-@kwargs_to_strings(offset="sequence")
 def timestamp(
     self,
     text: str | None = None,
@@ -82,17 +82,22 @@ def timestamp(
     """
     self._preprocess()
 
-    # Build the options passed to the "plot" module
-    kwdict: dict = {"T": True, "U": ""}
-    if label is not None:
-        kwdict["U"] += f"{label}"
-    kwdict["U"] += f"+j{justification}"
-
-    if Version(__gmt_version__) <= Version("6.4.0") and "/" not in str(offset):
-        # Giving a single offset doesn't work in GMT <= 6.4.0.
-        # See https://github.com/GenericMappingTools/gmt/issues/7107.
-        offset = f"{offset}/{offset}"
-    kwdict["U"] += f"+o{offset}"
+    # Aliases from PyGMT parameters to GMT options
+    _aliases = [
+        Alias("label", "U", "", ""),
+        Alias("justification", "U", "+j", ""),
+        Alias("offset", "U", "+o", "/"),
+        Alias("text", "U", "+t", ""),
+    ]
+
+    # Giving a single offset doesn't work in GMT <= 6.4.0.
+    # See https://github.com/GenericMappingTools/gmt/issues/7107.
+    if (
+        Version(__gmt_version__) <= Version("6.4.0")
+        and not is_nonstr_iter(offset)
+        and "/" not in str(offset)
+    ):
+        offset = (offset, offset)
 
     # The +t modifier was added in GMT 6.5.0.
     # See https://github.com/GenericMappingTools/gmt/pull/7127.
@@ -106,13 +111,16 @@ def timestamp(
         if Version(__gmt_version__) <= Version("6.4.0"):
             # workaround for GMT<=6.4.0 by overriding the 'timefmt' parameter
             timefmt = text[:64]
-        else:
-            kwdict["U"] += f"+t{text}"
+            text = None  # reset 'text' to None
+
+    # Build the options passed to the "plot" module
+    options = convert_aliases()
+    options["T"] = True
 
     with Session() as lib:
         lib.call_module(
             module="plot",
             args=build_arg_string(
-                kwdict, confdict={"FONT_LOGO": font, "FORMAT_TIME_STAMP": timefmt}
+                options, confdict={"FONT_LOGO": font, "FORMAT_TIME_STAMP": timefmt}
             ),
         )