Use GMTParameterError for missing required parameters

seisman · seisman · commit d553a25b300a · 2025-07-21T19:55:18.000+08:00
diff --git a/pygmt/src/filter1d.py b/pygmt/src/filter1d.py
@@ -8,7 +8,7 @@
 import pandas as pd
 from pygmt._typing import PathLike, TableLike
 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)
 
diff --git a/pygmt/src/grdlandmask.py b/pygmt/src/grdlandmask.py
@@ -8,7 +8,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,
@@ -115,8 +115,7 @@ def grdlandmask(
     >>> landmask = pygmt.grdlandmask(spacing=1, region=[125, 130, 30, 35])
     """
     if kwargs.get("I") is None or kwargs.get("R") is None:
-        msg = "Both 'region' and 'spacing' must be specified."
-        raise GMTInvalidInput(msg)
+        raise GMTParameterError(required={"spacing", "region"})
 
     kwargs["D"] = kwargs.get("D", _parse_coastline_resolution(resolution))
     kwargs["N"] = sequence_join(maskvalues, size=(2, 5), name="maskvalues")
diff --git a/pygmt/src/grdproject.py b/pygmt/src/grdproject.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__ = ["grdproject"]
@@ -106,8 +106,7 @@ def grdproject(
     >>> new_grid = pygmt.grdproject(grid=grid, projection="M10c", region=region)
     """
     if kwargs.get("J") is None:
-        msg = "The projection must be specified."
-        raise GMTInvalidInput(msg)
+        raise GMTParameterError(required={"projection"})
 
     with Session() as lib:
         with (
diff --git a/pygmt/src/grdtrack.py b/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
+from pygmt.exceptions import GMTInvalidInput, GMTParameterError
 from pygmt.helpers import (
     build_arg_list,
     fmt_docstring,
@@ -300,8 +300,10 @@ 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="Parameter 'newcolname' is required when 'points' is a pandas.DataFrame object.",
+        )
 
     output_type = validate_output_table_type(output_type, outfile=outfile)
 
diff --git a/pygmt/src/meca.py b/pygmt/src/meca.py
@@ -9,7 +9,7 @@
 import pandas as pd
 from pygmt._typing import PathLike, TableLike
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput, GMTValueError
+from pygmt.exceptions import GMTParameterError, GMTValueError
 from pygmt.helpers import (
     build_arg_list,
     data_kind,
@@ -30,8 +30,7 @@ def _get_focal_convention(spec, convention, component) -> _FocalMechanismConvent
 
     # Determine the convention from the 'convention' parameter.
     if convention is None:
-        msg = "Parameter 'convention' must be specified."
-        raise GMTInvalidInput(msg)
+        raise GMTParameterError(required={"convention"})
     return _FocalMechanismConvention(convention=convention, component=component)
 
 
diff --git a/pygmt/src/project.py b/pygmt/src/project.py
@@ -8,7 +8,7 @@
 import pandas as pd
 from pygmt._typing import PathLike, TableLike
 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,
@@ -223,8 +223,7 @@ def project(
           (depends on ``output_type``)
     """
     if kwargs.get("C") is None:
-        msg = "The 'center' parameter must be specified."
-        raise GMTInvalidInput(msg)
+        raise GMTParameterError(required={"center"})
     if kwargs.get("G") is None and data is None:
         msg = "The 'data' parameter must be specified unless 'generate' is used."
         raise GMTInvalidInput(msg)
diff --git a/pygmt/src/sphdistance.py b/pygmt/src/sphdistance.py
@@ -6,7 +6,7 @@
 import xarray as xr
 from pygmt._typing import PathLike, TableLike
 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__ = ["sphdistance"]
@@ -115,8 +115,8 @@ def sphdistance(
     ... )
     """
     if kwargs.get("I") is None or kwargs.get("R") is None:
-        msg = "Both 'region' and 'spacing' must be specified."
-        raise GMTInvalidInput(msg)
+        raise GMTParameterError(required={"spacing", "region"})
+
     with Session() as lib:
         with (
             lib.virtualfile_in(check_kind="vector", data=data, x=x, y=y) as vintbl,
diff --git a/pygmt/src/velo.py b/pygmt/src/velo.py
@@ -6,7 +6,7 @@
 import pandas as pd
 from pygmt._typing import PathLike, TableLike
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput, GMTTypeError
+from pygmt.exceptions import GMTParameterError, GMTTypeError
 from pygmt.helpers import (
     build_arg_list,
     fmt_docstring,
@@ -241,11 +241,8 @@ def velo(self, data: PathLike | TableLike | None = None, **kwargs):
     """
     self._activate_figure()
 
-    if kwargs.get("S") is None or (
-        kwargs.get("S") is not None and not isinstance(kwargs["S"], str)
-    ):
-        msg = "The parameter 'spec' is required and has to be a string."
-        raise GMTInvalidInput(msg)
+    if kwargs.get("S") is None:
+        raise GMTParameterError(required={"spec"})
 
     if isinstance(data, np.ndarray) and not pd.api.types.is_numeric_dtype(data):
         raise GMTTypeError(
diff --git a/pygmt/src/xyz2grd.py b/pygmt/src/xyz2grd.py
@@ -5,7 +5,7 @@
 import xarray as xr
 from pygmt._typing import PathLike, TableLike
 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__ = ["xyz2grd"]
@@ -149,8 +149,7 @@ def xyz2grd(
     ... )
     """
     if kwargs.get("I") is None or kwargs.get("R") is None:
-        msg = "Both 'region' and 'spacing' must be specified."
-        raise GMTInvalidInput(msg)
+        raise GMTParameterError(required={"spacing", "region"})
 
     with Session() as lib:
         with (
diff --git a/pygmt/tests/test_grdlandmask.py b/pygmt/tests/test_grdlandmask.py
@@ -8,7 +8,7 @@
 import xarray as xr
 from pygmt import grdlandmask
 from pygmt.enums import GridRegistration, GridType
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTParameterError
 from pygmt.helpers import GMTTempFile
 
 
@@ -64,5 +64,5 @@ def test_grdlandmask_fails():
     """
     Check that grdlandmask fails correctly when region and spacing are not given.
     """
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         grdlandmask()
diff --git a/pygmt/tests/test_grdproject.py b/pygmt/tests/test_grdproject.py
@@ -8,7 +8,7 @@
 import xarray as xr
 from pygmt import grdproject
 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
 
@@ -85,5 +85,5 @@ def test_grdproject_fails(grid):
     """
     Check that grdproject fails correctly.
     """
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         grdproject(grid=grid)
diff --git a/pygmt/tests/test_grdtrack.py b/pygmt/tests/test_grdtrack.py
@@ -9,7 +9,7 @@
 import pandas as pd
 import pytest
 from pygmt import grdtrack
-from pygmt.exceptions import GMTInvalidInput, GMTTypeError
+from pygmt.exceptions import GMTInvalidInput, GMTParameterError, GMTTypeError
 from pygmt.helpers import GMTTempFile
 from pygmt.helpers.testing import load_static_earth_relief
 
@@ -146,7 +146,7 @@ def test_grdtrack_without_newcolname_setting(dataarray, dataframe):
     """
     Run grdtrack by not passing in newcolname parameter setting.
     """
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         grdtrack(points=dataframe, grid=dataarray)
 
 
diff --git a/pygmt/tests/test_meca.py b/pygmt/tests/test_meca.py
@@ -10,7 +10,7 @@
 from packaging.version import Version
 from pygmt import Figure
 from pygmt.clib import __gmt_version__
-from pygmt.exceptions import GMTInvalidInput, GMTValueError
+from pygmt.exceptions import GMTParameterError, GMTValueError
 from pygmt.helpers import GMTTempFile
 
 
@@ -308,7 +308,7 @@ def test_meca_spec_ndarray_no_convention():
     """
     fig = Figure()
     fig.basemap(region=[-125, -122, 47, 49], projection="M6c", frame=True)
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.meca(spec=np.array([[-124, 48, 12.0, 330, 30, 90, 3]]), scale="1c")
 
 
diff --git a/pygmt/tests/test_project.py b/pygmt/tests/test_project.py
@@ -10,7 +10,7 @@
 import pytest
 import xarray as xr
 from pygmt import project
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTInvalidInput, GMTParameterError
 from pygmt.helpers import GMTTempFile
 
 
@@ -81,7 +81,7 @@ def test_project_incorrect_parameters():
     Run project by providing incorrect parameters such as 1) no `center`; 2) no `data`
     or `generate`; and 3) `generate` with `convention`.
     """
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError, match="center"):
         # No `center`
         project(azimuth=45)
     with pytest.raises(GMTInvalidInput):
diff --git a/pygmt/tests/test_sphdistance.py b/pygmt/tests/test_sphdistance.py
@@ -9,7 +9,7 @@
 import pytest
 from pygmt import sphdistance
 from pygmt.enums import GridRegistration, GridType
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTParameterError
 from pygmt.helpers import GMTTempFile
 
 
@@ -69,5 +69,5 @@ def test_sphdistance_fails(array):
     """
     Check that sphdistance fails correctly when neither increment nor region is given.
     """
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         sphdistance(data=array)
diff --git a/pygmt/tests/test_velo.py b/pygmt/tests/test_velo.py
@@ -5,7 +5,7 @@
 import pandas as pd
 import pytest
 from pygmt import Figure
-from pygmt.exceptions import GMTInvalidInput, GMTTypeError
+from pygmt.exceptions import GMTParameterError, GMTTypeError
 
 
 @pytest.fixture(scope="module", name="dataframe")
@@ -60,7 +60,7 @@ def test_velo_without_spec(dataframe):
     Check that velo fails when the spec parameter is not given.
     """
     fig = Figure()
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError, match="spec"):
         fig.velo(data=dataframe)
 
 
diff --git a/pygmt/tests/test_xyz2grd.py b/pygmt/tests/test_xyz2grd.py
@@ -10,7 +10,7 @@
 from pygmt import xyz2grd
 from pygmt.datasets import load_sample_data
 from pygmt.enums import GridRegistration, GridType
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTParameterError
 from pygmt.helpers import GMTTempFile
 
 
@@ -75,9 +75,9 @@ def test_xyz2grd_missing_region_spacing(ship_data):
     """
     Test xyz2grd raise an exception if region or spacing is missing.
     """
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         xyz2grd(data=ship_data)
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         xyz2grd(data=ship_data, region=[245, 255, 20, 30])
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         xyz2grd(data=ship_data, spacing=5)
