Add new exception GMTParameterError for invalid parameters

doc/api/index.rst

@@ -295,10 +295,10 @@ All custom exceptions are derived from :class:`pygmt.exceptions.GMTError`.
     exceptions.GMTCLibError
     exceptions.GMTCLibNoSessionError
     exceptions.GMTCLibNotFoundError
+    exceptions.GMTParameterError
     exceptions.GMTTypeError
     exceptions.GMTValueError
 
-
 .. currentmodule:: pygmt
 
 GMT C API

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} with tiled grids.",
         )
-        raise GMTInvalidInput(msg)
 
     fname = f"@{prefix}_{resolution}_{reg}"
     grid = xr.load_dataarray(

pygmt/exceptions.py

@@ -4,7 +4,7 @@
 All exceptions derive from GMTError.
 """
 
-from collections.abc import Iterable
+from collections.abc import Iterable, Set
 from typing import Any
 
 
@@ -130,3 +130,51 @@ 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
+        Names of required parameters.
+    require_any
+        Names of parameters where at least one must be specified.
+    exclusive
+        Names of mutually exclusive parameters.
+    reason
+        Detailed reason why the parameters are invalid.
+    """
+
+    def __init__(
+        self,
+        *,
+        required: Set[str] | None = None,
+        require_any: Set[str] | None = None,
+        exclusive: Set[str] | None = None,
+        reason: str | None = None,
+    ):
+        msg = []
+        if required:
+            msg.append(
+                "Required parameter(s) are missing: "
+                f"{', '.join(repr(par) for par in required)}."
+            )
+
+        if require_any:
+            msg.append(
+                "At least one of the following parameters must be specified: "
+                f"{', '.join(repr(par) for par in require_any)}."
+            )
+
+        if exclusive:
+            msg.append(
+                "Mutually exclusive parameter(s) are specified: "
+                f"{', '.join(repr(par) for par in exclusive)}."
+            )
+
+        if reason:
+            msg.append(reason)
+        super().__init__(" ".join(msg))

pygmt/src/coast.py

@@ -7,7 +7,7 @@
 
 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 (
     args_in_kwargs,
     build_arg_list,
@@ -202,11 +202,18 @@ def coast(
     """
     self._activate_figure()
     if not args_in_kwargs(args=["C", "G", "S", "I", "N", "E", "Q", "W"], kwargs=kwargs):
-        msg = (
-            "At least one of the following parameters must be specified: "
-            "lakes, land, water, rivers, borders, dcw, Q, or shorelines."
+        raise GMTParameterError(
+            require_any={
+                "lakes",
+                "land",
+                "water",
+                "rivers",
+                "borders",
+                "dcw",
+                "Q",
+                "shorelines",
+            }
         )
-        raise GMTInvalidInput(msg)
 
     aliasdict = AliasSystem(
         D=Alias(

pygmt/src/dimfilter.py

@@ -9,7 +9,7 @@
 from pygmt._typing import PathLike
 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, kwargs_to_strings, use_alias
 
 __doctest_skip__ = ["dimfilter"]
@@ -142,11 +142,7 @@ def dimfilter(
     ... )
     """
     if not all(arg in kwargs for arg in ["D", "F", "N"]) and "Q" not in kwargs:
-        msg = (
-            "At least one of the following parameters must be specified: "
-            "distance, filters, or sectors."
-        )
-        raise GMTInvalidInput(msg)
+        raise GMTParameterError(require_any={"distance", "filter", "sectors"})
 
     aliasdict = AliasSystem().add_common(
         R=region,

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/grd2cpt.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, fmt_docstring, kwargs_to_strings, use_alias
 
 __doctest_skip__ = ["grd2cpt"]
@@ -199,8 +199,7 @@ def grd2cpt(
     >>> fig.show()
     """
     if kwargs.get("W") is not None and kwargs.get("Ww") is not None:
-        msg = "Set only 'categorical' or 'cyclic' to True, not both."
-        raise GMTInvalidInput(msg)
+        raise GMTParameterError(exclusive={"categorical", "cyclic"})
 
     if (output := kwargs.pop("H", None)) is not None:
         kwargs["H"] = True

pygmt/src/grdclip.py

@@ -9,8 +9,12 @@
 from pygmt._typing import PathLike
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput
-from pygmt.helpers import build_arg_list, deprecate_parameter, fmt_docstring
+from pygmt.exceptions import GMTParameterError
+from pygmt.helpers import (
+    build_arg_list,
+    deprecate_parameter,
+    fmt_docstring,
+)
 
 __doctest_skip__ = ["grdclip"]
 
@@ -111,11 +115,7 @@ def grdclip(
     [0.0, 10000.0]
     """
     if all(v is None for v in (above, below, between, replace)):
-        msg = (
-            "Must specify at least one of the following parameters: ",
-            "'above', 'below', 'between', or 'replace'.",
-        )
-        raise GMTInvalidInput(msg)
+        raise GMTParameterError(require_any={"above", "below", "between", "replace"})
 
     aliasdict = AliasSystem(
         Sa=Alias(above, name="above", sep="/", size=2),

pygmt/src/grdfill.py

@@ -11,8 +11,13 @@
 from pygmt._typing import PathLike
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput
-from pygmt.helpers import build_arg_list, deprecate_parameter, fmt_docstring, use_alias
+from pygmt.exceptions import GMTParameterError
+from pygmt.helpers import (
+    build_arg_list,
+    deprecate_parameter,
+    fmt_docstring,
+    use_alias,
+)
 
 __doctest_skip__ = ["grdfill"]
 
@@ -34,22 +39,22 @@ def _validate_params(
     >>> _validate_params(constantfill=20.0, gridfill="bggrid.nc")
     Traceback (most recent call last):
     ...
-    pygmt.exceptions.GMTInvalidInput: Parameters ... are mutually exclusive.
+    pygmt.exceptions.GMTParameterError: Mutually exclusive parameter...
     >>> _validate_params(constantfill=20.0, inquire=True)
     Traceback (most recent call last):
     ...
-    pygmt.exceptions.GMTInvalidInput: Parameters ... are mutually exclusive.
+    pygmt.exceptions.GMTParameterError: Mutually exclusive parameter...
     >>> _validate_params()
     Traceback (most recent call last):
     ...
-    pygmt.exceptions.GMTInvalidInput: Need to specify parameter ...
+    pygmt.exceptions.GMTParameterError: ...
     """
-    _fill_params = "'constantfill'/'gridfill'/'neighborfill'/'splinefill'"
+    _fill_params = {"constantfill", "gridfill", "neighborfill", "splinefill"}
     # The deprecated 'mode' parameter is given.
     if mode is not None:
         msg = (
             "The 'mode' parameter is deprecated since v0.15.0 and will be removed in "
-            f"v0.19.0. Use {_fill_params} instead."
+            f"v0.19.0. Use {', '.join(repr(par) for par in _fill_params)} instead."
         )
         warnings.warn(msg, FutureWarning, stacklevel=2)
 
@@ -58,14 +63,15 @@ def _validate_params(
         for param in [constantfill, gridfill, neighborfill, splinefill, inquire, mode]
     )
     if n_given > 1:  # More than one mutually exclusive parameter is given.
-        msg = f"Parameters {_fill_params}/'inquire'/'mode' are mutually exclusive."
-        raise GMTInvalidInput(msg)
+        raise GMTParameterError(exclusive=[*_fill_params, "inquire", "mode"])
     if n_given == 0:  # No parameters are given.
-        msg = (
-            f"Need to specify parameter {_fill_params} for filling holes or "
-            "'inquire' for inquiring the bounds of each hole."
+        raise GMTParameterError(
+            required=_fill_params,
+            reason=(
+                f"Need to specify parameter {_fill_params!r} for filling holes or "
+                "'inquire' for inquiring the bounds of each hole."
+            ),
         )
-        raise GMTInvalidInput(msg)
 
 
 @fmt_docstring

pygmt/src/grdgradient.py

@@ -9,7 +9,7 @@
 from pygmt._typing import PathLike
 from pygmt.alias import AliasSystem
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTParameterError
 from pygmt.helpers import (
     args_in_kwargs,
     build_arg_list,
@@ -170,14 +170,12 @@ 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)
-    if not args_in_kwargs(args=["A", "D", "E"], kwargs=kwargs):
-        msg = (
-            "At least one of the following parameters must be specified: "
-            "azimuth, direction, or radiance."
+        raise GMTParameterError(
+            required={"normalize"},
+            reason="Must specify 'normalize' if 'tiles' is specified.",
         )
-        raise GMTInvalidInput(msg)
+    if not args_in_kwargs(args=["A", "D", "E"], kwargs=kwargs):
+        raise GMTParameterError(require_any={"azimuth", "direction", "radiance"})
 
     aliasdict = AliasSystem().add_common(
         R=region,

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, fmt_docstring, kwargs_to_strings, use_alias
 
 __doctest_skip__ = ["grdlandmask"]
@@ -109,8 +109,7 @@ def grdlandmask(
     >>> landmask = pygmt.grdlandmask(spacing=1, region=[125, 130, 30, 35])
     """
     if kwargs.get("I") is None or kwargs.get("R", region) is None:
-        msg = "Both 'region' and 'spacing' must be specified."
-        raise GMTInvalidInput(msg)
+        raise GMTParameterError(required={"spacing", "region"})
 
     aliasdict = AliasSystem(
         D=Alias(

pygmt/src/grdproject.py

@@ -9,7 +9,7 @@
 from pygmt._typing import PathLike
 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, kwargs_to_strings, use_alias
 
 __doctest_skip__ = ["grdproject"]
@@ -116,8 +116,7 @@ def grdproject(
     >>> new_grid = pygmt.grdproject(grid=grid, projection="M10c", region=region)
     """
     if projection is None:
-        msg = "The projection must be specified."
-        raise GMTInvalidInput(msg)
+        raise GMTParameterError(required={"projection"})
 
     aliasdict = AliasSystem().add_common(
         J=projection,

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 GMTParameterError
 from pygmt.helpers import (
     build_arg_list,
     fmt_docstring,
@@ -297,16 +297,16 @@ def grdtrack(
     ... )
     """
     if points is not None and kwargs.get("E") is not None:
-        msg = "Can't set both 'points' and 'profile'."
-        raise GMTInvalidInput(msg)
+        raise GMTParameterError(exclusive={"points", "profile"})
 
     if points is None and kwargs.get("E") is None:
-        msg = "Must give 'points' or set 'profile'."
-        raise GMTInvalidInput(msg)
+        raise GMTParameterError(require_any={"points", "profile"})
 
     if hasattr(points, "columns") and newcolname is None:
-        msg = "Please pass in a str to 'newcolname'."
-        raise GMTInvalidInput(msg)
+        raise GMTParameterError(
+            required={"newcolname"},
+            reason="Parameter 'newcolname' is required when 'points' is a pandas.DataFrame object.",
+        )
 
     output_type = validate_output_table_type(output_type, outfile=outfile)