Migrate the parameter 'verbose' to the new alias system and let it support descriptive arguments (#4039)

Author: seisman

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)
+    - ``"info"``: Informational messages (same as ``verbose=True``)
+    - ``"compat"``: 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,6 +234,7 @@ class AliasSystem(UserDict):
     ...         B=Alias(frame, name="frame"),
     ...         D=Alias(repeat, name="repeat"),
     ...     ).add_common(
+    ...         V=verbose,
     ...         c=panel,
     ...     )
     ...     aliasdict.merge(kwargs)
@@ -238,9 +246,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):
@@ -276,6 +285,20 @@ def add_common(self, **kwargs):
         """
         for key, value in kwargs.items():
             match key:
+                case "V":
+                    alias = Alias(
+                        value,
+                        name="verbose",
+                        mapping={
+                            "quiet": "q",
+                            "error": "e",
+                            "warning": "w",
+                            "timing": "t",
+                            "info": "i",
+                            "compat": "c",
+                            "debug": "d",
+                        },
+                    )
                 case "J":
                     alias = Alias(value, name="projection")
                 case "c":

pygmt/src/basemap.py

@@ -2,6 +2,8 @@
 basemap - Plot base maps and frames.
 """
 
+from typing import Literal
+
 from pygmt.alias import AliasSystem
 from pygmt.clib import Session
 from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
@@ -17,14 +19,18 @@
     F="box",
     Td="rose",
     Tm="compass",
-    V="verbose",
     f="coltypes",
     p="perspective",
     t="transparency",
 )
 @kwargs_to_strings(R="sequence", p="sequence")
 def basemap(
-    self, projection=None, panel: int | tuple[int, int] | bool = False, **kwargs
+    self,
+    projection=None,
+    verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
+    | bool = False,
+    panel: int | tuple[int, int] | bool = False,
+    **kwargs,
 ):
     r"""
     Plot base maps and frames.
@@ -41,6 +47,7 @@ def basemap(
 
     {aliases}
        - J = projection
+       - V = verbose
        - c = panel
 
     Parameters
@@ -89,6 +96,7 @@ def basemap(
 
     aliasdict = AliasSystem().add_common(
         J=projection,
+        V=verbose,
         c=panel,
     )
     aliasdict.merge(kwargs)

pygmt/src/binstats.py

@@ -18,7 +18,6 @@
     N="normalize",
     R="region",
     S="search_radius",
-    V="verbose",
     W="weight",
     a="aspatial",
     b="binary",
@@ -49,6 +48,8 @@ def binstats(
         "sum",
     ] = "number",
     quantile_value: float = 50,
+    verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
+    | bool = False,
     **kwargs,
 ) -> xr.DataArray | None:
     r"""
@@ -66,6 +67,7 @@ def binstats(
 
     {aliases}
        - C = statistic
+       - V = verbose
 
     Parameters
     ----------
@@ -151,7 +153,10 @@ def binstats(
                 "sum": "z",
             },
         ),
-    ).merge(kwargs)
+    ).add_common(
+        V=verbose,
+    )
+    aliasdict.merge(kwargs)
     if statistic == "quantile":
         aliasdict["C"] += f"{quantile_value}"
 

pygmt/src/blockm.py

@@ -7,6 +7,7 @@
 import numpy as np
 import pandas as pd
 from pygmt._typing import PathLike, TableLike
+from pygmt.alias import AliasSystem
 from pygmt.clib import Session
 from pygmt.helpers import (
     build_arg_list,
@@ -74,7 +75,6 @@ def _blockm(
     I="spacing",
     R="region",
     S="summary",
-    V="verbose",
     a="aspatial",
     b="binary",
     d="nodata",
@@ -94,6 +94,8 @@ def blockmean(
     z=None,
     output_type: Literal["pandas", "numpy", "file"] = "pandas",
     outfile: PathLike | None = None,
+    verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
+    | bool = False,
     **kwargs,
 ) -> pd.DataFrame | np.ndarray | None:
     r"""
@@ -111,6 +113,7 @@ def blockmean(
     Full GMT docs at :gmt-docs:`blockmean.html`.
 
     {aliases}
+       - V = verbose
 
     Parameters
     ----------
@@ -162,6 +165,11 @@ def blockmean(
     >>> # Calculate block mean values within 5 by 5 arc-minute bins
     >>> data_bmean = pygmt.blockmean(data=data, region=[245, 255, 20, 30], spacing="5m")
     """
+    aliasdict = AliasSystem().add_common(
+        V=verbose,
+    )
+    aliasdict.merge(kwargs)
+
     return _blockm(
         block_method="blockmean",
         data=data,
@@ -170,15 +178,14 @@ def blockmean(
         z=z,
         output_type=output_type,
         outfile=outfile,
-        **kwargs,
+        **aliasdict,
     )
 
 
 @fmt_docstring
 @use_alias(
     I="spacing",
     R="region",
-    V="verbose",
     a="aspatial",
     b="binary",
     d="nodata",
@@ -198,6 +205,8 @@ def blockmedian(
     z=None,
     output_type: Literal["pandas", "numpy", "file"] = "pandas",
     outfile: PathLike | None = None,
+    verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
+    | bool = False,
     **kwargs,
 ) -> pd.DataFrame | np.ndarray | None:
     r"""
@@ -215,6 +224,7 @@ def blockmedian(
     Full GMT docs at :gmt-docs:`blockmedian.html`.
 
     {aliases}
+       - V = verbose
 
     Parameters
     ----------
@@ -260,6 +270,11 @@ def blockmedian(
     ...     data=data, region=[245, 255, 20, 30], spacing="5m"
     ... )
     """
+    aliasdict = AliasSystem().add_common(
+        V=verbose,
+    )
+    aliasdict.merge(kwargs)
+
     return _blockm(
         block_method="blockmedian",
         data=data,
@@ -268,15 +283,14 @@ def blockmedian(
         z=z,
         output_type=output_type,
         outfile=outfile,
-        **kwargs,
+        **aliasdict,
     )
 
 
 @fmt_docstring
 @use_alias(
     I="spacing",
     R="region",
-    V="verbose",
     a="aspatial",
     b="binary",
     d="nodata",
@@ -296,6 +310,8 @@ def blockmode(
     z=None,
     output_type: Literal["pandas", "numpy", "file"] = "pandas",
     outfile: PathLike | None = None,
+    verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
+    | bool = False,
     **kwargs,
 ) -> pd.DataFrame | np.ndarray | None:
     r"""
@@ -313,6 +329,7 @@ def blockmode(
     Full GMT docs at :gmt-docs:`blockmode.html`.
 
     {aliases}
+       - V = verbose
 
     Parameters
     ----------
@@ -356,6 +373,11 @@ def blockmode(
     >>> # Calculate block mode values within 5 by 5 arc-minute bins
     >>> data_bmode = pygmt.blockmode(data=data, region=[245, 255, 20, 30], spacing="5m")
     """
+    aliasdict = AliasSystem().add_common(
+        V=verbose,
+    )
+    aliasdict.merge(kwargs)
+
     return _blockm(
         block_method="blockmode",
         data=data,
@@ -364,5 +386,5 @@ def blockmode(
         z=z,
         output_type=output_type,
         outfile=outfile,
-        **kwargs,
+        **aliasdict,
     )

pygmt/src/coast.py

@@ -31,7 +31,6 @@
     N="borders",
     R="region",
     S="water",
-    V="verbose",
     W="shorelines",
     p="perspective",
     t="transparency",
@@ -43,6 +42,8 @@ def coast(
     resolution: Literal[
         "auto", "full", "high", "intermediate", "low", "crude", None
     ] = None,
+    verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
+    | bool = False,
     panel: int | tuple[int, int] | bool = False,
     **kwargs,
 ):
@@ -68,6 +69,7 @@ def coast(
     {aliases}
        - D = resolution
        - J = projection
+       - V = verbose
        - c = panel
 
     Parameters
@@ -229,6 +231,7 @@ def coast(
         ),
     ).add_common(
         J=projection,
+        V=verbose,
         c=panel,
     )
     aliasdict.merge(kwargs)

pygmt/src/colorbar.py

@@ -2,6 +2,8 @@
 colorbar - Plot gray scale or color scale bar.
 """
 
+from typing import Literal
+
 from pygmt.alias import AliasSystem
 from pygmt.clib import Session
 from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
@@ -20,15 +22,19 @@
     L="equalsize",
     Q="log",
     R="region",
-    V="verbose",
     W="scale",
     Z="zfile",
     p="perspective",
     t="transparency",
 )
 @kwargs_to_strings(R="sequence", G="sequence", I="sequence", p="sequence")
 def colorbar(
-    self, projection=None, panel: int | tuple[int, int] | bool = False, **kwargs
+    self,
+    projection=None,
+    verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
+    | bool = False,
+    panel: int | tuple[int, int] | bool = False,
+    **kwargs,
 ):
     r"""
     Plot gray scale or color scale bar.
@@ -45,6 +51,7 @@ def colorbar(
 
     {aliases}
        - J = projection
+       - V = verbose
        - c = panel
 
     Parameters
@@ -149,6 +156,7 @@ def colorbar(
 
     aliasdict = AliasSystem().add_common(
         J=projection,
+        V=verbose,
         c=panel,
     )
     aliasdict.merge(kwargs)