diff --git a/pygmt/helpers/__init__.py b/pygmt/helpers/__init__.py index 08583896b6c..0d074061ba1 100644 --- a/pygmt/helpers/__init__.py +++ b/pygmt/helpers/__init__.py @@ -19,7 +19,6 @@ _validate_data_input, args_in_kwargs, build_arg_list, - build_arg_string, data_kind, is_nonstr_iter, launch_external_viewer, diff --git a/pygmt/helpers/utils.py b/pygmt/helpers/utils.py index 337c27ffbd5..33ef60b4c98 100644 --- a/pygmt/helpers/utils.py +++ b/pygmt/helpers/utils.py @@ -9,7 +9,6 @@ import subprocess import sys import time -import warnings import webbrowser from collections.abc import Iterable, Sequence from typing import Any, Literal @@ -461,139 +460,6 @@ def build_arg_list( # noqa: PLR0912 return gmt_args -def build_arg_string(kwdict, confdict=None, infile=None, outfile=None): - r""" - Convert keyword dictionaries and input/output files into a GMT argument string. - - Make sure all values in ``kwdict`` have been previously converted to a - string representation using the ``kwargs_to_strings`` decorator. The only - exceptions are True, False and None. - - Any lists or tuples left will be interpreted as multiple entries for the - same command line option. For example, the kwargs entry ``'B': ['xa', - 'yaf']`` will be converted to ``-Bxa -Byaf`` in the argument string. - - Note that spaces `` `` in arguments are converted to the equivalent octal - code ``\040``, except in the case of -J (projection) arguments where PROJ4 - strings (e.g. "+proj=longlat +datum=WGS84") will have their spaces removed. - See https://github.com/GenericMappingTools/pygmt/pull/1487 for more info. - - .. deprecated:: 0.12.0 - - Use :func:`build_arg_list` instead. - - Parameters - ---------- - kwdict : dict - A dictionary containing parsed keyword arguments. - confdict : dict - A dictionary containing configurable GMT parameters. - infile : str or pathlib.Path - The input file. - outfile : str or pathlib.Path - The output file. - - Returns - ------- - args : str - The space-delimited argument string with '-' inserted before each - keyword, or '--' inserted before GMT configuration key-value pairs. - The keyword arguments are sorted alphabetically, followed by GMT - configuration key-value pairs, with optional input file at the - beginning and optional output file at the end. - - Examples - -------- - - >>> print( - ... build_arg_string( - ... dict( - ... A=True, - ... B=False, - ... E=200, - ... J="+proj=longlat +datum=WGS84", - ... P="", - ... R="1/2/3/4", - ... X=None, - ... Y=None, - ... Z=0, - ... ) - ... ) - ... ) - -A -E200 -J+proj=longlat+datum=WGS84 -P -R1/2/3/4 -Z0 - >>> print( - ... build_arg_string( - ... dict( - ... R="1/2/3/4", - ... J="X4i", - ... B=["xaf", "yaf", "WSen"], - ... I=("1/1p,blue", "2/0.25p,blue"), - ... ) - ... ) - ... ) - -BWSen -Bxaf -Byaf -I1/1p,blue -I2/0.25p,blue -JX4i -R1/2/3/4 - >>> print(build_arg_string(dict(R="1/2/3/4", J="X4i", watre=True))) - Traceback (most recent call last): - ... - pygmt.exceptions.GMTInvalidInput: Unrecognized parameter 'watre'. - >>> print( - ... build_arg_string( - ... dict( - ... B=["af", "WSne+tBlank Space"], - ... F='+t"Empty Spaces"', - ... l="'Void Space'", - ... ), - ... ) - ... ) - -BWSne+tBlank\040Space -Baf -F+t"Empty\040\040Spaces" -l'Void\040Space' - >>> print( - ... build_arg_string( - ... dict(A="0", B=True, C="rainbow"), - ... confdict=dict(FORMAT_DATE_MAP="o dd"), - ... infile="input.txt", - ... outfile="output.txt", - ... ) - ... ) - input.txt -A0 -B -Crainbow --FORMAT_DATE_MAP="o dd" ->output.txt - """ - msg = ( - "Utility function 'build_arg_string()' is deprecated in v0.12.0 and will be " - "removed in v0.14.0. Use 'build_arg_list()' instead." - ) - warnings.warn(msg, category=FutureWarning, stacklevel=2) - - gmt_args = [] - for key in kwdict: - if len(key) > 2: # raise an exception for unrecognized options - raise GMTInvalidInput(f"Unrecognized parameter '{key}'.") - if kwdict[key] is None or kwdict[key] is False: - pass # Exclude arguments that are None and False - elif is_nonstr_iter(kwdict[key]): - for value in kwdict[key]: - _value = str(value).replace(" ", r"\040") - gmt_args.append(rf"-{key}{_value}") - elif kwdict[key] is True: - gmt_args.append(f"-{key}") - else: - if key != "J": # non-projection parameters - _value = str(kwdict[key]).replace(" ", r"\040") - else: - # special handling if key == "J" (projection) - # remove any spaces in PROJ4 string - _value = str(kwdict[key]).replace(" ", "") - gmt_args.append(rf"-{key}{_value}") - gmt_args = sorted(gmt_args) - - if confdict: - gmt_args.extend(f'--{key}="{value}"' for key, value in confdict.items()) - - if infile: - gmt_args = [str(infile), *gmt_args] - if outfile: - gmt_args.append("->" + str(outfile)) - return non_ascii_to_octal(" ".join(gmt_args)) - - def is_nonstr_iter(value): """ Check if the value is not a string but is iterable (list, tuple, array)