BREAKING: Raise GMTParameterError exception for conflicts_with parameters. Previously raise GMTInvalidInput

pygmt/exceptions.py

@@ -145,6 +145,9 @@ class GMTParameterError(GMTError):
     at_most_one
        A set of mutually exclusive parameter names, of which at most one can be
        specified.
+    conflicts_with
+       A dictionary mapping parameter names to sets of conflicting parameter
+       names. Used to indicate which parameters cannot be used together.
     reason
         Detailed reason why the parameters are invalid.
     """
@@ -155,6 +158,7 @@ def __init__(
         required: str | set[str] | None = None,
         at_least_one: set[str] | None = None,
         at_most_one: set[str] | None = None,
+        conflicts_with: dict[str, set[str]] | None = None,
         reason: str | None = None,
     ):
         msg = []
@@ -177,6 +181,12 @@ def __init__(
                 f"{', '.join(repr(par) for par in at_most_one)}. "
                 "Specify at most one of them."
             )
+        if conflicts_with:
+            for param, conflicts in conflicts_with.items():
+                msg.append(
+                    f"Conflicting parameters: {param!r} cannot be used with "
+                    f"{', '.join(repr(c) for c in sorted(conflicts))}."
+                )
         if reason:
             msg.append(reason)
         super().__init__(" ".join(msg))

pygmt/src/_common.py

@@ -7,7 +7,7 @@
 from pathlib import Path
 from typing import Any, ClassVar, Literal
 
-from pygmt.exceptions import GMTInvalidInput, GMTTypeError, GMTValueError
+from pygmt.exceptions import GMTParameterError, GMTTypeError, GMTValueError
 from pygmt.params.position import Position
 from pygmt.src.which import which
 
@@ -328,7 +328,7 @@ def _parse_position(
     ... )
     Traceback (most recent call last):
         ...
-    pygmt.exceptions.GMTInvalidInput: Parameter 'position' is given with a raw GMT...
+    pygmt.exceptions.GMTParameterError: ...
 
     >>> _parse_position(
     ...     123,
@@ -364,12 +364,10 @@ def _parse_position(
                 position = Position(position, cstype="inside")
             elif kwdict is not None:  # Raw GMT command string with potential conflicts.
                 if any(v is not None and v is not False for v in kwdict.values()):
-                    msg = (
-                        "Parameter 'position' is given with a raw GMT command string, "
-                        "and conflicts with parameters "
-                        f"{', '.join(repr(c) for c in kwdict)}."
+                    raise GMTParameterError(
+                        conflicts_with={"position": set(kwdict.keys())},
+                        reason="Parameter 'position' is given with a raw GMT command string",
                     )
-                    raise GMTInvalidInput(msg)
             else:
                 # No conflicting parameters to check, indicating it's a new function.
                 # The string must be an anchor code.

pygmt/src/grdview.py

@@ -10,7 +10,7 @@
 from pygmt._typing import PathLike
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session, __gmt_version__
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTInvalidInput, GMTParameterError
 from pygmt.helpers import build_arg_list, deprecate_parameter, fmt_docstring, use_alias
 from pygmt.src.grdinfo import grdinfo
 
@@ -71,11 +71,12 @@ def _alias_option_Q(  # noqa: N802
         v is not None and v is not False
         for v in (dpi, mesh_fill, monochrome, nan_transparent)
     ):
-        msg = (
-            "Parameter 'surftype' is given with a raw GMT command string, and conflicts "
-            "with parameters 'dpi', 'mesh_fill', 'monochrome', or 'nan_transparent'."
+        raise GMTParameterError(
+            conflicts_with={
+                "surftype": {"dpi", "mesh_fill", "monochrome", "nan_transparent"}
+            },
+            reason="Parameter 'surftype' is given with a raw GMT command string",
         )
-        raise GMTInvalidInput(msg)
 
     if dpi is not None and surftype != "image":
         msg = "Parameter 'dpi' can only be used when 'surftype' is 'image'."

pygmt/tests/test_colorbar.py

@@ -4,7 +4,7 @@
 
 import pytest
 from pygmt import Figure
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTParameterError
 from pygmt.params.position import Position
 
 
@@ -50,21 +50,21 @@ def test_image_position_mixed_syntax():
     Test that mixing deprecated GMT CLI syntax string with new parameters.
     """
     fig = Figure()
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.colorbar(cmap="gmt/rainbow", position="x0/0", length="4c")
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.colorbar(cmap="gmt/rainbow", position="x0/0", width="0.5c")
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.colorbar(cmap="gmt/rainbow", position="x0/0", orientation="horizontal")
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.colorbar(cmap="gmt/rainbow", position="x0/0", reverse=True)
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.colorbar(cmap="gmt/rainbow", position="x0/0", nan=True)
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.colorbar(
             cmap="gmt/rainbow", position="x0/0", fg_triangle=True, bg_triangle=True
         )
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.colorbar(cmap="gmt/rainbow", position="x0/0", move_text="label")
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.colorbar(cmap="gmt/rainbow", position="x0/0", label_as_column=True)

pygmt/tests/test_grdview.py

@@ -4,7 +4,7 @@
 
 import pytest
 from pygmt import Figure, grdcut
-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
 
@@ -343,13 +343,13 @@ def test_grdview_mixed_syntax(gridfile):
     Run grdview using grid as a file and drapegrid as an xarray.DataArray.
     """
     fig = Figure()
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.grdview(grid=gridfile, cmap="SCM/oleron", surftype="i", dpi=300)
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.grdview(grid=gridfile, cmap="SCM/oleron", surftype="m", mesh_fill="red")
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.grdview(grid=gridfile, cmap="SCM/oleron", surftype="s", monochrome=True)
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.grdview(
             grid=gridfile, cmap="SCM/oleron", surftype="i", nan_transparent=True
         )

pygmt/tests/test_image.py

@@ -4,7 +4,7 @@
 
 import pytest
 from pygmt import Figure
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTParameterError
 from pygmt.params import Box, Position
 
 
@@ -66,11 +66,11 @@ def test_image_position_mixed_syntax():
     and conflicts with other parameters.
     """
     fig = Figure()
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.image(imagefile="@circuit.png", position="x0/0", width="4c")
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.image(imagefile="@circuit.png", position="x0/0", height="3c")
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.image(imagefile="@circuit.png", position="x0/0", dpi="300")
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.image(imagefile="@circuit.png", position="x0/0", replicate=(2, 1))

pygmt/tests/test_inset.py

@@ -4,7 +4,7 @@
 
 import pytest
 from pygmt import Figure
-from pygmt.exceptions import GMTInvalidInput, GMTParameterError
+from pygmt.exceptions import GMTParameterError
 from pygmt.params import Box, Position
 
 
@@ -94,6 +94,6 @@ def test_inset_invalid_inputs():
         with fig.inset(position=Position("TL"), height="5c"):
             pass
     # Old position syntax conflicts with width/height
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         with fig.inset(position="jTL+w3.5c", width="3.5c"):
             pass

pygmt/tests/test_legend.py

@@ -7,7 +7,7 @@
 
 import pytest
 from pygmt import Figure
-from pygmt.exceptions import GMTInvalidInput, GMTTypeError
+from pygmt.exceptions import GMTParameterError, GMTTypeError
 from pygmt.helpers import GMTTempFile
 
 
@@ -174,9 +174,9 @@ def test_legend_position_mixed_syntax(legend_spec):
     spec = io.StringIO(legend_spec)
     fig = Figure()
     fig.basemap(projection="x6i", region=[0, 1, 0, 1], frame=True)
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.legend(spec, position="jTL", width="5i")
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.legend(spec, position="jTL", height="5i")
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.legend(spec, position="jTL", line_spacing=2.0)

pygmt/tests/test_logo.py

@@ -4,7 +4,7 @@
 
 import pytest
 from pygmt import Figure
-from pygmt.exceptions import GMTInvalidInput, GMTParameterError
+from pygmt.exceptions import GMTParameterError
 from pygmt.params import Position
 
 
@@ -66,7 +66,7 @@ def test_logo_position_mixed_syntax():
     Test that an error is raised when mixing new and deprecated syntax in 'position'.
     """
     fig = Figure()
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.logo(position="jTL", width="5c")
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.logo(position="jTL", height="6c")

pygmt/tests/test_wiggle.py

@@ -5,7 +5,7 @@
 import numpy as np
 import pytest
 from pygmt import Figure
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTParameterError
 from pygmt.params import Position
 
 
@@ -136,11 +136,11 @@ def test_wiggle_mixed_syntax(data):
         "pen": "1.0p",
         "track": "0.5p",
     }
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.wiggle(position="jMR+w2+lnT", length=2, **kwargs)
 
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         fig.wiggle(position="jMR+w2+lnT", label="nT", **kwargs)
 
-    with pytest.raises(GMTInvalidInput):
-        fig.wiggle(position="jMR+w2+lnT", length_alignment="left", **kwargs)
+    with pytest.raises(GMTParameterError):
+        fig.wiggle(position="jMR+w2+lnT", label_alignment="left", **kwargs)