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,13 @@ 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'.
+        pygmt.exceptions.GMTValueError: Invalid GMT common option: 'A'. Expected ...
         """
-        if option not in "BIJRUVXYabfghinoprst:":
-            msg = f"Unknown GMT common option flag '{option}'."
-            raise GMTInvalidInput(msg)
+        valid_options = "BIJRUVXYabfghinoprst:"
+        if option not in valid_options:
+            raise GMTValueError(
+                option, description="GMT common option", choices=valid_options
+            )
 
         c_get_common = self.get_libgmt_func(
             "GMT_Get_Common",
@@ -847,15 +854,15 @@ def _parse_constant(
         their values are added.
 
         If no valid modifiers are given, then will assume that modifiers are not
-        allowed. In this case, will raise a :class:`pygmt.exceptions.GMTInvalidInput`
+        allowed. In this case, will raise a :class:`pygmt.exceptions.GMTValueError`
         exception if given a modifier.
 
         Parameters
         ----------
         constant
             The name of a valid GMT API constant, with an optional modifier.
         valid
-            A list of valid values for the constant. Will raise a GMTInvalidInput
+            A list of valid values for the constant. Will raise a GMTValueError
             exception if the given value is not in the list.
         valid_modifiers
             A list of valid modifiers that can be added to the constant. If ``None``,
@@ -866,28 +873,23 @@ 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, 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,15 @@ 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",
+                    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=fmts.keys()
+                )
 
         if transparent and ext not in {"kml", "png"}:
             msg = f"Transparency unavailable for '{ext}', only for png and kml."
@@ -249,8 +253,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 +366,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 +502,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/helpers/decorators.py

@@ -12,7 +12,7 @@
 from inspect import Parameter, signature
 
 import numpy as np
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTInvalidInput, GMTValueError
 from pygmt.helpers.utils import is_nonstr_iter
 
 COMMON_DOCSTRINGS = {
@@ -732,8 +732,11 @@ def kwargs_to_strings(**conversions):
 
     for arg, fmt in conversions.items():
         if fmt not in separators:
-            msg = f"Invalid conversion type '{fmt}' for argument '{arg}'."
-            raise GMTInvalidInput(msg)
+            raise GMTValueError(
+                fmt,
+                description=f"conversion type for parameter '{arg}'",
+                choices=separators.keys(),
+            )
 
     # Make the actual decorator function
     def converter(module_func):

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
 
 
@@ -115,12 +115,12 @@ class _FocalMechanismConvention:
     >>> conv = _FocalMechanismConvention(convention="invalid")
     Traceback (most recent call last):
         ...
-    pygmt.exceptions.GMTInvalidInput: Invalid focal mechanism ...'.
+    pygmt.exceptions.GMTValueError: Invalid focal mechanism convention: ...
 
     >>> conv = _FocalMechanismConvention("mt", component="invalid")
     Traceback (most recent call last):
         ...
-    pygmt.exceptions.GMTInvalidInput: Invalid focal mechanism ...'.
+    pygmt.exceptions.GMTValueError: Invalid focal mechanism convention: ...
 
     >>> _FocalMechanismConvention.from_params(["strike", "dip", "rake"])
     Traceback (most recent call last):
@@ -198,11 +198,8 @@ def __init__(
         else:  # Convention is specified via "convention" and "component".
             name = f"{convention.upper()}_{component.upper()}"  # e.g., "AKI_DC"
             if name not in _FocalMechanismConventionCode.__members__:
-                msg = (
-                    "Invalid focal mechanism convention with "
-                    f"convention='{convention}' and component='{component}'."
-                )
-                raise GMTInvalidInput(msg)
+                _value = f"convention='{convention}', component='{component}'"
+                raise GMTValueError(_value, description="focal mechanism convention")
             self.code = _FocalMechanismConventionCode[name]
             self._convention = convention
 
@@ -287,7 +284,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 +297,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/psconvert.py

@@ -5,7 +5,7 @@
 from pathlib import Path
 
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTValueError
 from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
 
 
@@ -115,8 +115,11 @@ def psconvert(self, **kwargs):
 
     prefix = kwargs.get("F")
     if prefix in {"", None, False, True}:
-        msg = "The 'prefix' parameter must be specified with a valid value."
-        raise GMTInvalidInput(msg)
+        raise GMTValueError(
+            prefix,
+            description="output file name",
+            reason="Parameter 'prefix' can't be None, bool, or an empty string.",
+        )
 
     # Check if the parent directory exists
     prefix_path = Path(prefix).parent