BREAKING: Raise GMTTypeError exception for invalid types. Previously raise GMTInvalidInput (#3999)

Author: seisman

doc/api/index.rst

@@ -283,6 +283,7 @@ All custom exceptions are derived from :class:`pygmt.exceptions.GMTError`.
     exceptions.GMTCLibError
     exceptions.GMTCLibNoSessionError
     exceptions.GMTCLibNotFoundError
+    exceptions.GMTTypeError
     exceptions.GMTValueError
 
 

pygmt/clib/session.py

@@ -28,6 +28,7 @@
     GMTCLibError,
     GMTCLibNoSessionError,
     GMTInvalidInput,
+    GMTTypeError,
     GMTValueError,
 )
 from pygmt.helpers import (
@@ -629,7 +630,7 @@ def call_module(self, module: str, args: str | list[str]) -> None:
 
         Raises
         ------
-        GMTInvalidInput
+        GMTTypeError
             If the ``args`` argument is not a string or a list of strings.
         GMTCLibError
             If the returned status code of the function is non-zero.
@@ -658,8 +659,10 @@ def call_module(self, module: str, args: str | list[str]) -> None:
             mode = self["GMT_MODULE_CMD"]
             argv = args.encode()
         else:
-            msg = "'args' must either be a list of strings (recommended) or a string."
-            raise GMTInvalidInput(msg)
+            raise GMTTypeError(
+                type(args),
+                reason="Parameter 'args' must either be a list of strings (recommended) or a string.",
+            )
 
         status = c_call_module(self.session_pointer, module.encode(), mode, argv)
         if status != 0:
@@ -915,7 +918,7 @@ def _check_dtype_and_dim(self, array: np.ndarray, ndim: int) -> int:
         ------
         GMTValueError
             If the array has the wrong number of dimensions.
-        GMTInvalidInput
+        GMTTypeError
             If the array is an unsupported data type.
 
         Examples
@@ -943,8 +946,7 @@ def _check_dtype_and_dim(self, array: np.ndarray, ndim: int) -> int:
         # 1-D arrays can be numeric or text, 2-D arrays can only be numeric.
         valid_dtypes = DTYPES if ndim == 1 else DTYPES_NUMERIC
         if (dtype := array.dtype.type) not in valid_dtypes:
-            msg = f"Unsupported numpy data type '{dtype}'."
-            raise GMTInvalidInput(msg)
+            raise GMTTypeError(dtype)
         return self[DTYPES[dtype]]
 
     def put_vector(
@@ -1871,8 +1873,10 @@ def virtualfile_in(  # noqa: PLR0912
             elif check_kind == "vector":
                 valid_kinds += ("empty", "matrix", "vectors", "geojson")
             if kind not in valid_kinds:
-                msg = f"Unrecognized data type for {check_kind}: {type(data)}."
-                raise GMTInvalidInput(msg)
+                raise GMTTypeError(
+                    type(data),
+                    reason=f"Unrecognized data type for {check_kind!r} kind.",
+                )
 
         # Decide which virtualfile_from_ function to use
         _virtualfile_from = {

pygmt/exceptions.py

@@ -115,3 +115,18 @@ def __init__(
         if reason:
             msg += f" {reason}"
         super().__init__(msg)
+
+
+class GMTTypeError(GMTError, TypeError):
+    """
+    Raised when an invalid type is passed to a function/method.
+
+    This exception is used to indicate that the type of an argument does not match
+    the expected type.
+    """
+
+    def __init__(self, dtype: object, /, reason: str | None = None):
+        msg = f"Unrecognized data type: {dtype!r}."
+        if reason:
+            msg += f" {reason}"
+        super().__init__(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, GMTValueError
+from pygmt.exceptions import GMTTypeError, GMTValueError
 from pygmt.helpers import (
     build_arg_list,
     data_kind,
@@ -122,8 +122,7 @@ def grdcut(
         case "file":
             outkind = kind
         case _:
-            msg = f"Unsupported data type {type(grid)}."
-            raise GMTInvalidInput(msg)
+            raise GMTTypeError(type(grid))
 
     with Session() as lib:
         with (

pygmt/src/legend.py

@@ -6,7 +6,7 @@
 
 from pygmt._typing import PathLike
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTTypeError
 from pygmt.helpers import (
     build_arg_list,
     data_kind,
@@ -91,11 +91,11 @@ def legend(
 
     kind = data_kind(spec)
     if kind not in {"empty", "file", "stringio"}:
-        msg = f"Unrecognized data type: {type(spec)}"
-        raise GMTInvalidInput(msg)
+        raise GMTTypeError(type(spec))
     if kind == "file" and is_nonstr_iter(spec):
-        msg = "Only one legend specification file is allowed."
-        raise GMTInvalidInput(msg)
+        raise GMTTypeError(
+            type(spec), reason="Only one legend specification file is allowed."
+        )
 
     with Session() as lib:
         with lib.virtualfile_in(data=spec, required=False) as vintbl:

pygmt/src/plot.py

@@ -6,7 +6,7 @@
 
 from pygmt._typing import PathLike, TableLike
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTInvalidInput, GMTTypeError
 from pygmt.helpers import (
     build_arg_list,
     data_kind,
@@ -272,8 +272,10 @@ def plot(  # noqa: PLR0912
             ("symbol", symbol),
         ]:
             if is_nonstr_iter(value):
-                msg = f"'{name}' can't be a 1-D array if 'data' is used."
-                raise GMTInvalidInput(msg)
+                raise GMTTypeError(
+                    type(value),
+                    reason=f"Parameter {name!r} can't be a 1-D array if 'data' is used.",
+                )
 
     # Set the default style if data has a geometry of Point or MultiPoint
     if kwargs.get("S") is None and _data_geometry_is_point(data, kind):

pygmt/src/plot3d.py

@@ -6,7 +6,7 @@
 
 from pygmt._typing import PathLike, TableLike
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTInvalidInput, GMTTypeError
 from pygmt.helpers import (
     build_arg_list,
     data_kind,
@@ -251,8 +251,10 @@ def plot3d(  # noqa: PLR0912
             ("symbol", symbol),
         ]:
             if is_nonstr_iter(value):
-                msg = f"'{name}' can't be a 1-D array if 'data' is used."
-                raise GMTInvalidInput(msg)
+                raise GMTTypeError(
+                    type(value),
+                    reason=f"Parameter {name!r} can't be a 1-D array if 'data' is used.",
+                )
 
     # Set the default style if data has a geometry of Point or MultiPoint
     if kwargs.get("S") is None and _data_geometry_is_point(data, kind):

pygmt/src/text.py

@@ -7,7 +7,7 @@
 import numpy as np
 from pygmt._typing import AnchorCode, PathLike, StringArrayTypes, TableLike
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTInvalidInput, GMTTypeError
 from pygmt.helpers import (
     _check_encoding,
     build_arg_list,
@@ -257,8 +257,10 @@ def text_(  # noqa: PLR0912
 
         for arg, _, name in [*array_args, (kwargs.get("t"), "", "transparency")]:
             if is_nonstr_iter(arg):
-                msg = f"Argument of '{name}' must be a single value or True."
-                raise GMTInvalidInput(msg)
+                raise GMTTypeError(
+                    type(arg),
+                    reason=f"Parameter {name!r} expects a single value or True.",
+                )
 
     with Session() as lib:
         with lib.virtualfile_in(

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
+from pygmt.exceptions import GMTInvalidInput, GMTTypeError
 from pygmt.helpers import (
     build_arg_list,
     fmt_docstring,
@@ -248,11 +248,13 @@ def velo(self, data: PathLike | TableLike | None = None, **kwargs):
         raise GMTInvalidInput(msg)
 
     if isinstance(data, np.ndarray) and not pd.api.types.is_numeric_dtype(data):
-        msg = (
-            "Text columns are not supported with numpy.ndarray type inputs. "
-            "They are only supported with file or pandas.DataFrame inputs."
+        raise GMTTypeError(
+            type(data),
+            reason=(
+                "Text columns are not supported with numpy.ndarray type inputs. "
+                "They are only supported with file or pandas.DataFrame inputs."
+            ),
         )
-        raise GMTInvalidInput(msg)
 
     with Session() as lib:
         with lib.virtualfile_in(check_kind="vector", data=data) as vintbl:

pygmt/src/x2sys_cross.py

@@ -10,7 +10,7 @@
 import pandas as pd
 from pygmt._typing import PathLike
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTTypeError
 from pygmt.helpers import (
     build_arg_list,
     data_kind,
@@ -213,8 +213,7 @@ def x2sys_cross(
                 # Save pandas.DataFrame track data to temporary file
                 file_contexts.append(tempfile_from_dftrack(track=track, suffix=suffix))
             case _:
-                msg = f"Unrecognized data type: {type(track)}."
-                raise GMTInvalidInput(msg)
+                raise GMTTypeError(type(track))
 
     with Session() as lib:
         with lib.virtualfile_out(kind="dataset", fname=outfile) as vouttbl: