POC: Migrate the parameter 'verbose' to the new alias system and let it support descriptive arguments

doc/techref/common_parameters.md

@@ -22,13 +22,13 @@
 ``verbose``
     Select verbosity level, which modulates the messages written to stderr.
 
-    Choose among 7 levels of verbosity [Default is ``"w"``]:
+    Choose among 7 levels of verbosity [Default is ``"warning"``]:
 
-    - ``"q"``: Quiet, not even fatal error messages are produced
-    - ``"e"``: Error messages only
-    - ``"w"``: Warnings [Default]
-    - ``"t"``: Timings (report runtimes for time-intensive algorithms)
-    - ``"i"``: Informational messages (same as ``verbose=True``)
-    - ``"c"``: Compatibility warnings
-    - ``"d"``: Debugging messages
+    - ``"quiet"``: Quiet, not even fatal error messages are produced
+    - ``"error"``: Error messages only
+    - ``"warning"``: Warnings [Default]
+    - ``"timing"``: Timings (report runtimes for time-intensive algorithms)
+    - ``"information"``: Informational messages (same as ``verbose=True``)
+    - ``"compatibility"``: Compatibility warnings
+    - ``"debug"``: Debugging messages
 ```

pygmt/alias.py

@@ -217,7 +217,14 @@ class AliasSystem(UserDict):
     >>> from pygmt.helpers import build_arg_list
     >>>
     >>> def func(
-    ...     par0, par1=None, par2=None, frame=False, repeat=None, panel=None, **kwargs
+    ...     par0,
+    ...     par1=None,
+    ...     par2=None,
+    ...     frame=False,
+    ...     repeat=None,
+    ...     panel=None,
+    ...     verbose=None,
+    ...     **kwargs,
     ... ):
     ...     aliasdict = AliasSystem(
     ...         A=[
@@ -227,7 +234,8 @@ class AliasSystem(UserDict):
     ...         B=Alias(frame, name="frame"),
     ...         D=Alias(repeat, name="repeat"),
     ...         c=Alias(panel, name="panel", sep=","),
-    ...     ).merge(kwargs)
+    ...     ).add_common(V=verbose)
+    ...     aliasdict.merge(kwargs)
     ...     return build_arg_list(aliasdict)
     >>> func(
     ...     "infile",
@@ -236,9 +244,10 @@ class AliasSystem(UserDict):
     ...     frame=True,
     ...     repeat=[1, 2, 3],
     ...     panel=(1, 2),
+    ...     verbose="debug",
     ...     J="X10c/10c",
     ... )
-    ['-Amytext+o12/12', '-B', '-D1', '-D2', '-D3', '-JX10c/10c', '-c1,2']
+    ['-Amytext+o12/12', '-B', '-D1', '-D2', '-D3', '-JX10c/10c', '-Vd', '-c1,2']
     """
 
     def __init__(self, **kwargs):
@@ -268,6 +277,34 @@ def __init__(self, **kwargs):
                 kwdict[option] = aliases._value
         super().__init__(kwdict)
 
+    def add_common(self, **kwargs):
+        """
+        Add common parameters to the alias dictionary.
+        """
+        for key, value in kwargs.items():
+            match key:
+                case "V":
+                    name = "verbose"
+                    alias = Alias(
+                        value,
+                        name=name,
+                        mapping={
+                            "quiet": "q",
+                            "error": "e",
+                            "warning": "w",
+                            "timing": "t",
+                            "information": "i",
+                            "compatibility": "c",
+                            "debug": "d",
+                        },
+                    )
+                case _:
+                    raise GMTValueError(key, description="common parameter")
+
+            self.aliasdict[key] = alias
+            self[key] = alias._value
+        return self
+
     def merge(self, kwargs: Mapping[str, Any]):
         """
         Update the dictionary with additional keyword arguments.

pygmt/src/basemap.py

@@ -2,6 +2,8 @@
 basemap - Plot base maps and frames.
 """
 
+from typing import Literal
+
 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
@@ -17,14 +19,27 @@
     F="box",
     Td="rose",
     Tm="compass",
-    V="verbose",
     c="panel",
     f="coltypes",
     p="perspective",
     t="transparency",
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
-def basemap(self, projection=None, **kwargs):
+def basemap(
+    self,
+    projection=None,
+    verbose: Literal[
+        "quiet",
+        "error",
+        "warning",
+        "timing",
+        "information",
+        "compatibility",
+        "debug",
+    ]
+    | bool = False,
+    **kwargs,
+):
     r"""
     Plot base maps and frames.
 
@@ -39,7 +54,8 @@ def basemap(self, projection=None, **kwargs):
     Full GMT docs at :gmt-docs:`basemap.html`.
 
     {aliases}
-       - J=projection
+       - J = projection
+       - V = verbose
 
     Parameters
     ----------
@@ -86,6 +102,10 @@ def basemap(self, projection=None, **kwargs):
     self._activate_figure()
     aliasdict = AliasSystem(
         J=Alias(projection, name="projection"),
-    ).merge(kwargs)
+    ).add_common(
+        V=verbose,
+    )
+    aliasdict.merge(kwargs)
+
     with Session() as lib:
         lib.call_module(module="basemap", args=build_arg_list(aliasdict))

pygmt/src/coast.py

@@ -44,6 +44,16 @@ def coast(
     resolution: Literal[
         "auto", "full", "high", "intermediate", "low", "crude", None
     ] = None,
+    verbose: Literal[
+        "quiet",
+        "error",
+        "warning",
+        "timing",
+        "information",
+        "compatibility",
+        "debug",
+    ]
+    | bool = False,
     **kwargs,
 ):
     r"""
@@ -66,8 +76,9 @@ def coast(
     Full GMT docs at :gmt-docs:`coast.html`.
 
     {aliases}
-       - D=resolution
-       - J=projection
+       - D = resolution
+       - J = projection
+       - V = verbose
 
     Parameters
     ----------
@@ -227,7 +238,10 @@ def coast(
             },
         ),
         J=Alias(projection, name="projection"),
-    ).merge(kwargs)
+    ).add_common(
+        V=verbose,
+    )
+    aliasdict.merge(kwargs)
 
     with Session() as lib:
         lib.call_module(module="coast", args=build_arg_list(aliasdict))