BREAKING: Raise GMTParameterError exception for missing required parameters. Previously raise GMTInvalidInput (#4374)

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

Author: Chuan1937

doc/api/index.rst

@@ -293,14 +293,15 @@ All custom exceptions are derived from :class:`pygmt.exceptions.GMTError`.
     :toctree: generated
 
     exceptions.GMTError
-    exceptions.GMTInvalidInput
-    exceptions.GMTVersionError
-    exceptions.GMTOSError
     exceptions.GMTCLibError
     exceptions.GMTCLibNoSessionError
     exceptions.GMTCLibNotFoundError
+    exceptions.GMTInvalidInput
+    exceptions.GMTOSError
+    exceptions.GMTParameterError
     exceptions.GMTTypeError
     exceptions.GMTValueError
+    exceptions.GMTVersionError
 
 
 .. currentmodule:: pygmt

pygmt/datasets/load_remote_dataset.py

@@ -7,7 +7,7 @@
 from typing import Any, Literal, NamedTuple
 
 import xarray as xr
-from pygmt.exceptions import GMTInvalidInput, GMTValueError
+from pygmt.exceptions import GMTParameterError, GMTValueError
 
 with contextlib.suppress(ImportError):
     # rioxarray is needed to register the rio accessor
@@ -564,11 +564,10 @@ def _load_remote_dataset(
             reg = registration[0]
 
     if resinfo.tiled and region is None:
-        msg = (
-            f"The 'region' parameter is required for {dataset.description} "
-            f"resolution '{resolution}'."
+        raise GMTParameterError(
+            required="region",
+            reason=f"Required for {dataset.description} resolution {resolution!r}.",
         )
-        raise GMTInvalidInput(msg)
 
     fname = f"@{prefix}_{resolution}_{reg}"
     grid = xr.load_dataarray(

pygmt/exceptions.py

@@ -130,3 +130,35 @@ def __init__(self, dtype: object, /, reason: str | None = None):
         if reason:
             msg += f" {reason}"
         super().__init__(msg)
+
+
+class GMTParameterError(GMTError):
+    """
+    Raised when parameters are missing or invalid.
+
+    Parameters
+    ----------
+    required
+       Name or a set of names of required parameters.
+    reason
+        Detailed reason why the parameters are invalid.
+    """
+
+    def __init__(
+        self,
+        *,
+        required: str | set[str] | None = None,
+        reason: str | None = None,
+    ):
+        msg = []
+        if required:
+            if isinstance(required, str):
+                msg.append(f"Missing required parameter: {required!r}.")
+            else:
+                msg.append(
+                    "Missing required parameters: "
+                    f"{', '.join(repr(par) for par in required)}."
+                )
+        if reason:
+            msg.append(reason)
+        super().__init__(" ".join(msg))

pygmt/helpers/validators.py

@@ -6,7 +6,7 @@
 from typing import Literal
 
 from pygmt._typing import PathLike
-from pygmt.exceptions import GMTInvalidInput, GMTValueError
+from pygmt.exceptions import GMTParameterError, GMTValueError
 
 
 def validate_output_table_type(
@@ -43,7 +43,7 @@ def validate_output_table_type(
     >>> validate_output_table_type("file", outfile=None)
     Traceback (most recent call last):
         ...
-    pygmt.exceptions.GMTInvalidInput: Must specify 'outfile' for output_type='file'.
+    pygmt.exceptions.GMTParameterError: Missing required parameter: 'outfile'. ...
     >>> with warnings.catch_warnings(record=True) as w:
     ...     validate_output_table_type("pandas", outfile="not-none.txt")
     ...     assert len(w) == 1
@@ -57,8 +57,9 @@ def validate_output_table_type(
             choices=_valids,
         )
     if output_type == "file" and outfile is None:
-        msg = "Must specify 'outfile' for output_type='file'."
-        raise GMTInvalidInput(msg)
+        raise GMTParameterError(
+            required="outfile", reason="Required when output_type='file'."
+        )
     if output_type != "file" and outfile is not None:
         msg = (
             f"Changing 'output_type' from '{output_type}' to 'file' since 'outfile' "

pygmt/params/box.py

@@ -6,7 +6,7 @@
 from collections.abc import Sequence
 
 from pygmt.alias import Alias
-from pygmt.exceptions import GMTInvalidInput, GMTValueError
+from pygmt.exceptions import GMTParameterError, GMTValueError
 from pygmt.helpers import is_nonstr_iter
 from pygmt.params.base import BaseParam
 
@@ -65,8 +65,9 @@ def _validate(self):
         """
         # inner_pen is required when inner_gap is set.
         if self.inner_gap is not None and self.inner_pen is None:
-            msg = "Parameter 'inner_pen' is required when 'inner_gap' is set."
-            raise GMTInvalidInput(msg)
+            raise GMTParameterError(
+                required="inner_pen", reason="Required when 'inner_gap' is set."
+            )
 
         # shade_offset must be a sequence of two values or None.
         if self.shade_offset and not (

pygmt/src/filter1d.py

@@ -9,7 +9,7 @@
 from pygmt._typing import PathLike, TableLike
 from pygmt.alias import AliasSystem
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTParameterError
 from pygmt.helpers import (
     build_arg_list,
     fmt_docstring,
@@ -112,8 +112,7 @@ def filter1d(
           (depends on ``output_type``)
     """
     if kwargs.get("F") is None:
-        msg = "Pass a required argument to 'filter_type'."
-        raise GMTInvalidInput(msg)
+        raise GMTParameterError(required="filter_type")
 
     output_type = validate_output_table_type(output_type, outfile=outfile)
 

pygmt/src/grdgradient.py

@@ -9,7 +9,7 @@
 from pygmt._typing import PathLike
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTInvalidInput, GMTParameterError
 from pygmt.helpers import build_arg_list, fmt_docstring, use_alias
 
 __doctest_skip__ = ["grdgradient"]
@@ -166,8 +166,9 @@ def grdgradient(
     >>> new_grid = pygmt.grdgradient(grid=grid, azimuth=10)
     """
     if kwargs.get("Q") is not None and kwargs.get("N") is None:
-        msg = "Must specify normalize if tiles is specified."
-        raise GMTInvalidInput(msg)
+        raise GMTParameterError(
+            required="normalize", reason="Required when 'tiles' is set."
+        )
     if (
         kwargs.get("A", azimuth) is None
         and kwargs.get("D") is None

pygmt/src/grdlandmask.py

@@ -9,7 +9,7 @@
 from pygmt._typing import PathLike
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTParameterError
 from pygmt.helpers import build_arg_list, deprecate_parameter, fmt_docstring, use_alias
 
 __doctest_skip__ = ["grdlandmask"]
@@ -119,8 +119,7 @@ def grdlandmask(
     >>> landmask = pygmt.grdlandmask(spacing=1, region=[125, 130, 30, 35])
     """
     if kwargs.get("I", spacing) is None or kwargs.get("R", region) is None:
-        msg = "Both 'region' and 'spacing' must be specified."
-        raise GMTInvalidInput(msg)
+        raise GMTParameterError(required={"region", "spacing"})
 
     aliasdict = AliasSystem(
         D=Alias(

pygmt/src/grdproject.py

@@ -9,7 +9,7 @@
 from pygmt._typing import PathLike
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTInvalidInput, GMTParameterError
 from pygmt.helpers import build_arg_list, fmt_docstring, use_alias
 
 __doctest_skip__ = ["grdproject"]
@@ -118,8 +118,7 @@ def grdproject(  # noqa: PLR0913
     >>> new_grid = pygmt.grdproject(grid=grid, projection="M10c", region=region)
     """
     if kwargs.get("J", projection) is None:
-        msg = "Parameter 'projection' must be specified."
-        raise GMTInvalidInput(msg)
+        raise GMTParameterError(required="projection")
 
     if kwargs.get("M", unit) is not None and kwargs.get("F", scaling) is not False:
         msg = "Cannot use both 'unit' and 'scaling'."

pygmt/src/grdtrack.py

@@ -11,7 +11,7 @@
 from pygmt._typing import PathLike, TableLike
 from pygmt.alias import AliasSystem
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTInvalidInput, GMTParameterError
 from pygmt.helpers import (
     build_arg_list,
     fmt_docstring,
@@ -307,8 +307,9 @@ def grdtrack(
         raise GMTInvalidInput(msg)
 
     if hasattr(points, "columns") and newcolname is None:
-        msg = "Please pass in a str to 'newcolname'."
-        raise GMTInvalidInput(msg)
+        raise GMTParameterError(
+            required="newcolname", reason="Pass in a string to 'newcolname'."
+        )
 
     output_type = validate_output_table_type(output_type, outfile=outfile)