Merge branch 'main' into deprecate/load_dataarray

Author: weiji14

.github/workflows/ci_tests.yaml

@@ -152,7 +152,7 @@ jobs:
           GH_TOKEN: ${{ github.token }}
 
       - name: Install uv
-        uses: astral-sh/[email protected].1
+        uses: astral-sh/[email protected].2
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -183,7 +183,7 @@ jobs:
 
       # Upload coverage to Codecov
       - name: Upload coverage to Codecov
-        uses: codecov/[email protected].0
+        uses: codecov/[email protected].2
         if: success() || failure()
         with:
           use_oidc: true

doc/_templates/autosummary/class.rst

@@ -17,6 +17,7 @@
 .. rubric:: Methods Summary
 
 .. autosummary::
+    :toctree:
     {% for item in methods %}
     {% if item != '__init__' %}
     {{ objname }}.{{ item }}

doc/_templates/autosummary/module.rst

@@ -16,7 +16,7 @@
 .. rubric:: Classes
 
 .. autosummary::
-  :toctree: ./
+  :toctree:
 {% for item in classes %}
   {{ item }}
 {% endfor %}
@@ -29,7 +29,7 @@
 .. rubric:: Functions
 
 .. autosummary::
-  :toctree: ./
+  :toctree:
 {% for item in functions %}
   {{ item }}
 {% endfor %}
@@ -42,7 +42,7 @@
 .. rubric:: Exceptions
 
 .. autosummary::
-  :toctree: ./
+  :toctree:
 {% for item in exceptions %}
   {{ item }}
 {% endfor %}

doc/api/index.rst

@@ -1,9 +1,7 @@
-.. _api:
-
 API Reference
 =============
 
-.. automodule:: pygmt
+This page gives an overview of all public PyGMT objects, functions and methods.
 
 .. currentmodule:: pygmt
 
@@ -197,6 +195,14 @@ Getting metadata from tabular or grid data:
     info
     grdinfo
 
+Xarray Integration
+------------------
+
+.. autosummary::
+    :toctree: generated
+
+    GMTBackendEntrypoint
+
 Enums
 -----
 

pygmt/__init__.py

@@ -65,6 +65,7 @@
     x2sys_init,
     xyz2grd,
 )
+from pygmt.xarray import GMTBackendEntrypoint
 
 # Start our global modern mode session
 _begin()

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

@@ -71,14 +71,11 @@
             :gmt-docs:`gmt.html#f-full`.""",
     "cores": r"""
         cores : bool or int
-            [[**-**]\ *n*].
-            Limit the number of cores to be used in any OpenMP-enabled
-            multi-threaded algorithms. By default we try to use all available
-            cores. Set a number *n* to only use n cores (if too large it will
-            be truncated to the maximum cores available). Finally, give a
-            negative number *-n* to select (all - *n*) cores (or at least 1 if
-            *n* equals or exceeds all).
-            """,
+            Specify the number of active cores to be used in any OpenMP-enabled
+            multi-threaded algorithms. By default, all available cores are used. Set a
+            positive number *n* to use *n* cores (if too large it will be truncated to
+            the maximum cores available); or set a negative number *-n* to select
+            (all - *n*) cores (or at least 1 if *n* equals or exceeds all).""",
     "distcalc": r"""
         distcalc : str
             Determine how spherical distances are calculated
@@ -141,7 +138,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 +405,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 +420,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 +452,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.