pygmt.project: Migrate the 'center'/'endpoint'/'pole'/'width'/'length' parameters to the new alias system (#4172)

Author: seisman

pygmt/src/project.py

@@ -2,18 +2,18 @@
 project - Project data onto lines or great circles, or generate tracks.
 """
 
+from collections.abc import Sequence
 from typing import Literal
 
 import numpy as np
 import pandas as pd
 from pygmt._typing import PathLike, TableLike
-from pygmt.alias import AliasSystem
+from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import (
     build_arg_list,
     fmt_docstring,
-    kwargs_to_strings,
     use_alias,
     validate_output_table_type,
 )
@@ -22,27 +22,26 @@
 @fmt_docstring
 @use_alias(
     A="azimuth",
-    C="center",
-    E="endpoint",
     F="convention",
     G="generate",
-    L="length",
     N="flat_earth",
     Q="unit",
     S="sort",
-    T="pole",
-    W="width",
     Z="ellipse",
     f="coltypes",
 )
-@kwargs_to_strings(E="sequence", L="sequence", T="sequence", W="sequence", C="sequence")
-def project(
+def project(  # noqa: PLR0913
     data: PathLike | TableLike | None = None,
     x=None,
     y=None,
     z=None,
     output_type: Literal["pandas", "numpy", "file"] = "pandas",
     outfile: PathLike | None = None,
+    center: Sequence[float | str] | None = None,
+    endpoint: Sequence[float | str] | None = None,
+    width: Sequence[float | str] | None = None,
+    length: Sequence[float | str] | Literal["limit"] | None = None,
+    pole: Sequence[float | str] | None = None,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     **kwargs,
@@ -112,6 +111,11 @@ def project(
     Full GMT docs at :gmt-docs:`project.html`.
 
     {aliases}
+       - C = center
+       - E = endpoint
+       - L = length
+       - T = pole
+       - W = width
        - V = verbose
 
     Parameters
@@ -123,19 +127,17 @@ def project(
     {output_type}
     {outfile}
 
-    center : str or list
-        *cx*/*cy*.
-        Set the origin of the projection, in Definition 1 or 2. If
-        Definition 3 is used, then *cx/cy* are the coordinates of a
-        point through which the oblique zero meridian (:math:`p = 0`) should
-        pass. The *cx/cy* is not required to be 90 degrees from the pole.
-
+    center
+        Set the origin of the projection, in the form of (*cx*, *cy*), in Definitions 1
+        or 2. If Definition 3 is used, then (*cx*, *cy*) are the coordinates of a point
+        through which the oblique zero meridian (:math:`p = 0`) should pass.
+        (*cx*, *cy*) is not required to be 90 degrees from the pole set by ``pole``.
     azimuth : float or str
         Define the azimuth of the projection (Definition 1).
 
-    endpoint : str or list
-        *bx*/*by*.
-        Define the end point of the projection path (Definition 2).
+    endpoint
+        (*bx*, *by*).
+        Set the end point of the projection path (Definition 2).
 
     convention : str
         Specify the desired output using any combination of **xyzpqrs**, in
@@ -162,14 +164,12 @@ def project(
         the pole as part of the segment header [Default is no header].
         **Note**: No input is read and the value of ``data``, ``x``, ``y``,
         and ``z`` is ignored if ``generate`` is used.
-
-    length : str or list
-        [**w**\|\ *l_min*/*l_max*].
-        Project only those data whose *p* coordinate is
-        within :math:`l_{{min}} < p < l_{{max}}`. If ``endpoint`` has been set,
-        then you may alternatively use **w** to stay within the distance from
-        ``center`` to ``endpoint``.
-
+    length
+        (*lmin*, *lmax*) or ``"limit"``.
+        Project only those data whose *p* coordinate is within
+        :math:`l_{{min}} < p < l_{{max}}`. If ``endpoint`` has been set, then you may
+        alternatively set it to ``"limit"`` to stay within the distance from ``center``
+        to ``endpoint``.
     flat_earth : bool
         Make a Cartesian coordinate transformation in the plane.
         [Default is ``False``; plane created with spherical trigonometry.]
@@ -182,18 +182,13 @@ def project(
     sort : bool
         Sort the output into increasing :math:`p` order. Useful when projecting
         random data into a sequential profile.
-
-    pole : str or list
-        *px*/*py*.
-        Set the position of the rotation pole of the projection.
-        (Definition 3).
-
-    {verbose}
-
-    width : str or list
-        *w_min*/*w_max*.
-        Project only those data whose :math:`q` coordinate is
-        within :math:`w_{{min}} < q < w_{{max}}`.
+    pole
+        (*px*, *py*).
+        Set the position of the rotation pole of the projection. (Definition 3).
+    width
+        (*w_min*, *w_max*).
+        Specify width controls for the projected points. Project only those points whose
+        q coordinate is within :math:`w_{{min}} < q < w_{{max}}`.
 
     ellipse : str
         *major*/*minor*/*azimuth* [**+e**\|\ **n**].
@@ -212,7 +207,7 @@ def project(
         For the Cartesian ellipse (which requires ``flat_earth``), the
         *direction* is counter-clockwise from the horizontal instead of an
         *azimuth*.
-
+    {verbose}
     {coltypes}
 
     Returns
@@ -225,8 +220,8 @@ def project(
         - :class:`pandas.DataFrame` or :class:`numpy.ndarray` if ``outfile`` is not set
           (depends on ``output_type``)
     """
-    if kwargs.get("C") is None:
-        msg = "The 'center' parameter must be specified."
+    if kwargs.get("C", center) is None:
+        msg = "Parameter 'center' must be specified."
         raise GMTInvalidInput(msg)
     if kwargs.get("G") is None and data is None:
         msg = "The 'data' parameter must be specified unless 'generate' is used."
@@ -241,7 +236,13 @@ def project(
     if output_type == "pandas" and kwargs.get("G") is not None:
         column_names = list("rsp")
 
-    aliasdict = AliasSystem().add_common(
+    aliasdict = AliasSystem(
+        C=Alias(center, name="center", sep="/", size=2),
+        E=Alias(endpoint, name="endpoint", sep="/", size=2),
+        L=Alias(length, name="length", sep="/", size=2, mapping={"limit": "w"}),
+        T=Alias(pole, name="pole", sep="/", size=2),
+        W=Alias(width, name="width", sep="/", size=2),
+    ).add_common(
         V=verbose,
     )
     aliasdict.merge(kwargs)