Improve error message for recommended long-form parameters

Author: seisman

pygmt/alias.py

@@ -280,23 +280,38 @@ def update(self, kwargs: Mapping[str, Any]):
         for short_param, value in kwargs.items():
             # Long-form parameters exist.
             if aliases := self.aliasdict.get(short_param):
-                long_params = ", ".join(
-                    [repr(alias.name) for alias in aliases]
-                    if isinstance(aliases, Sequence)
-                    else [repr(aliases.name)]
-                )
+                if not isinstance(aliases, Sequence):  # Single Alias object.
+                    _params = repr(aliases.name)
+                    _msg_long_params = f"Use long-form parameter {_params} instead."
+                else:  # Sequence of Alias objects.
+                    _params = ", ".join(
+                        [repr(alias.name) for alias in aliases if not alias.prefix]
+                    )
+                    _modifiers = ", ".join(
+                        [
+                            repr(alias.name) + f" ({alias.prefix})"
+                            for alias in aliases
+                            if alias.prefix
+                        ]
+                    )
+                    _msg_long_params = (
+                        f"Use long-form parameters {_params}, "
+                        f"with optional parameters {_modifiers} instead."
+                    )
+
                 # Long-form parameters are already specified.
                 if short_param in self.kwdict:
                     msg = (
-                        f"Parameter in short-form {short_param!r} conflicts with "
-                        f"long-form parameter {long_params}."
+                        f"Short-form parameter {short_param!r} conflicts with "
+                        "long-form parameters and is not recommended. "
+                        f"{_msg_long_params}"
                     )
                     raise GMTInvalidInput(msg)
 
                 # Long-form parameters are not specified.
                 msg = (
                     f"Short-form parameter {short_param!r} is not recommended. "
-                    f"Use long-form parameter {long_params} instead."
+                    f"{_msg_long_params}"
                 )
                 warnings.warn(msg, category=SyntaxWarning, stacklevel=2)
 

pygmt/tests/test_alias_system.py

@@ -59,7 +59,7 @@ def test_alias_system_one_alias_short_form():
     # Coexistence of long-form and short-form parameters.
     with pytest.raises(
         GMTInvalidInput,
-        match="Parameter in short-form 'J' conflicts with long-form parameter 'projection'.",
+        match="Short-form parameter 'J' conflicts with long-form parameters and is not recommended. Use long-form parameter 'projection' instead.",
     ):
         func(projection="X10c", J="H10c")
 
@@ -70,21 +70,16 @@ def test_alias_system_multiple_aliases_short_form():
     are used.
     """
     # Long-form exists but is not given, and short-form is given.
-    with pytest.warns(
-        SyntaxWarning,
-        match="Short-form parameter 'U' is not recommended. Use long-form parameter 'label', 'text' instead.",
-    ):
+    msg = (
+        r"Short-form parameter 'U' is not recommended. Use long-form parameters 'label', with optional parameters 'text' \(\+t\) instead.",
+    )
+    with pytest.warns(SyntaxWarning, match=msg):
         assert func(U="abcd+tefg") == ["-Uabcd+tefg"]
 
     # Coexistence of long-form and short-form parameters.
-    with pytest.raises(
-        GMTInvalidInput,
-        match="Parameter in short-form 'U' conflicts with long-form parameter 'label', 'text'.",
-    ):
+    msg = r"Short-form parameter 'U' conflicts with long-form parameters and is not recommended. Use long-form parameters 'label', with optional parameters 'text' \(\+t\) instead."
+    with pytest.raises(GMTInvalidInput, match=msg):
         func(label="abcd", U="efg")
 
-    with pytest.raises(
-        GMTInvalidInput,
-        match="Parameter in short-form 'U' conflicts with long-form parameter 'label', 'text'.",
-    ):
+    with pytest.raises(GMTInvalidInput, match=msg):
         func(text="efg", U="efg")