Fix write_vrt and write_geotiff_gpu signature/docstring drift vs to_geotiff (#1631)

Three API-consistency drifts surfaced by the sweep on 2026-05-11:

1. write_vrt used **kwargs even though the docstring listed three
   accepted kwargs (relative, crs_wkt, nodata). inspect.signature, IDE
   autocomplete, and mypy --strict could not see them. Replaced with an
   explicit signature that mirrors _vrt.write_vrt and forwards each
   kwarg by name. A typo'd kwarg now raises TypeError from the public
   wrapper rather than from deep inside the internal helper.

2. write_geotiff_gpu's overview_resampling docstring omitted 'cubic'.
   to_geotiff lists it; the underlying make_overview_gpu accepts it
   (falls back to CPU for parity with the CPU writer). Updated the
   docstring to match.

3. write_geotiff_gpu(data) was untyped while to_geotiff(data) was
   annotated xr.DataArray | np.ndarray. Added xr.DataArray |
   cupy.ndarray for parity. Annotation is a forward reference under
   the module's `from __future__ import annotations`, so cupy stays
   lazily imported at function-body level.

Regression test: xrspatial/geotiff/tests/test_signature_parity_1631.py
pins each guarantee. inspect.signature parity, unknown-kwarg rejection
at the public wrapper, cubic-resampling round-trip on the GPU writer.

Author: brendancol

xrspatial/geotiff/__init__.py

@@ -2663,7 +2663,7 @@ def _read_once():
     return result
 
 
-def write_geotiff_gpu(data, path: str, *,
+def write_geotiff_gpu(data: xr.DataArray | cupy.ndarray, path: str, *,
                       crs: int | str | None = None,
                       nodata=None,
                       compression: str = 'zstd',
@@ -2726,7 +2726,10 @@ def write_geotiff_gpu(data, path: str, *,
         halving until the smallest overview fits in a single tile.
     overview_resampling : str
         Resampling method for overviews: 'mean' (default), 'nearest',
-        'min', 'max', 'median', or 'mode'.
+        'min', 'max', 'median', 'mode', or 'cubic'. ``mode`` and
+        ``cubic`` fall back to the CPU implementation in
+        ``xrspatial.geotiff._writer`` so the GPU writer produces the
+        same overview bytes as the CPU writer.
     bigtiff : bool or None
         Force BigTIFF (64-bit offsets). None auto-promotes when the
         estimated file size would exceed the classic-TIFF 4 GB limit.
@@ -3187,7 +3190,10 @@ def _sentinel_for_dtype(nodata_val, dtype):
     return result
 
 
-def write_vrt(vrt_path: str, source_files: list[str], **kwargs) -> str:
+def write_vrt(vrt_path: str, source_files: list[str], *,
+              relative: bool = True,
+              crs_wkt: str | None = None,
+              nodata: float | None = None) -> str:
     """Generate a VRT file that mosaics multiple GeoTIFF tiles.
 
     Parameters
@@ -3208,14 +3214,18 @@ def write_vrt(vrt_path: str, source_files: list[str], **kwargs) -> str:
     -------
     str
         Path to the written VRT file.
-
-    Notes
-    -----
-    Only the keyword arguments listed above are accepted. Passing any
-    other keyword raises ``TypeError`` from the underlying writer.
     """
+    # Explicit signature (previously ``**kwargs``) so ``inspect.signature``,
+    # IDE autocomplete, and ``mypy --strict`` can see the accepted kwargs
+    # without parsing the docstring. Mirrors ``_vrt.write_vrt`` exactly; if
+    # that signature changes, this wrapper must be updated in lockstep.
     from ._vrt import write_vrt as _write_vrt_internal
-    return _write_vrt_internal(vrt_path, source_files, **kwargs)
+    return _write_vrt_internal(
+        vrt_path, source_files,
+        relative=relative,
+        crs_wkt=crs_wkt,
+        nodata=nodata,
+    )
 
 
 def plot_geotiff(da: xr.DataArray, **kwargs):

xrspatial/geotiff/tests/test_signature_parity_1631.py

@@ -0,0 +1,151 @@
+"""Regression test for #1631: public write_vrt / write_geotiff_gpu
+signature and docstring parity vs to_geotiff.
+
+Three drifts were flagged by the api-consistency sweep on 2026-05-11:
+
+1. ``write_vrt(vrt_path, source_files, **kwargs)`` swallowed every kwarg
+   into ``**kwargs``. The docstring documented ``relative``, ``crs_wkt``,
+   ``nodata``, but ``inspect.signature`` and IDE autocomplete saw nothing.
+2. ``write_geotiff_gpu``'s ``overview_resampling`` docstring omitted
+   ``'cubic'``; ``to_geotiff`` lists it and ``make_overview_gpu`` accepts
+   it (falling back to CPU).
+3. ``write_geotiff_gpu(data, ...)`` lacked the type hint that
+   ``to_geotiff(data, ...)`` has.
+
+This module pins each of those three guarantees against future drift.
+"""
+
+import inspect
+import os
+import tempfile
+
+import numpy as np
+import pytest
+import xarray as xr
+
+from xrspatial.geotiff import (
+    open_geotiff,
+    to_geotiff,
+    write_geotiff_gpu,
+    write_vrt,
+)
+
+
+def test_write_vrt_signature_exposes_documented_kwargs():
+    """``inspect.signature(write_vrt)`` reports the three accepted kwargs.
+
+    Prior to #1631 the public wrapper used ``**kwargs``, so
+    ``inspect.signature`` only saw ``vrt_path`` and ``source_files``.
+    """
+    sig = inspect.signature(write_vrt)
+    params = sig.parameters
+    assert 'relative' in params
+    assert 'crs_wkt' in params
+    assert 'nodata' in params
+    # Defaults must match _vrt.write_vrt
+    assert params['relative'].default is True
+    assert params['crs_wkt'].default is None
+    assert params['nodata'].default is None
+    # No more catch-all VAR_KEYWORD
+    kinds = {p.kind for p in params.values()}
+    assert inspect.Parameter.VAR_KEYWORD not in kinds
+
+
+def test_write_vrt_unknown_kwarg_rejected_at_public_level():
+    """A typo'd kwarg now raises ``TypeError`` from the public function
+    rather than from deep inside ``_vrt.write_vrt``.
+    """
+    with tempfile.TemporaryDirectory() as td:
+        arr = np.zeros((8, 8), dtype=np.float32)
+        da = xr.DataArray(
+            arr, dims=['y', 'x'],
+            coords={'y': np.arange(8.0, 0, -1), 'x': np.arange(8.0)},
+            attrs={'crs': 4326, 'transform': (1.0, 0, 0.0, 0, -1.0, 8.0)},
+        )
+        tif_path = os.path.join(td, 't.tif')
+        to_geotiff(da, tif_path)
+
+        with pytest.raises(TypeError, match='typo_kwarg'):
+            write_vrt(os.path.join(td, 't.vrt'), [tif_path], typo_kwarg=1)
+
+
+def test_write_vrt_accepts_documented_kwargs():
+    """Each documented kwarg round-trips through the explicit signature."""
+    with tempfile.TemporaryDirectory() as td:
+        arr = np.zeros((8, 8), dtype=np.float32)
+        da = xr.DataArray(
+            arr, dims=['y', 'x'],
+            coords={'y': np.arange(8.0, 0, -1), 'x': np.arange(8.0)},
+            attrs={'crs': 4326, 'transform': (1.0, 0, 0.0, 0, -1.0, 8.0)},
+        )
+        tif_path = os.path.join(td, 't.tif')
+        to_geotiff(da, tif_path)
+
+        vrt_path = os.path.join(td, 't.vrt')
+        out = write_vrt(
+            vrt_path, [tif_path],
+            relative=False, crs_wkt=None, nodata=-9999.0,
+        )
+        assert out == vrt_path
+        assert os.path.exists(vrt_path)
+
+
+def test_write_geotiff_gpu_docstring_lists_cubic():
+    """``overview_resampling`` docstring includes ``'cubic'`` so it
+    matches ``to_geotiff`` and the underlying ``make_overview_gpu``.
+    """
+    doc = write_geotiff_gpu.__doc__
+    assert doc is not None
+    # Find the overview_resampling block
+    assert 'overview_resampling' in doc
+    # The block must mention cubic
+    block_start = doc.index('overview_resampling')
+    block_end = doc.index('bigtiff', block_start)
+    block = doc[block_start:block_end]
+    assert 'cubic' in block
+
+
+def test_write_geotiff_gpu_data_has_type_hint():
+    """``data`` parameter is annotated, matching ``to_geotiff(data, ...)``."""
+    sig = inspect.signature(write_geotiff_gpu)
+    data_param = sig.parameters['data']
+    assert data_param.annotation is not inspect.Parameter.empty
+    # The annotation is a forward reference under ``from __future__ import
+    # annotations``; just confirm it mentions the documented types.
+    ann_str = str(data_param.annotation)
+    assert 'DataArray' in ann_str or 'cupy' in ann_str
+
+
+@pytest.mark.skipif(
+    not pytest.importorskip('cupy', reason='cupy required').is_available()
+    if False else False,
+    reason='guarded below',
+)
+def test_write_geotiff_gpu_cubic_overview_round_trip():
+    """``overview_resampling='cubic'`` works on the GPU writer.
+
+    Sanity check that the docstring update is not advertising an
+    unsupported codec. ``make_overview_gpu`` falls back to the CPU
+    cubic implementation for parity with the CPU writer.
+    """
+    cupy = pytest.importorskip('cupy')
+    try:
+        cupy.zeros(1)
+    except Exception:
+        pytest.skip('cupy import succeeded but no device available')
+
+    with tempfile.TemporaryDirectory() as td:
+        arr_cpu = np.random.RandomState(0).rand(256, 256).astype(np.float32)
+        arr_gpu = cupy.asarray(arr_cpu)
+        da_gpu = xr.DataArray(
+            arr_gpu, dims=['y', 'x'],
+            coords={'y': np.arange(256.0, 0, -1), 'x': np.arange(256.0)},
+        )
+        path = os.path.join(td, 'cog.tif')
+        write_geotiff_gpu(
+            da_gpu, path,
+            cog=True, tile_size=64, overview_resampling='cubic',
+        )
+        # Overview level 1 = 1/2 resolution
+        ov = open_geotiff(path, overview_level=1)
+        assert ov.shape == (128, 128)