Refactor the data_kind and validate_data_input functions

pygmt/clib/session.py

@@ -37,6 +37,7 @@
     data_kind,
     tempfile_from_geojson,
     tempfile_from_image,
+    validate_data_input,
 )
 
 FAMILIES = [
@@ -1591,8 +1592,15 @@ def virtualfile_in(  # noqa: PLR0912
         ...             print(fout.read().strip())
         <vector memory>: N = 3 <7/9> <4/6> <1/3>
         """
-        kind = data_kind(
-            data, x, y, z, required_z=required_z, required_data=required_data
+        kind = data_kind(data, required=required_data)
+        validate_data_input(
+            data=data,
+            x=x,
+            y=y,
+            z=z,
+            required_z=required_z,
+            required_data=required_data,
+            kind=kind,
         )
 
         if check_kind:

pygmt/helpers/__init__.py

@@ -22,5 +22,6 @@
     is_nonstr_iter,
     launch_external_viewer,
     non_ascii_to_octal,
+    validate_data_input,
 )
 from pygmt.helpers.validators import validate_output_table_type

pygmt/helpers/utils.py

@@ -12,74 +12,78 @@
 import warnings
 import webbrowser
 from collections.abc import Iterable, Sequence
-from typing import Any
+from typing import Any, Literal
 
 import xarray as xr
 from pygmt.encodings import charset
 from pygmt.exceptions import GMTInvalidInput
 
 
-def _validate_data_input(
+def validate_data_input(
     data=None, x=None, y=None, z=None, required_z=False, required_data=True, kind=None
 ):
     """
     Check if the combination of data/x/y/z is valid.
 
     Examples
     --------
-    >>> _validate_data_input(data="infile")
-    >>> _validate_data_input(x=[1, 2, 3], y=[4, 5, 6])
-    >>> _validate_data_input(x=[1, 2, 3], y=[4, 5, 6], z=[7, 8, 9])
-    >>> _validate_data_input(data=None, required_data=False)
-    >>> _validate_data_input()
+    >>> validate_data_input(data="infile")
+    >>> validate_data_input(x=[1, 2, 3], y=[4, 5, 6])
+    >>> validate_data_input(x=[1, 2, 3], y=[4, 5, 6], z=[7, 8, 9])
+    >>> validate_data_input(data=None, required_data=False)
+    >>> validate_data_input()
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: No input data provided.
-    >>> _validate_data_input(x=[1, 2, 3])
+    >>> validate_data_input(x=[1, 2, 3])
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Must provide both x and y.
-    >>> _validate_data_input(y=[4, 5, 6])
+    >>> validate_data_input(y=[4, 5, 6])
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Must provide both x and y.
-    >>> _validate_data_input(x=[1, 2, 3], y=[4, 5, 6], required_z=True)
+    >>> validate_data_input(x=[1, 2, 3], y=[4, 5, 6], required_z=True)
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Must provide x, y, and z.
     >>> import numpy as np
     >>> import pandas as pd
     >>> import xarray as xr
     >>> data = np.arange(8).reshape((4, 2))
-    >>> _validate_data_input(data=data, required_z=True, kind="matrix")
+    >>> validate_data_input(data=data, required_z=True, kind="matrix")
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: data must provide x, y, and z columns.
-    >>> _validate_data_input(
+    >>> validate_data_input(
     ...     data=pd.DataFrame(data, columns=["x", "y"]),
     ...     required_z=True,
     ...     kind="matrix",
     ... )
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: data must provide x, y, and z columns.
-    >>> _validate_data_input(
+    >>> validate_data_input(
     ...     data=xr.Dataset(pd.DataFrame(data, columns=["x", "y"])),
     ...     required_z=True,
     ...     kind="matrix",
     ... )
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: data must provide x, y, and z columns.
-    >>> _validate_data_input(data="infile", x=[1, 2, 3])
+    >>> validate_data_input(data="infile", x=[1, 2, 3])
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Too much data. Use either data or x/y/z.
-    >>> _validate_data_input(data="infile", y=[4, 5, 6])
+    >>> validate_data_input(data="infile", y=[4, 5, 6])
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Too much data. Use either data or x/y/z.
-    >>> _validate_data_input(data="infile", z=[7, 8, 9])
+    >>> validate_data_input(data="infile", x=[1, 2, 3], y=[4, 5, 6])
+    Traceback (most recent call last):
+        ...
+    pygmt.exceptions.GMTInvalidInput: Too much data. Use either data or x/y/z.
+    >>> validate_data_input(data="infile", z=[7, 8, 9])
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Too much data. Use either data or x/y/z.
@@ -111,7 +115,9 @@ def _validate_data_input(
                 raise GMTInvalidInput("data must provide x, y, and z columns.")
 
 
-def data_kind(data=None, x=None, y=None, z=None, required_z=False, required_data=True):
+def data_kind(
+    data: Any = None, required: bool = True
+) -> Literal["arg", "file", "geojson", "grid", "image", "matrix", "vectors"]:
     """
     Check what kind of data is provided to a module.
 
@@ -124,50 +130,39 @@ def data_kind(data=None, x=None, y=None, z=None, required_z=False, required_data
     * 1-D arrays x and y (and z, optionally)
     * an optional argument (None, bool, int or float) provided as 'data'
 
-    Arguments should be ``None`` if not used. If doesn't fit any of these
-    categories (or fits more than one), will raise an exception.
-
     Parameters
     ----------
     data : str, pathlib.PurePath, None, bool, xarray.DataArray or {table-like}
         Pass in either a file name or :class:`pathlib.Path` to an ASCII data
         table, an :class:`xarray.DataArray`, a 1-D/2-D
         {table-classes} or an option argument.
-    x/y : 1-D arrays or None
-        x and y columns as numpy arrays.
-    z : 1-D array or None
-        z column as numpy array. To be used optionally when x and y are given.
-    required_z : bool
-        State whether the 'z' column is required.
-    required_data : bool
+    required
         Set to True when 'data' is required, or False when dealing with
         optional virtual files. [Default is True].
 
     Returns
     -------
-    kind : str
-        One of ``'arg'``, ``'file'``, ``'grid'``, ``image``, ``'geojson'``,
-        ``'matrix'``, or ``'vectors'``.
+    kind
+        The data kind.
 
     Examples
     --------
-
     >>> import numpy as np
     >>> import xarray as xr
     >>> import pathlib
-    >>> data_kind(data=None, x=np.array([1, 2, 3]), y=np.array([4, 5, 6]))
+    >>> data_kind(data=None)
     'vectors'
-    >>> data_kind(data=np.arange(10).reshape((5, 2)), x=None, y=None)
+    >>> data_kind(data=np.arange(10).reshape((5, 2)))
     'matrix'
-    >>> data_kind(data="my-data-file.txt", x=None, y=None)
+    >>> data_kind(data="my-data-file.txt")
     'file'
-    >>> data_kind(data=pathlib.Path("my-data-file.txt"), x=None, y=None)
+    >>> data_kind(data=pathlib.Path("my-data-file.txt"))
     'file'
-    >>> data_kind(data=None, x=None, y=None, required_data=False)
+    >>> data_kind(data=None, required=False)
     'arg'
-    >>> data_kind(data=2.0, x=None, y=None, required_data=False)
+    >>> data_kind(data=2.0, required=False)
     'arg'
-    >>> data_kind(data=True, x=None, y=None, required_data=False)
+    >>> data_kind(data=True, required=False)
     'arg'
     >>> data_kind(data=xr.DataArray(np.random.rand(4, 3)))
     'grid'
@@ -181,7 +176,7 @@ def data_kind(data=None, x=None, y=None, z=None, required_z=False, required_data
     ):
         # One or more files
         kind = "file"
-    elif isinstance(data, bool | int | float) or (data is None and not required_data):
+    elif isinstance(data, bool | int | float) or (data is None and not required):
         kind = "arg"
     elif isinstance(data, xr.DataArray):
         kind = "image" if len(data.dims) == 3 else "grid"
@@ -193,15 +188,6 @@ def data_kind(data=None, x=None, y=None, z=None, required_z=False, required_data
         kind = "matrix"
     else:
         kind = "vectors"
-    _validate_data_input(
-        data=data,
-        x=x,
-        y=y,
-        z=z,
-        required_z=required_z,
-        required_data=required_data,
-        kind=kind,
-    )
     return kind
 
 

pygmt/src/plot.py

@@ -208,7 +208,7 @@ def plot(  # noqa: PLR0912
     """
     kwargs = self._preprocess(**kwargs)
 
-    kind = data_kind(data, x, y)
+    kind = data_kind(data)
     extra_arrays = []
     if kind == "vectors":  # Add more columns for vectors input
         # Parameters for vector styles

pygmt/src/plot3d.py

@@ -183,7 +183,7 @@ def plot3d(  # noqa: PLR0912
     """
     kwargs = self._preprocess(**kwargs)
 
-    kind = data_kind(data, x, y, z)
+    kind = data_kind(data)
     extra_arrays = []
 
     if kind == "vectors":  # Add more columns for vectors input

pygmt/src/text.py

@@ -180,11 +180,11 @@ def text_(  # noqa: PLR0912
 
     # Ensure inputs are either textfiles, x/y/text, or position/text
     if position is None:
-        if (x is not None or y is not None) and textfiles is not None:
+        if any(v is not None for v in (x, y, text)) and textfiles is not None:
             raise GMTInvalidInput(
                 "Provide either position only, or x/y pairs, or textfiles."
             )
-        kind = data_kind(textfiles, x, y, text)
+        kind = data_kind(textfiles)
         if kind == "vectors" and text is None:
             raise GMTInvalidInput("Must provide text with x/y pairs")
     else:

pygmt/tests/test_helpers.py

@@ -4,18 +4,11 @@
 
 from pathlib import Path
 
-import numpy as np
 import pytest
 import xarray as xr
 from pygmt import Figure
 from pygmt.exceptions import GMTInvalidInput
-from pygmt.helpers import (
-    GMTTempFile,
-    args_in_kwargs,
-    data_kind,
-    kwargs_to_strings,
-    unique_name,
-)
+from pygmt.helpers import GMTTempFile, args_in_kwargs, kwargs_to_strings, unique_name
 from pygmt.helpers.testing import load_static_earth_relief, skip_if_no
 
 
@@ -32,25 +25,6 @@ def test_load_static_earth_relief():
     assert isinstance(data, xr.DataArray)
 
 
-@pytest.mark.parametrize(
-    ("data", "x", "y"),
-    [
-        (None, None, None),
-        ("data.txt", np.array([1, 2]), np.array([4, 5])),
-        ("data.txt", np.array([1, 2]), None),
-        ("data.txt", None, np.array([4, 5])),
-        (None, np.array([1, 2]), None),
-        (None, None, np.array([4, 5])),
-    ],
-)
-def test_data_kind_fails(data, x, y):
-    """
-    Make sure data_kind raises exceptions when it should.
-    """
-    with pytest.raises(GMTInvalidInput):
-        data_kind(data=data, x=x, y=y)
-
-
 def test_unique_name():
     """
     Make sure the names are really unique.