_parse_position: Refactor for new functions that do no need to check conflicting parameters (#4360)

Author: seisman

pygmt/src/_common.py

@@ -248,8 +248,8 @@ def from_params(
 
 def _parse_position(
     position: Position | Sequence[float | str] | str | None,
-    kwdict: dict[str, Any],
-    default: Position | None,
+    default: Position | None = None,
+    kwdict: dict[str, Any] | None = None,
 ) -> Position | str | None:
     """
     Parse the "position" parameter for embellishment-plotting functions.
@@ -264,12 +264,14 @@ def _parse_position(
         - A 2-character justification code
         - A raw GMT command string (for backward compatibility)
         - ``None``, in which case the default position is used
-    kwdict
-        The keyword arguments dictionary that conflicts with ``position`` if
-        ``position`` is given as a raw GMT command string.
     default
         The default Position object to use if ``position`` is ``None``. If ``default``
         is ``None``, use the GMT default.
+    kwdict
+        The keyword arguments dictionary that conflicts with ``position`` if
+        ``position`` is given as a raw GMT command string. This is used for backward
+        compatibility to raise an exception if there are conflicting parameters. If
+        ``kwdict`` is ``None``, no conflict checking is performed (for new functions).
 
     Returns
     -------
@@ -281,76 +283,104 @@ def _parse_position(
     >>> from pygmt.params import Position
     >>> _parse_position(
     ...     Position((3, 3), cstype="mapcoords"),
-    ...     kwdict={"width": None, "height": None},
     ...     default=Position((0, 0), cstype="plotcoords"),
+    ...     kwdict={"width": None, "height": None},
     ... )
     Position(refpoint=(3, 3), cstype='mapcoords')
 
     >>> _parse_position(
     ...     (3, 3),
-    ...     kwdict={"width": None, "height": None},
     ...     default=Position((0, 0), cstype="plotcoords"),
+    ...     kwdict={"width": None, "height": None},
     ... )
     Position(refpoint=(3, 3), cstype='plotcoords')
     >>> _parse_position(
     ...     "TL",
-    ...     kwdict={"width": None, "height": None},
     ...     default=Position((0, 0), cstype="plotcoords"),
+    ...     kwdict={"width": None, "height": None},
     ... )
     Position(refpoint='TL', cstype='inside')
 
     >>> _parse_position(
     ...     None,
-    ...     kwdict={"width": None, "height": None},
     ...     default=Position((0, 0), cstype="plotcoords"),
+    ...     kwdict={"width": None, "height": None},
     ... )
     Position(refpoint=(0, 0), cstype='plotcoords')
 
     >>> _parse_position(
     ...     None,
-    ...     kwdict={"width": None, "height": None},
     ...     default=None,
+    ...     kwdict={"width": None, "height": None},
     ... )
 
     >>> _parse_position(
     ...     "x3c/4c+w2c",
-    ...     kwdict={"width": None, "height": None},
     ...     default=Position((0, 0), cstype="plotcoords"),
+    ...     kwdict={"width": None, "height": None},
     ... )
     'x3c/4c+w2c'
 
     >>> _parse_position(
     ...     "x3c/4c+w2c",
-    ...     kwdict={"width": 2, "height": None},
     ...     default=Position((0, 0), cstype="plotcoords"),
+    ...     kwdict={"width": 2, "height": None},
     ... )
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Parameter 'position' is given with a raw GMT...
 
     >>> _parse_position(
     ...     123,
-    ...     kwdict={"width": None, "height": None},
     ...     default=Position((0, 0), cstype="plotcoords"),
+    ...     kwdict={"width": None, "height": None},
     ... )
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Invalid type for parameter 'position':...
+
+    >>> # Below are examples without kwdict (for new functions).
+    >>> _parse_position(
+    ...     "BL",
+    ...     default=Position((0, 0), cstype="plotcoords"),
+    ... )
+    Position(refpoint='BL', cstype='inside')
+
+    >>> _parse_position(
+    ...     "invalid",
+    ...     default=Position((0, 0), cstype="plotcoords"),
+    ... )
+    Traceback (most recent call last):
+        ...
+    pygmt.exceptions.GMTValueError: Invalid position: 'invalid'...
     """
 
     _valid_anchors = {f"{h}{v}" for v in "TMB" for h in "LCR"} | {
         f"{v}{h}" for v in "TMB" for h in "LCR"
     }
     match position:
-        case str() if position in _valid_anchors:  # Anchor code
-            position = Position(position, cstype="inside")
-        case str():  # Raw GMT command string.
-            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 "
-                    f"conflicts with parameters {', '.join(repr(c) for c in kwdict)}."
+        case str():  # String for anchor code or raw GMT command.
+            if position in _valid_anchors:  # Anchor code
+                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 GMTInvalidInput(msg)
+            else:
+                # No conflicting parameters to check, indicating it's a new function.
+                # The string must be an anchor code.
+                raise GMTValueError(
+                    position,
+                    description="position",
+                    reason=(
+                        "Parameter 'position' must be a two-character anchor code, "
+                        "a coordinate, or a Position object."
+                    ),
                 )
-                raise GMTInvalidInput(msg)
         case Sequence() if len(position) == 2:  # A sequence of x and y coordinates.
             position = Position(position, cstype="plotcoords")
         case Position():  # Already a Position object.

pygmt/src/colorbar.py

@@ -296,6 +296,7 @@ def colorbar(  # noqa: PLR0913
 
     position = _parse_position(
         position,
+        default=None,  # Use GMT's default behavior if position is not provided.
         kwdict={
             "length": length,
             "width": width,
@@ -309,7 +310,6 @@ def colorbar(  # noqa: PLR0913
             "move_text": move_text,
             "label_as_column": label_as_column,
         },
-        default=None,  # Use GMT's default behavior if position is not provided.
     )
 
     aliasdict = AliasSystem(

pygmt/src/image.py

@@ -136,8 +136,8 @@ def image(  # noqa: PLR0913
 
     position = _parse_position(
         position,
-        kwdict={"width": width, "height": height, "dpi": dpi, "replicate": replicate},
         default=Position((0, 0), cstype="plotcoords"),  # Default to (0,0) in plotcoords
+        kwdict={"width": width, "height": height, "dpi": dpi, "replicate": replicate},
     )
 
     # width is required when only height is given.

pygmt/src/inset.py

@@ -129,8 +129,8 @@ def inset(
 
     position = _parse_position(
         position,
-        kwdict={"width": width, "height": height},
         default=Position((0, 0), cstype="plotcoords"),  # Default to (0,0) in plotcoords
+        kwdict={"width": width, "height": height},
     )
 
     # width is mandatory unless both projection and region are given.

pygmt/src/legend.py

@@ -123,8 +123,8 @@ def legend(  # noqa: PLR0913
 
     position = _parse_position(
         position,
-        kwdict={"width": width, "height": height, "line_spacing": line_spacing},
         default=Position("TR", offset=0.2),  # Default to TR with 0.2-cm offset.
+        kwdict={"width": width, "height": height, "line_spacing": line_spacing},
     )
 
     # Set width to 0 (auto calculated) if height is given but width is not.

pygmt/src/logo.py

@@ -99,8 +99,8 @@ def logo(  # noqa: PLR0913
 
     position = _parse_position(
         position,
-        kwdict={"width": width, "height": height},
         default=Position((0, 0), cstype="plotcoords"),  # Default to (0,0) in plotcoords
+        kwdict={"width": width, "height": height},
     )
 
     # width and height are mutually exclusive.

pygmt/src/wiggle.py

@@ -170,8 +170,8 @@ def wiggle(  # noqa: PLR0913
 
     position = _parse_position(
         position,
-        kwdict={"length": length, "label": label, "label_alignment": label_alignment},
         default=Position("BL", offset=0.2),  # Default to BL with 0.2-cm offset.
+        kwdict={"length": length, "label": label, "label_alignment": label_alignment},
     )
 
     _fills = _parse_fills(positive_fill, negative_fill)