Use the new exception

Author: seisman

pygmt/clib/session.py

@@ -24,7 +24,12 @@
 )
 from pygmt.clib.loading import get_gmt_version, load_libgmt
 from pygmt.datatypes import _GMT_DATASET, _GMT_GRID, _GMT_IMAGE
-from pygmt.exceptions import GMTCLibError, GMTCLibNoSessionError, GMTInvalidInput
+from pygmt.exceptions import (
+    GMTCLibError,
+    GMTCLibNoSessionError,
+    GMTInvalidInput,
+    GMTValueError,
+)
 from pygmt.helpers import (
     _validate_data_input,
     data_kind,
@@ -560,11 +565,15 @@ def get_common(self, option: str) -> bool | int | float | np.ndarray:
         ...     lib.get_common("A")
         Traceback (most recent call last):
         ...
-        pygmt.exceptions.GMTInvalidInput: Unknown GMT common option flag 'A'.
-        """
-        if option not in "BIJRUVXYabfghinoprst:":
-            msg = f"Unknown GMT common option flag '{option}'."
-            raise GMTInvalidInput(msg)
+        pygmt.exceptions.GMTValueError: Invalid GMT common option: 'A'. Expecetd ...
+        """
+        valid_options = "BIJRUVXYabfghinoprst:"
+        if option not in valid_options:
+            raise GMTValueError(
+                option,
+                description="GMT common option flag",
+                choices=valid_options,
+            )
 
         c_get_common = self.get_libgmt_func(
             "GMT_Get_Common",
@@ -866,28 +875,25 @@ def _parse_constant(
         nmodifiers = len(parts) - 1
 
         if name not in valid:
-            msg = f"Invalid constant name '{name}'. Must be one of {valid}."
-            raise GMTInvalidInput(msg)
+            raise GMTValueError(name, description="constant name", choices=valid)
 
         match nmodifiers:
             case 1 if valid_modifiers is None:
-                msg = (
-                    f"Constant modifiers are not allowed since valid values "
-                    f"were not given: '{constant}'."
+                raise GMTValueError(
+                    constant,
+                    reason="Constant modifiers are not allowed since valid values were not given",
                 )
-                raise GMTInvalidInput(msg)
             case 1 if valid_modifiers is not None and parts[1] not in valid_modifiers:
-                msg = (
-                    f"Invalid constant modifier '{parts[1]}'. "
-                    f"Must be one of {valid_modifiers}."
+                raise GMTValueError(
+                    parts[1],
+                    description="constant modifier",
+                    choices=valid_modifiers,
                 )
-                raise GMTInvalidInput(msg)
             case n if n > 1:
-                msg = (
-                    f"Only one modifier is allowed in constants, "
-                    f"{nmodifiers} given: '{constant}'."
+                raise GMTValueError(
+                    constant,
+                    reason=f"Only one modifier is allowed in constants but {nmodifiers} given",
                 )
-                raise GMTInvalidInput(msg)
 
         integer_value = sum(self[part] for part in parts)
         return integer_value

pygmt/datasets/earth_magnetic_anomaly.py

@@ -10,7 +10,7 @@
 
 import xarray as xr
 from pygmt.datasets.load_remote_dataset import _load_remote_dataset
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTValueError
 
 __doctest_skip__ = ["load_earth_magnetic_anomaly"]
 
@@ -135,11 +135,11 @@ def load_earth_magnetic_anomaly(
         "wdmam": "earth_wdmam",
     }.get(data_source)
     if prefix is None:
-        msg = (
-            f"Invalid earth magnetic anomaly data source '{data_source}'. "
-            "Valid values are 'emag2', 'emag2_4km', and 'wdmam'."
+        raise GMTValueError(
+            data_source,
+            description="earth magnetic anomaly data source",
+            choices=["emag2", "emag2_4km", "wdmam"],
         )
-        raise GMTInvalidInput(msg)
     grid = _load_remote_dataset(
         name="earth_wdmam" if data_source == "wdmam" else "earth_mag",
         prefix=prefix,

pygmt/datasets/earth_relief.py

@@ -10,7 +10,7 @@
 
 import xarray as xr
 from pygmt.datasets.load_remote_dataset import _load_remote_dataset
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTInvalidInput, GMTValueError
 
 __doctest_skip__ = ["load_earth_relief"]
 
@@ -154,11 +154,11 @@ def load_earth_relief(
         "synbath": "earth_synbath",
     }.get(data_source)
     if prefix is None:
-        msg = (
-            f"Invalid earth relief data source '{data_source}'. "
-            "Valid values are 'igpp', 'gebco', 'gebcosi', and 'synbath'."
+        raise GMTValueError(
+            data_source,
+            description="earth relief data source",
+            choices=["igpp", "gebco", "gebcosi", "synbath"],
         )
-        raise GMTInvalidInput(msg)
     # Use SRTM or not.
     if use_srtm and resolution in land_only_srtm_resolutions:
         if data_source != "igpp":

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
+from pygmt.exceptions import GMTInvalidInput, GMTValueError
 
 with contextlib.suppress(ImportError):
     # rioxarray is needed to register the rio accessor
@@ -546,11 +546,11 @@ def _load_remote_dataset(
 
     # Check resolution
     if resolution not in dataset.resolutions:
-        msg = (
-            f"Invalid resolution '{resolution}' for {dataset.description} dataset. "
-            f"Available resolutions are: {', '.join(dataset.resolutions)}."
+        raise GMTValueError(
+            value=resolution,
+            description=f"resolution for {dataset.description} dataset",
+            choices=dataset.resolutions.keys(),
         )
-        raise GMTInvalidInput(msg)
     resinfo = dataset.resolutions[resolution]
 
     # Check registration
@@ -559,13 +559,15 @@ def _load_remote_dataset(
             # Use gridline registration unless only pixel registration is available
             reg = "g" if "gridline" in resinfo.registrations else "p"
         case x if x not in resinfo.registrations:
-            msg = (
-                f"Invalid grid registration '{registration}' for the {resolution} "
-                f"{dataset.description} dataset. Should be either 'pixel', 'gridline' "
-                "or None. Default is None, where a gridline-registered grid is "
-                "returned unless only the pixel-registered grid is available."
+            raise GMTValueError(
+                registration,
+                description=f"grid registration for the {resolution} {dataset.description} dataset",
+                choices=[*resinfo.registrations.keys(), None],
+                reason=(
+                    "Default is None, where a gridline-registered grid is returned "
+                    "unless only the pixel-registered grid is available."
+                ),
             )
-            raise GMTInvalidInput(msg)
         case _:
             reg = registration[0]
 

pygmt/datasets/samples.py

@@ -7,7 +7,7 @@
 
 import pandas as pd
 import xarray as xr
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTValueError
 from pygmt.src import which
 
 
@@ -346,6 +346,5 @@ def load_sample_data(
     >>> data = load_sample_data("bathymetry")
     """  # noqa: W505
     if name not in datasets:
-        msg = f"Invalid dataset name '{name}'."
-        raise GMTInvalidInput(msg)
+        raise GMTValueError(name, choices=datasets.keys(), description="dataset name")
     return datasets[name].func()

pygmt/figure.py

@@ -20,7 +20,7 @@
 
 import numpy as np
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTInvalidInput, GMTValueError
 from pygmt.helpers import launch_external_viewer, unique_name
 
 
@@ -234,11 +234,16 @@ def savefig(
             case "kml":  # KML
                 kwargs["W"] = "+k"
             case "ps":
-                msg = "Extension '.ps' is not supported. Use '.eps' or '.pdf' instead."
-                raise GMTInvalidInput(msg)
+                raise GMTValueError(
+                    ext,
+                    description="file extension",
+                    choices=list(fmts.keys()),
+                    reason="Extension '.ps' is not supported. Use '.eps' or '.pdf' instead",
+                )
             case ext if ext not in fmts:
-                msg = f"Unknown extension '.{ext}'."
-                raise GMTInvalidInput(msg)
+                raise GMTValueError(
+                    ext, description="file extension", choices=list(fmts.keys())
+                )
 
         if transparent and ext not in {"kml", "png"}:
             msg = f"Transparency unavailable for '{ext}', only for png and kml."
@@ -249,8 +254,12 @@ def savefig(
 
         if worldfile:
             if ext in {"eps", "kml", "pdf", "tiff"}:
-                msg = f"Saving a world file is not supported for '{ext}' format."
-                raise GMTInvalidInput(msg)
+                raise GMTValueError(
+                    ext,
+                    description="file extension",
+                    choices=["eps", "kml", "pdf", "tiff"],
+                    reason="Saving a world file is not supported for this format",
+                )
             kwargs["W"] = True
 
         # pytest-mpl v0.17.0 added the "metadata" parameter to Figure.savefig, which is
@@ -358,11 +367,11 @@ def show(
             case "none":
                 pass  # Do nothing
             case _:
-                msg = (
-                    f"Invalid display method '{method}'. "
-                    "Valid values are 'external', 'notebook', 'none' or None."
+                raise GMTValueError(
+                    method,
+                    description="display method",
+                    choices=["external", "notebook", "none", None],
                 )
-                raise GMTInvalidInput(msg)
 
     @overload
     def _preview(
@@ -494,8 +503,8 @@ def set_display(method: Literal["external", "notebook", "none", None] = None) ->
         case None:
             SHOW_CONFIG["method"] = _get_default_display_method()
         case _:
-            msg = (
-                f"Invalid display method '{method}'. "
-                "Valid values are 'external', 'notebook', 'none' or None."
+            raise GMTValueError(
+                method,
+                description="display method",
+                choices=["external", "notebook", "none", None],
             )
-            raise GMTInvalidInput(msg)

pygmt/src/_common.py

@@ -7,7 +7,7 @@
 from pathlib import Path
 from typing import Any, ClassVar, Literal
 
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTInvalidInput, GMTValueError
 from pygmt.src.which import which
 
 
@@ -287,7 +287,7 @@ def _parse_coastline_resolution(
     >>> _parse_coastline_resolution("invalid")
     Traceback (most recent call last):
     ...
-    pygmt.exceptions.GMTInvalidInput: Invalid resolution: 'invalid'. Valid values ...
+    pygmt...GMTValueError: Invalid .... Expected ....
     """
     if resolution is None:
         return None
@@ -300,7 +300,6 @@ def _parse_coastline_resolution(
     if resolution in {_res[0] for _res in _valid_res}:  # Short-form arguments.
         return resolution  # type: ignore[return-value]
 
-    msg = (
-        f"Invalid resolution: '{resolution}'. Valid values are {', '.join(_valid_res)}."
+    raise GMTValueError(
+        resolution, choices=_valid_res, description="GSHHG coastline resolution"
     )
-    raise GMTInvalidInput(msg)

pygmt/src/grdcut.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 GMTInvalidInput, GMTValueError
 from pygmt.helpers import (
     build_arg_list,
     data_kind,
@@ -113,8 +113,7 @@ def grdcut(
     >>> new_grid = pygmt.grdcut(grid=grid, region=[12, 15, 21, 24])
     """
     if kind not in {"grid", "image"}:
-        msg = f"Invalid raster kind: '{kind}'. Valid values are 'grid' and 'image'."
-        raise GMTInvalidInput(msg)
+        raise GMTValueError(kind, description="raster kind", choices=["grid", "image"])
 
     # Determine the output data kind based on the input data kind.
     match inkind := data_kind(grid):

pygmt/src/solar.py

@@ -6,7 +6,7 @@
 
 import pandas as pd
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTInvalidInput, GMTValueError
 from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
 
 __doctest_skip__ = ["solar"]
@@ -103,11 +103,11 @@ def solar(
 
     valid_terminators = ["day_night", "civil", "nautical", "astronomical"]
     if terminator not in valid_terminators and terminator not in "dcna":
-        msg = (
-            f"Unrecognized solar terminator type '{terminator}'. "
-            f"Valid values are {valid_terminators}."
+        raise GMTValueError(
+            terminator,
+            description="solar terminator type",
+            choices=valid_terminators,
         )
-        raise GMTInvalidInput(msg)
     kwargs["T"] = terminator[0]
     if terminator_datetime:
         try:

pygmt/tests/test_clib.py

@@ -13,7 +13,7 @@
 from pygmt.exceptions import (
     GMTCLibError,
     GMTCLibNoSessionError,
-    GMTInvalidInput,
+    GMTValueError,
     GMTVersionError,
 )
 
@@ -170,7 +170,7 @@ def test_parse_constant_fails():
         "NOT_A_PROPER_FAMILY|ALSO_INVALID",
     ]
     for test_case in test_cases:
-        with pytest.raises(GMTInvalidInput):
+        with pytest.raises(GMTValueError):
             lib._parse_constant(test_case, valid=FAMILIES, valid_modifiers=VIAS)
 
     # Should also fail if not given valid modifiers but is using them anyway.
@@ -179,7 +179,7 @@ def test_parse_constant_fails():
         "GMT_IS_DATASET|GMT_VIA_MATRIX", valid=FAMILIES, valid_modifiers=VIAS
     )
     # But this shouldn't.
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTValueError):
         lib._parse_constant(
             "GMT_IS_DATASET|GMT_VIA_MATRIX", valid=FAMILIES, valid_modifiers=None
         )

pygmt/tests/test_clib_create_data.py

@@ -4,7 +4,7 @@
 
 import pytest
 from pygmt import clib
-from pygmt.exceptions import GMTCLibError, GMTInvalidInput
+from pygmt.exceptions import GMTCLibError, GMTValueError
 from pygmt.tests.test_clib import mock
 
 
@@ -64,7 +64,7 @@ def test_create_data_fails():
     Check that create_data raises exceptions for invalid input and output.
     """
     # Passing in invalid mode
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTValueError):
         with clib.Session() as lib:
             lib.create_data(
                 family="GMT_IS_DATASET",
@@ -75,7 +75,7 @@ def test_create_data_fails():
                 inc=[0.1, 0.2],
             )
     # Passing in invalid geometry
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTValueError):
         with clib.Session() as lib:
             lib.create_data(
                 family="GMT_IS_GRID",