sequence_join/_to_string/Alias: Deprecate parameter 'separator', use 'sep' instead. [Will be removed in v0.19.0] (#4033)

Author: seisman

pygmt/alias.py

@@ -15,7 +15,7 @@ def _to_string(
     value: Any,
     prefix: str = "",  # Default to an empty string to simplify the code logic.
     mapping: Mapping | None = None,
-    separator: Literal["/", ","] | None = None,
+    sep: Literal["/", ","] | None = None,
     size: int | Sequence[int] | None = None,
     ndim: int = 1,
     name: str | None = None,
@@ -41,8 +41,8 @@ def _to_string(
     string.
 
     To avoid extra overhead, this function does not validate parameter combinations. For
-    example, if ``value`` is a sequence but ``separator`` is not specified, the function
-    will return a sequence of strings. In this case, ``prefix`` has no effect, but the
+    example, if ``value`` is a sequence but ``sep`` is not specified, the function will
+    return a sequence of strings. In this case, ``prefix`` has no effect, but the
     function does not check for such inconsistencies. The maintainer should ensure that
     the parameter combinations are valid.
 
@@ -54,7 +54,7 @@ def _to_string(
         The string to add as a prefix to the returned value.
     mapping
         A mapping dictionary to map PyGMT's long-form arguments to GMT's short-form.
-    separator
+    sep
         The separator to use if the value is a sequence.
     size
         Expected size of the 1-D sequence. It can be either an integer or a sequence of
@@ -97,17 +97,17 @@ def _to_string(
     ...
     pygmt...GMTValueError: Invalid value: 'invalid'. Expected one of: 'mean', ...
 
-    >>> _to_string((12, 34), separator="/")
+    >>> _to_string((12, 34), sep="/")
     '12/34'
-    >>> _to_string(("12p", "34p"), separator=",")
+    >>> _to_string(("12p", "34p"), sep=",")
     '12p,34p'
-    >>> _to_string(("12p", "34p"), prefix="+o", separator="/")
+    >>> _to_string(("12p", "34p"), prefix="+o", sep="/")
     '+o12p/34p'
 
     >>> _to_string(["xaf", "yaf", "WSen"])
     ['xaf', 'yaf', 'WSen']
 
-    >>> _to_string([[1, 2], [3, 4]], separator="/", ndim=2)
+    >>> _to_string([[1, 2], [3, 4]], sep="/", ndim=2)
     ['1/2', '3/4']
     """
     # None and False are converted to None.
@@ -130,11 +130,11 @@ def _to_string(
 
     # Return the sequence if separator is not specified for options like '-B'.
     # True in a sequence will be converted to an empty string.
-    if separator is None:
+    if sep is None:
         return [str(item) if item is not True else "" for item in value]
     # Join the sequence of values with the separator.
     # "prefix" and "mapping" are ignored. We can enable them when needed.
-    _value = sequence_join(value, separator=separator, size=size, ndim=ndim, name=name)
+    _value = sequence_join(value, sep=sep, size=size, ndim=ndim, name=name)
     return _value if is_nonstr_iter(_value) else f"{prefix}{_value}"
 
 
@@ -152,7 +152,7 @@ class Alias:
         The string to add as a prefix to the returned value.
     mapping
         A mapping dictionary to map PyGMT's long-form arguments to GMT's short-form.
-    separator
+    sep
         The separator to use if the value is a sequence.
     size
         Expected size of the 1-D sequence. It can be either an integer or a sequence
@@ -163,7 +163,7 @@ class Alias:
 
     Examples
     --------
-    >>> par = Alias((3.0, 3.0), prefix="+o", separator="/")
+    >>> par = Alias((3.0, 3.0), prefix="+o", sep="/")
     >>> par._value
     '+o3.0/3.0'
 
@@ -182,7 +182,7 @@ def __init__(
         name: str | None = None,
         prefix: str = "",
         mapping: Mapping | None = None,
-        separator: Literal["/", ","] | None = None,
+        sep: Literal["/", ","] | None = None,
         size: int | Sequence[int] | None = None,
         ndim: int = 1,
     ):
@@ -193,7 +193,7 @@ def __init__(
             name=name,
             prefix=prefix,
             mapping=mapping,
-            separator=separator,
+            sep=sep,
             size=size,
             ndim=ndim,
         )
@@ -222,11 +222,11 @@ class AliasSystem(UserDict):
     ...     aliasdict = AliasSystem(
     ...         A=[
     ...             Alias(par1, name="par1"),
-    ...             Alias(par2, name="par2", prefix="+o", separator="/"),
+    ...             Alias(par2, name="par2", prefix="+o", sep="/"),
     ...         ],
     ...         B=Alias(frame, name="frame"),
     ...         D=Alias(repeat, name="repeat"),
-    ...         c=Alias(panel, name="panel", separator=","),
+    ...         c=Alias(panel, name="panel", sep=","),
     ...     ).merge(kwargs)
     ...     return build_arg_list(aliasdict)
     >>> func(

pygmt/helpers/utils.py

@@ -9,6 +9,7 @@
 import subprocess
 import sys
 import time
+import warnings
 import webbrowser
 from collections.abc import Iterable, Mapping, Sequence
 from itertools import islice
@@ -724,9 +725,11 @@ def args_in_kwargs(args: Sequence[str], kwargs: dict[str, Any]) -> bool:
     )
 
 
+# TODO(PyGMT>=0.19.0): Remove the deprecate_parameter decorator.
 def sequence_join(
     value: Any,
-    separator: str = "/",
+    sep: str = "/",
+    separator: str | None = None,
     size: int | Sequence[int] | None = None,
     ndim: int = 1,
     name: str | None = None,
@@ -741,8 +744,14 @@ def sequence_join(
     ----------
     value
         The 1-D or 2-D sequence of values to join.
+    sep
+        The separator to join the values.
     separator
         The separator to join the values.
+
+        .. versionchanged:: v0.17.0
+
+            Deprecated and will be removed in v0.19.0. Use ``sep`` instead.
     size
         Expected size of the 1-D sequence. It can be either an integer or a sequence of
         integers. If an integer, it is the expected size of the 1-D sequence. If it is a
@@ -774,43 +783,53 @@ def sequence_join(
 
     >>> sequence_join([1, 2, 3, 4])
     '1/2/3/4'
-    >>> sequence_join([1, 2, 3, 4], separator=",")
+    >>> sequence_join([1, 2, 3, 4], sep=",")
     '1,2,3,4'
-    >>> sequence_join([1, 2, 3, 4], separator="/", size=4)
+    >>> sequence_join([1, 2, 3, 4], sep="/", size=4)
     '1/2/3/4'
-    >>> sequence_join([1, 2, 3, 4], separator="/", size=[2, 4])
+    >>> sequence_join([1, 2, 3, 4], sep="/", size=[2, 4])
     '1/2/3/4'
-    >>> sequence_join([1, 2, 3, 4], separator="/", size=[2, 4], ndim=2)
+    >>> sequence_join([1, 2, 3, 4], sep="/", size=[2, 4], ndim=2)
     '1/2/3/4'
-    >>> sequence_join([1, 2, 3, 4], separator="/", size=2)
+    >>> sequence_join([1, 2, 3, 4], sep="/", size=2)
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Expected a sequence of 2 values, but got 4 values.
-    >>> sequence_join([1, 2, 3, 4, 5], separator="/", size=[2, 4], name="parname")
+    >>> sequence_join([1, 2, 3, 4, 5], sep="/", size=[2, 4], name="parname")
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Parameter 'parname': Expected ...
 
-    >>> sequence_join([[1, 2], [3, 4]], separator="/")
+    >>> sequence_join([[1, 2], [3, 4]], sep="/")
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Expected a 1-D ..., but a 2-D sequence is given.
-    >>> sequence_join([[1, 2], [3, 4]], separator="/", ndim=2)
+    >>> sequence_join([[1, 2], [3, 4]], sep="/", ndim=2)
     ['1/2', '3/4']
-    >>> sequence_join([[1, 2], [3, 4]], separator="/", size=2, ndim=2)
+    >>> sequence_join([[1, 2], [3, 4]], sep="/", size=2, ndim=2)
     ['1/2', '3/4']
-    >>> sequence_join([[1, 2], [3, 4]], separator="/", size=4, ndim=2)
+    >>> sequence_join([[1, 2], [3, 4]], sep="/", size=4, ndim=2)
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Expected a sequence of 4 values.
-    >>> sequence_join([[1, 2], [3, 4]], separator="/", size=[2, 4], ndim=2)
+    >>> sequence_join([[1, 2], [3, 4]], sep="/", size=[2, 4], ndim=2)
     ['1/2', '3/4']
+    >>> sequence_join([1, 2, 3, 4], separator=",")
+    '1,2,3,4'
     """
     # Return the original value if it is not a sequence (e.g., None, bool, or str).
     if not is_nonstr_iter(value):
         return value
     # Now it must be a sequence.
 
+    if separator is not None:
+        sep = separator  # Deprecated, use sep instead.
+        msg = (
+            "Parameter 'separator' has been deprecated since v0.17.0 and will be "
+            "removed in v0.19.0. Please use 'sep' instead."
+        )
+        warnings.warn(msg, category=FutureWarning, stacklevel=2)
+
     # Change size to a list to simplify the checks.
     size = [size] if isinstance(size, int) else size
     errmsg = {
@@ -829,7 +848,7 @@ def sequence_join(
                 f"but got {len(value)} values."
             )
             raise GMTInvalidInput(msg)
-        return separator.join(str(v) for v in value)
+        return sep.join(str(v) for v in value)
 
     # Now it must be a 2-D sequence.
     if ndim == 1:
@@ -838,4 +857,4 @@ def sequence_join(
     if size is not None and any(len(i) not in size for i in value):
         msg = f"{errmsg['name']}Expected a sequence of {errmsg['sizes']} values."
         raise GMTInvalidInput(msg)
-    return [separator.join(str(j) for j in sub) for sub in value]
+    return [sep.join(str(j) for j in sub) for sub in value]

pygmt/tests/test_alias_system.py

@@ -22,12 +22,12 @@ def func(
     """
     aliasdict = AliasSystem(
         J=Alias(projection, name="projection"),
-        R=Alias(region, name="region", separator="/", size=[4, 6]),
+        R=Alias(region, name="region", sep="/", size=[4, 6]),
         B=Alias(frame, name="frame"),
         U=[
             Alias(label, name="label"),
             Alias(text, name="text", prefix="+t"),
-            Alias(offset, name="offset", prefix="+o", separator="/"),
+            Alias(offset, name="offset", prefix="+o", sep="/"),
         ],
     ).merge(kwargs)
     return build_arg_list(aliasdict)