Add new exception GMTParameterError for missing required parameters

Author: seisman

doc/api/index.rst

@@ -286,7 +286,7 @@ All custom exceptions are derived from :class:`pygmt.exceptions.GMTError`.
     exceptions.GMTTypeError
     exceptions.GMTValueError
     exceptions.GMTTypeError
-
+    exceptions.GMTParameterError
 
 .. currentmodule:: pygmt
 

pygmt/exceptions.py

@@ -4,7 +4,7 @@
 All exceptions derive from GMTError.
 """
 
-from collections.abc import Iterable
+from collections.abc import Iterable, Set
 from typing import Any
 
 
@@ -130,3 +130,40 @@ def __init__(self, dtype: object, /, reason: str | None = None):
         if reason:
             msg += f" {reason}"
         super().__init__(msg)
+
+
+class GMTParameterError(GMTError):
+    """
+    Raised when parameters are missing or invalid.
+
+    Parameters
+    ----------
+    required
+        Names of required parameters.
+    exclusive
+        Names of mutually exclusive parameters.
+    reason
+        Detailed reason why the parameters are invalid.
+    """
+
+    def __init__(
+        self,
+        *,
+        required: Set[str] | None = None,
+        exclusive: Set[str] | None = None,
+        reason: str | None = None,
+    ):
+        msg = ""
+        if required:
+            msg = (
+                "Required parameter(s) are missing: "
+                f"{', '.join(repr(par) for par in required)}."
+            )
+        if exclusive:
+            msg = (
+                "Mutually exclusive parameter(s) are specified: "
+                f"{', '.join(repr(par) for par in exclusive)}."
+            )
+        if reason:
+            msg += f" {reason}"
+        super().__init__(msg)