From e79a7d0171247da3b97c2705a0aafaa93f245be9 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 17 Jul 2024 17:28:45 +0800 Subject: [PATCH 1/8] Make _validate_data_input public and move it to Session.virtualfile_in --- pygmt/clib/session.py | 10 ++++++++++ pygmt/helpers/__init__.py | 1 + pygmt/helpers/utils.py | 39 +++++++++++++++------------------------ 3 files changed, 26 insertions(+), 24 deletions(-) diff --git a/pygmt/clib/session.py b/pygmt/clib/session.py index 1e9489d4720..7a8981fc920 100644 --- a/pygmt/clib/session.py +++ b/pygmt/clib/session.py @@ -37,6 +37,7 @@ data_kind, tempfile_from_geojson, tempfile_from_image, + validate_data_input, ) FAMILIES = [ @@ -1594,6 +1595,15 @@ def virtualfile_in( # noqa: PLR0912 kind = data_kind( data, x, y, z, required_z=required_z, required_data=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: valid_kinds = ("file", "arg") if required_data is False else ("file",) diff --git a/pygmt/helpers/__init__.py b/pygmt/helpers/__init__.py index 128b1e31a18..aa87b9d4887 100644 --- a/pygmt/helpers/__init__.py +++ b/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 diff --git a/pygmt/helpers/utils.py b/pygmt/helpers/utils.py index 8997a2b0df1..4974802581f 100644 --- a/pygmt/helpers/utils.py +++ b/pygmt/helpers/utils.py @@ -19,7 +19,7 @@ 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 ): """ @@ -27,23 +27,23 @@ def _validate_data_input( 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. @@ -51,11 +51,11 @@ def _validate_data_input( >>> 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", @@ -63,7 +63,7 @@ def _validate_data_input( 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", @@ -71,15 +71,15 @@ def _validate_data_input( 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", z=[7, 8, 9]) Traceback (most recent call last): ... pygmt.exceptions.GMTInvalidInput: Too much data. Use either data or x/y/z. @@ -193,15 +193,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 From e2a8ceba70222fcf1d57fda9fb04a29149ad5ce6 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 17 Jul 2024 17:43:03 +0800 Subject: [PATCH 2/8] Remove test_data_kind_fails because it's already covered by validate_data_input doctests --- pygmt/helpers/utils.py | 4 ++++ pygmt/tests/test_helpers.py | 28 +--------------------------- 2 files changed, 5 insertions(+), 27 deletions(-) diff --git a/pygmt/helpers/utils.py b/pygmt/helpers/utils.py index 4974802581f..3648d56857c 100644 --- a/pygmt/helpers/utils.py +++ b/pygmt/helpers/utils.py @@ -79,6 +79,10 @@ def validate_data_input( Traceback (most recent call last): ... pygmt.exceptions.GMTInvalidInput: Too much data. Use either data or x/y/z. + >>> 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): ... diff --git a/pygmt/tests/test_helpers.py b/pygmt/tests/test_helpers.py index ea9e4c87225..9aa67f309bc 100644 --- a/pygmt/tests/test_helpers.py +++ b/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. From 008a56f973625bc3b57c6a8613df16af7bb485fb Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 17 Jul 2024 17:57:35 +0800 Subject: [PATCH 3/8] Remove the unused x/y/z/required_z parameters from data_kind --- pygmt/clib/session.py | 4 +--- pygmt/helpers/utils.py | 22 ++++++++-------------- pygmt/src/plot.py | 2 +- pygmt/src/plot3d.py | 2 +- pygmt/src/text.py | 4 ++-- 5 files changed, 13 insertions(+), 21 deletions(-) diff --git a/pygmt/clib/session.py b/pygmt/clib/session.py index 7a8981fc920..2af356f2e7b 100644 --- a/pygmt/clib/session.py +++ b/pygmt/clib/session.py @@ -1592,9 +1592,7 @@ def virtualfile_in( # noqa: PLR0912 ... print(fout.read().strip()) : 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_data=required_data) validate_data_input( data=data, x=x, diff --git a/pygmt/helpers/utils.py b/pygmt/helpers/utils.py index 3648d56857c..99cbfab1731 100644 --- a/pygmt/helpers/utils.py +++ b/pygmt/helpers/utils.py @@ -115,7 +115,7 @@ 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=None, required_data=True): """ Check what kind of data is provided to a module. @@ -137,12 +137,6 @@ def data_kind(data=None, x=None, y=None, z=None, required_z=False, required_data 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 Set to True when 'data' is required, or False when dealing with optional virtual files. [Default is True]. @@ -159,19 +153,19 @@ def data_kind(data=None, x=None, y=None, z=None, required_z=False, required_data >>> 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_data=False) 'arg' - >>> data_kind(data=2.0, x=None, y=None, required_data=False) + >>> data_kind(data=2.0, required_data=False) 'arg' - >>> data_kind(data=True, x=None, y=None, required_data=False) + >>> data_kind(data=True, required_data=False) 'arg' >>> data_kind(data=xr.DataArray(np.random.rand(4, 3))) 'grid' diff --git a/pygmt/src/plot.py b/pygmt/src/plot.py index 43b26232871..e66f08438e5 100644 --- a/pygmt/src/plot.py +++ b/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 diff --git a/pygmt/src/plot3d.py b/pygmt/src/plot3d.py index 65d87761d5c..c86e5e259f1 100644 --- a/pygmt/src/plot3d.py +++ b/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 diff --git a/pygmt/src/text.py b/pygmt/src/text.py index 04abf12ea3b..484f885997a 100644 --- a/pygmt/src/text.py +++ b/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: From 46fb30744668dd4be560c4cf2f6dcc7978e84200 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Thu, 18 Jul 2024 01:55:57 +0800 Subject: [PATCH 4/8] data_kind: Change the parameter name from required_data to required --- pygmt/clib/session.py | 2 +- pygmt/helpers/utils.py | 21 +++++++++++---------- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/pygmt/clib/session.py b/pygmt/clib/session.py index 2af356f2e7b..c3ea579405c 100644 --- a/pygmt/clib/session.py +++ b/pygmt/clib/session.py @@ -1592,7 +1592,7 @@ def virtualfile_in( # noqa: PLR0912 ... print(fout.read().strip()) : N = 3 <7/9> <4/6> <1/3> """ - kind = data_kind(data, required_data=required_data) + kind = data_kind(data, required=required_data) validate_data_input( data=data, x=x, diff --git a/pygmt/helpers/utils.py b/pygmt/helpers/utils.py index 99cbfab1731..880c891a844 100644 --- a/pygmt/helpers/utils.py +++ b/pygmt/helpers/utils.py @@ -12,7 +12,7 @@ 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 @@ -115,7 +115,9 @@ def validate_data_input( raise GMTInvalidInput("data must provide x, y, and z columns.") -def data_kind(data=None, 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. @@ -137,15 +139,14 @@ def data_kind(data=None, required_data=True): 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. - 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 -------- @@ -161,11 +162,11 @@ def data_kind(data=None, required_data=True): 'file' >>> data_kind(data=pathlib.Path("my-data-file.txt")) 'file' - >>> data_kind(data=None, required_data=False) + >>> data_kind(data=None, required=False) 'arg' - >>> data_kind(data=2.0, required_data=False) + >>> data_kind(data=2.0, required=False) 'arg' - >>> data_kind(data=True, required_data=False) + >>> data_kind(data=True, required=False) 'arg' >>> data_kind(data=xr.DataArray(np.random.rand(4, 3))) 'grid' @@ -179,7 +180,7 @@ def data_kind(data=None, required_data=True): ): # 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" From d3854da490a14759e31122bdf13d5bb1fc61be1e Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Thu, 18 Jul 2024 10:48:40 +0800 Subject: [PATCH 5/8] Update docstrings --- pygmt/helpers/utils.py | 4 ---- 1 file changed, 4 deletions(-) diff --git a/pygmt/helpers/utils.py b/pygmt/helpers/utils.py index 880c891a844..c881589df31 100644 --- a/pygmt/helpers/utils.py +++ b/pygmt/helpers/utils.py @@ -130,9 +130,6 @@ def data_kind( * 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} @@ -150,7 +147,6 @@ def data_kind( Examples -------- - >>> import numpy as np >>> import xarray as xr >>> import pathlib From a9670aa6618818de04175e4894bfb4bf3c441cd6 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Thu, 18 Jul 2024 10:57:41 +0800 Subject: [PATCH 6/8] Fix a typing hints issue --- pygmt/helpers/utils.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pygmt/helpers/utils.py b/pygmt/helpers/utils.py index c881589df31..d140de69e8f 100644 --- a/pygmt/helpers/utils.py +++ b/pygmt/helpers/utils.py @@ -169,7 +169,7 @@ def data_kind( >>> data_kind(data=xr.DataArray(np.random.rand(3, 4, 5))) 'image' """ - # determine the data kind + kind: Literal["arg", "file", "geojson", "grid", "image", "matrix", "vectors"] if isinstance(data, str | pathlib.PurePath) or ( isinstance(data, list | tuple) and all(isinstance(_file, str | pathlib.PurePath) for _file in data) From 7ff0d9e2698bf23339a3c271129e63b827245d4b Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 19 Jul 2024 09:50:13 +0800 Subject: [PATCH 7/8] Make validate_data_input private --- pygmt/clib/session.py | 4 ++-- pygmt/helpers/__init__.py | 2 +- pygmt/helpers/utils.py | 32 ++++++++++++++++---------------- 3 files changed, 19 insertions(+), 19 deletions(-) diff --git a/pygmt/clib/session.py b/pygmt/clib/session.py index c3ea579405c..03c7225c1a1 100644 --- a/pygmt/clib/session.py +++ b/pygmt/clib/session.py @@ -34,10 +34,10 @@ GMTVersionError, ) from pygmt.helpers import ( + _validate_data_input, data_kind, tempfile_from_geojson, tempfile_from_image, - validate_data_input, ) FAMILIES = [ @@ -1593,7 +1593,7 @@ def virtualfile_in( # noqa: PLR0912 : N = 3 <7/9> <4/6> <1/3> """ kind = data_kind(data, required=required_data) - validate_data_input( + _validate_data_input( data=data, x=x, y=y, diff --git a/pygmt/helpers/__init__.py b/pygmt/helpers/__init__.py index aa87b9d4887..862abbbdd64 100644 --- a/pygmt/helpers/__init__.py +++ b/pygmt/helpers/__init__.py @@ -15,6 +15,7 @@ unique_name, ) from pygmt.helpers.utils import ( + _validate_data_input, args_in_kwargs, build_arg_list, build_arg_string, @@ -22,6 +23,5 @@ is_nonstr_iter, launch_external_viewer, non_ascii_to_octal, - validate_data_input, ) from pygmt.helpers.validators import validate_output_table_type diff --git a/pygmt/helpers/utils.py b/pygmt/helpers/utils.py index d140de69e8f..59185c645f1 100644 --- a/pygmt/helpers/utils.py +++ b/pygmt/helpers/utils.py @@ -19,7 +19,7 @@ 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 ): """ @@ -27,23 +27,23 @@ def validate_data_input( 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. @@ -51,11 +51,11 @@ def validate_data_input( >>> 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", @@ -63,7 +63,7 @@ def validate_data_input( 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", @@ -71,19 +71,19 @@ def validate_data_input( 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", x=[1, 2, 3], y=[4, 5, 6]) + >>> _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]) + >>> _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. From b575591ace1374b5bdc547f94fcf1262aacf247d Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 19 Jul 2024 13:06:03 +0800 Subject: [PATCH 8/8] Improve the docstrings of the data_kind function --- pygmt/helpers/utils.py | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/pygmt/helpers/utils.py b/pygmt/helpers/utils.py index 7a182421636..2e981266575 100644 --- a/pygmt/helpers/utils.py +++ b/pygmt/helpers/utils.py @@ -119,16 +119,17 @@ 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. + Check the kind of data that is provided to a module. - Possible types: + The ``data`` argument can be in any type, but only following types are supported: - * a file name provided as 'data' - * a pathlib.PurePath object provided as 'data' - * an xarray.DataArray object provided as 'data' - * a 2-D matrix provided as 'data' - * 1-D arrays x and y (and z, optionally) - * an optional argument (None, bool, int or float) provided as 'data' + - a string or a :class:`pathlib.PurePath` object or a sequence of them, representing + a file name or a list of file names + - a 2-D or 3-D :class:`xarray.DataArray` object + - a 2-D matrix + - None, bool, int or float type representing an optional arguments + - a geo-like Python object that implements ``__geo_interface__`` (e.g., + geopandas.GeoDataFrame or shapely.geometry) Parameters ----------