Add args_in_kwargs function (#791)

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>
Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>

Author: 3 people

pygmt/helpers/__init__.py

@@ -4,6 +4,7 @@
 from pygmt.helpers.decorators import fmt_docstring, kwargs_to_strings, use_alias
 from pygmt.helpers.tempfile import GMTTempFile, unique_name
 from pygmt.helpers.utils import (
+    args_in_kwargs,
     build_arg_string,
     data_kind,
     dummy_context,

pygmt/helpers/utils.py

@@ -220,3 +220,29 @@ def launch_external_viewer(fname):
         subprocess.run(["open", fname], check=False, **run_args)
     else:
         webbrowser.open_new_tab("file://{}".format(fname))
+
+
+def args_in_kwargs(args, kwargs):
+    """
+    Take a list and a dictionary, and determine if any entries in the list are
+    keys in the dictionary.
+
+    This function is used to determine if at least one of the required
+    arguments is passed to raise a GMTInvalidInput Error.
+
+    Parameters
+    ----------
+    args : list
+        List of required arguments, using the GMT short-form aliases.
+
+    kwargs : dict
+        The dictionary of kwargs is the format returned by the _preprocess
+        function of the BasePlotting class. The keys are the GMT
+        short-form aliases of the parameters.
+
+    Returns
+    --------
+    bool
+        If one of the required arguments is in ``kwargs``.
+    """
+    return any(arg in kwargs for arg in args)

pygmt/tests/test_helpers.py

@@ -6,7 +6,13 @@
 import numpy as np
 import pytest
 from pygmt.exceptions import GMTInvalidInput
-from pygmt.helpers import GMTTempFile, data_kind, kwargs_to_strings, unique_name
+from pygmt.helpers import (
+    GMTTempFile,
+    args_in_kwargs,
+    data_kind,
+    kwargs_to_strings,
+    unique_name,
+)
 
 
 @pytest.mark.parametrize(
@@ -90,3 +96,17 @@ def test_gmttempfile_read():
             ftmp.write("in.dat: N = 2\t<1/3>\t<2/4>\n")
         assert tmpfile.read() == "in.dat: N = 2 <1/3> <2/4>\n"
         assert tmpfile.read(keep_tabs=True) == "in.dat: N = 2\t<1/3>\t<2/4>\n"
+
+
+def test_args_in_kwargs():
+    "Test that args_in_kwargs function returns correct Boolean responses."
+    kwargs = {"A": 1, "B": 2, "C": 3}
+    # Passing list of arguments with passing values in the beginning
+    passing_args_1 = ["B", "C", "D"]
+    assert args_in_kwargs(args=passing_args_1, kwargs=kwargs)
+    # Passing list of arguments that starts with failing arguments
+    passing_args_2 = ["D", "X", "C"]
+    assert args_in_kwargs(args=passing_args_2, kwargs=kwargs)
+    # Failing list of arguments
+    failing_args = ["D", "E", "F"]
+    assert not args_in_kwargs(args=failing_args, kwargs=kwargs)