TYP: Add PathLike and TableLike types for type hints and remove the table-like placeholder (#3920)

Co-authored-by: Wei Ji <[email protected]>

Author: seisman

pygmt/_typing.py

@@ -4,10 +4,13 @@
 
 import contextlib
 import importlib
+import os
 from collections.abc import Sequence
 from typing import Literal
 
 import numpy as np
+import pandas as pd
+import xarray as xr
 
 # Anchor codes
 AnchorCode = Literal["TL", "TC", "TR", "ML", "MC", "MR", "BL", "BC", "BR"]
@@ -16,3 +19,9 @@
 StringArrayTypes = Sequence[str] | np.ndarray
 with contextlib.suppress(ImportError):
     StringArrayTypes |= importlib.import_module(name="pyarrow").StringArray
+
+# PathLike and TableLike types
+PathLike = str | os.PathLike
+TableLike = dict | np.ndarray | pd.DataFrame | xr.Dataset
+with contextlib.suppress(ImportError):
+    TableLike |= importlib.import_module(name="geopandas").GeoDataFrame

pygmt/clib/session.py

@@ -1772,7 +1772,7 @@ def virtualfile_in(
         check_kind : str or None
             Used to validate the type of data that can be passed in. Choose
             from 'raster', 'vector', or None. Default is None (no validation).
-        data : str or pathlib.Path or xarray.DataArray or {table-like} or dict or None
+        data
             Any raster or vector data format. This could be a file name or
             path, a raster grid, a vector matrix/arrays, or other supported
             data input.

pygmt/figure.py

@@ -4,10 +4,12 @@
 
 import base64
 import os
-from pathlib import Path, PurePath
+from pathlib import Path
 from tempfile import TemporaryDirectory
 from typing import Literal, overload
 
+from pygmt._typing import PathLike
+
 try:
     import IPython
 
@@ -137,7 +139,7 @@ def region(self) -> np.ndarray:
 
     def savefig(
         self,
-        fname: str | PurePath,
+        fname: PathLike,
         transparent: bool = False,
         crop: bool = True,
         anti_alias: bool = True,

pygmt/helpers/decorators.py

@@ -141,7 +141,7 @@
                 - **+p**: specify that the current value minus the previous
                   value must exceed *gap* for a break to be imposed.""",
     "grid": r"""
-        grid : str or xarray.DataArray
+        grid
             Name of the input grid file or the grid loaded as a
             :class:`xarray.DataArray` object.
 
@@ -408,7 +408,7 @@ def fmt_docstring(module_func):
     ...
     ...     Parameters
     ...     ----------
-    ...     data : str, {table-like}
+    ...     data
     ...         Pass in either a file name to an ASCII data table, a 2-D
     ...         {table-classes}.
     ...     {region}
@@ -423,7 +423,7 @@ def fmt_docstring(module_func):
     <BLANKLINE>
     Parameters
     ----------
-    data : str, numpy.ndarray, pandas.DataFrame, xarray.Dataset, or geo...
+    data
         Pass in either a file name to an ASCII data table, a 2-D
         :class:`numpy.ndarray`, a :class:`pandas.DataFrame`, an
         :class:`xarray.Dataset` made up of 1-D :class:`xarray.DataArray`
@@ -455,9 +455,6 @@ def fmt_docstring(module_func):
             aliases.append(f"   - {arg} = {alias}")
         filler_text["aliases"] = "\n".join(aliases)
 
-    filler_text["table-like"] = (
-        "numpy.ndarray, pandas.DataFrame, xarray.Dataset, or geopandas.GeoDataFrame"
-    )
     filler_text["table-classes"] = (
         ":class:`numpy.ndarray`, a :class:`pandas.DataFrame`, an\n"
         "    :class:`xarray.Dataset` made up of 1-D :class:`xarray.DataArray`\n"

pygmt/helpers/utils.py

@@ -4,7 +4,6 @@
 
 import io
 import os
-import pathlib
 import shutil
 import string
 import subprocess
@@ -17,6 +16,7 @@
 from typing import Any, Literal
 
 import xarray as xr
+from pygmt._typing import PathLike
 from pygmt.encodings import charset
 from pygmt.exceptions import GMTInvalidInput
 
@@ -387,10 +387,10 @@ def data_kind(
     match data:
         case None if required:  # No data provided and required=True.
             kind = "empty"
-        case str() | pathlib.PurePath():  # One file.
+        case str() | os.PathLike():  # One file.
             kind = "file"
         case list() | tuple() if all(
-            isinstance(_file, str | pathlib.PurePath) for _file in data
+            isinstance(_file, str | os.PathLike) for _file in data
         ):  # A list/tuple of files.
             kind = "file"
         case io.StringIO():
@@ -482,8 +482,8 @@ def non_ascii_to_octal(argstr: str, encoding: Encoding = "ISOLatin1+") -> str:
 def build_arg_list(  # noqa: PLR0912
     kwdict: dict[str, Any],
     confdict: Mapping[str, Any] | None = None,
-    infile: str | pathlib.PurePath | Sequence[str | pathlib.PurePath] | None = None,
-    outfile: str | pathlib.PurePath | None = None,
+    infile: PathLike | Sequence[PathLike] | None = None,
+    outfile: PathLike | None = None,
 ) -> list[str]:
     r"""
     Convert keyword dictionaries and input/output files into a list of GMT arguments.
@@ -581,19 +581,19 @@ def build_arg_list(  # noqa: PLR0912
         gmt_args.extend(f"--{key}={value}" for key, value in confdict.items())
 
     if infile:  # infile can be a single file or a list of files
-        if isinstance(infile, str | pathlib.PurePath):
-            gmt_args = [str(infile), *gmt_args]
+        if isinstance(infile, str | os.PathLike):
+            gmt_args = [os.fspath(infile), *gmt_args]
         else:
-            gmt_args = [str(_file) for _file in infile] + gmt_args
+            gmt_args = [os.fspath(_file) for _file in infile] + gmt_args
     if outfile is not None:
         if (
-            not isinstance(outfile, str | pathlib.PurePath)
-            or str(outfile) in {"", ".", ".."}
-            or str(outfile).endswith(("/", "\\"))
+            not isinstance(outfile, str | os.PathLike)
+            or os.fspath(outfile) in {"", ".", ".."}
+            or os.fspath(outfile).endswith(("/", "\\"))
         ):
             msg = f"Invalid output file name '{outfile}'."
             raise GMTInvalidInput(msg)
-        gmt_args.append(f"->{outfile}")
+        gmt_args.append(f"->{os.fspath(outfile)}")
     return gmt_args
 
 
@@ -632,7 +632,7 @@ def is_nonstr_iter(value: Any) -> bool:
     return isinstance(value, Iterable) and not isinstance(value, str)
 
 
-def launch_external_viewer(fname: str, waiting: float = 0) -> None:
+def launch_external_viewer(fname: PathLike, waiting: float = 0) -> None:
     """
     Open a file in an external viewer program.
 

pygmt/helpers/validators.py

@@ -5,11 +5,12 @@
 import warnings
 from typing import Literal
 
+from pygmt._typing import PathLike
 from pygmt.exceptions import GMTInvalidInput
 
 
 def validate_output_table_type(
-    output_type: Literal["pandas", "numpy", "file"], outfile: str | None = None
+    output_type: Literal["pandas", "numpy", "file"], outfile: PathLike | None = None
 ) -> Literal["pandas", "numpy", "file"]:
     """
     Check if the ``output_type`` and ``outfile`` parameters are valid.

pygmt/src/binstats.py

@@ -3,6 +3,7 @@
 """
 
 import xarray as xr
+from pygmt._typing import PathLike, TableLike
 from pygmt.clib import Session
 from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
 
@@ -24,7 +25,9 @@
     r="registration",
 )
 @kwargs_to_strings(I="sequence", R="sequence", i="sequence_comma")
-def binstats(data, outgrid: str | None = None, **kwargs) -> xr.DataArray | None:
+def binstats(
+    data: PathLike | TableLike, outgrid: PathLike | None = None, **kwargs
+) -> xr.DataArray | None:
     r"""
     Bin spatial data and determine statistics per bin.
 
@@ -42,7 +45,7 @@ def binstats(data, outgrid: str | None = None, **kwargs) -> xr.DataArray | None:
 
     Parameters
     ----------
-    data : str, {table-like}
+    data
         A file name of an ASCII data table or a 2-D {table-classes}.
     {outgrid}
     statistic : str

pygmt/src/blockm.py

@@ -6,6 +6,7 @@
 
 import numpy as np
 import pandas as pd
+from pygmt._typing import PathLike, TableLike
 from pygmt.clib import Session
 from pygmt.helpers import (
     build_arg_list,
@@ -87,12 +88,12 @@ def _blockm(
 )
 @kwargs_to_strings(I="sequence", R="sequence", i="sequence_comma", o="sequence_comma")
 def blockmean(
-    data=None,
+    data: PathLike | TableLike | None = None,
     x=None,
     y=None,
     z=None,
     output_type: Literal["pandas", "numpy", "file"] = "pandas",
-    outfile: str | None = None,
+    outfile: PathLike | None = None,
     **kwargs,
 ) -> pd.DataFrame | np.ndarray | None:
     r"""
@@ -113,7 +114,7 @@ def blockmean(
 
     Parameters
     ----------
-    data : str, {table-like}
+    data
         Pass in (x, y, z) or (longitude, latitude, elevation) values by
         providing a file name to an ASCII data table, a 2-D
         {table-classes}.
@@ -191,12 +192,12 @@ def blockmean(
 )
 @kwargs_to_strings(I="sequence", R="sequence", i="sequence_comma", o="sequence_comma")
 def blockmedian(
-    data=None,
+    data: PathLike | TableLike | None = None,
     x=None,
     y=None,
     z=None,
     output_type: Literal["pandas", "numpy", "file"] = "pandas",
-    outfile: str | None = None,
+    outfile: PathLike | None = None,
     **kwargs,
 ) -> pd.DataFrame | np.ndarray | None:
     r"""
@@ -217,7 +218,7 @@ def blockmedian(
 
     Parameters
     ----------
-    data : str, {table-like}
+    data
         Pass in (x, y, z) or (longitude, latitude, elevation) values by
         providing a file name to an ASCII data table, a 2-D
         {table-classes}.
@@ -289,12 +290,12 @@ def blockmedian(
 )
 @kwargs_to_strings(I="sequence", R="sequence", i="sequence_comma", o="sequence_comma")
 def blockmode(
-    data=None,
+    data: PathLike | TableLike | None = None,
     x=None,
     y=None,
     z=None,
     output_type: Literal["pandas", "numpy", "file"] = "pandas",
-    outfile: str | None = None,
+    outfile: PathLike | None = None,
     **kwargs,
 ) -> pd.DataFrame | np.ndarray | None:
     r"""
@@ -315,7 +316,7 @@ def blockmode(
 
     Parameters
     ----------
-    data : str, {table-like}
+    data
         Pass in (x, y, z) or (longitude, latitude, elevation) values by
         providing a file name to an ASCII data table, a 2-D
         {table-classes}.

pygmt/src/contour.py

@@ -2,6 +2,7 @@
 contour - Contour table data by direct triangulation.
 """
 
+from pygmt._typing import PathLike, TableLike
 from pygmt.clib import Session
 from pygmt.helpers import (
     build_arg_list,
@@ -37,7 +38,9 @@
     t="transparency",
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
-def contour(self, data=None, x=None, y=None, z=None, **kwargs):
+def contour(
+    self, data: PathLike | TableLike | None = None, x=None, y=None, z=None, **kwargs
+):
     r"""
     Contour table data by direct triangulation.
 
@@ -52,7 +55,7 @@ def contour(self, data=None, x=None, y=None, z=None, **kwargs):
 
     Parameters
     ----------
-    data : str, {table-like}
+    data
         Pass in (x, y, z) or (longitude, latitude, elevation) values by
         providing a file name to an ASCII data table, a 2-D
         {table-classes}.

pygmt/src/dimfilter.py

@@ -3,6 +3,7 @@
 """
 
 import xarray as xr
+from pygmt._typing import PathLike
 from pygmt.clib import Session
 from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
@@ -20,7 +21,9 @@
     V="verbose",
 )
 @kwargs_to_strings(I="sequence", R="sequence")
-def dimfilter(grid, outgrid: str | None = None, **kwargs) -> xr.DataArray | None:
+def dimfilter(
+    grid: PathLike | xr.DataArray, outgrid: PathLike | None = None, **kwargs
+) -> xr.DataArray | None:
     r"""
     Directional filtering of grids in the space domain.