Use GMTParameterError for parameters where at least one is required

Author: seisman

pygmt/exceptions.py

@@ -140,6 +140,8 @@ class GMTParameterError(GMTError):
     ----------
     required
         Names of required parameters.
+    require_any
+        Names of parameters where at least one must be specified.
     exclusive
         Names of mutually exclusive parameters.
     reason
@@ -150,6 +152,7 @@ def __init__(
         self,
         *,
         required: Set[str] | None = None,
+        require_any: Set[str] | None = None,
         exclusive: Set[str] | None = None,
         reason: str | None = None,
     ):
@@ -159,6 +162,11 @@ def __init__(
                 "Required parameter(s) are missing: "
                 f"{', '.join(repr(par) for par in required)}."
             )
+        if require_any:
+            msg = (
+                "At least one of the following parameters must be specified: "
+                f"{', '.join(repr(par) for par in require_any)}."
+            )
         if exclusive:
             msg = (
                 "Mutually exclusive parameter(s) are specified: "

pygmt/src/coast.py

@@ -5,7 +5,7 @@
 from typing import Literal
 
 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,
@@ -206,11 +206,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)
 
     kwargs["D"] = kwargs.get("D", _parse_coastline_resolution(resolution))
 

pygmt/src/dimfilter.py

@@ -5,7 +5,7 @@
 import xarray as xr
 from pygmt._typing import PathLike
 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"]
@@ -138,11 +138,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"})
     with Session() as lib:
         with (
             lib.virtualfile_in(check_kind="raster", data=grid) as vingrd,

pygmt/src/grdclip.py

@@ -7,7 +7,7 @@
 import xarray as xr
 from pygmt._typing import PathLike
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTParameterError
 from pygmt.helpers import (
     build_arg_list,
     deprecate_parameter,
@@ -107,11 +107,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"})
 
     # Parse the -S option.
     kwargs["Sa"] = sequence_join(above, size=2, name="above")

pygmt/src/grdgradient.py

@@ -5,7 +5,7 @@
 import xarray as xr
 from pygmt._typing import PathLike
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTInvalidInput, GMTParameterError
 from pygmt.helpers import (
     args_in_kwargs,
     build_arg_list,
@@ -165,11 +165,8 @@ def grdgradient(
         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 GMTInvalidInput(msg)
+        raise GMTParameterError(require_any={"azimuth", "direction", "radiance"})
+
     with Session() as lib:
         with (
             lib.virtualfile_in(check_kind="raster", data=grid) as vingrd,

pygmt/src/grdtrack.py

@@ -9,7 +9,7 @@
 import xarray as xr
 from pygmt._typing import PathLike, TableLike
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput, GMTParameterError
+from pygmt.exceptions import GMTParameterError
 from pygmt.helpers import (
     build_arg_list,
     fmt_docstring,
@@ -295,8 +295,7 @@ def grdtrack(
         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:
         raise GMTParameterError(

pygmt/tests/test_coast.py

@@ -4,7 +4,7 @@
 
 import pytest
 from pygmt import Figure
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTInvalidInput, GMTParameterError
 
 
 @pytest.mark.benchmark
@@ -40,7 +40,7 @@ def test_coast_required_args():
     Test if fig.coast fails when not given required arguments.
     """
     fig = Figure()
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.coast(region="EG")
 
 

pygmt/tests/test_dimfilter.py

@@ -8,7 +8,7 @@
 import xarray as xr
 from pygmt import dimfilter
 from pygmt.enums import GridRegistration, GridType
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTParameterError
 from pygmt.helpers import GMTTempFile
 from pygmt.helpers.testing import load_static_earth_relief
 
@@ -80,5 +80,5 @@ def test_dimfilter_fails(grid):
     Check that dimfilter fails correctly when not all of sectors, filters, and distance
     are specified.
     """
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         dimfilter(grid=grid, sectors="l6", distance=4)

pygmt/tests/test_grdclip.py

@@ -11,7 +11,7 @@
 from pygmt import grdclip
 from pygmt.datasets import load_earth_mask
 from pygmt.enums import GridRegistration, GridType
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTParameterError
 from pygmt.helpers import GMTTempFile
 from pygmt.helpers.testing import load_static_earth_relief
 
@@ -110,5 +110,5 @@ def test_grdclip_missing_required_parameter(grid):
     """
     Test that grdclip raises a ValueError if the required parameter is missing.
     """
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         grdclip(grid=grid)

pygmt/tests/test_grdgradient.py

@@ -8,7 +8,7 @@
 import xarray as xr
 from pygmt import grdgradient
 from pygmt.enums import GridRegistration, GridType
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTInvalidInput, GMTParameterError
 from pygmt.helpers import GMTTempFile
 from pygmt.helpers.testing import load_static_earth_relief
 
@@ -80,7 +80,7 @@ def test_grdgradient_fails(grid):
     Check that grdgradient fails correctly when `tiles` is specified but
     normalize is not.
     """
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         grdgradient(grid=grid)  # fails without required arguments
     with pytest.raises(GMTInvalidInput):
         # fails when tiles is specified but not normalize