geotiff: write_vrt and write_geotiff_gpu signatures drift vs to_geotiff #1631

Summary

API consistency sweep flagged three signature/docstring drifts between the public reader/writer entry points in xrspatial.geotiff. None are correctness bugs, but they make tooling (IDE autocomplete, type checkers, inspect.signature) lie to users.

1. write_vrt uses **kwargs instead of an explicit signature

xrspatial/geotiff/__init__.py:3190

def write_vrt(vrt_path: str, source_files: list[str], **kwargs) -> str:
    ...

The docstring documents relative, crs_wkt, and nodata as accepted kwargs, but the actual signature swallows them via **kwargs. As a result:

• inspect.signature(write_vrt) returns (vrt_path, source_files, **kwargs) and gives callers no information about what is valid.
• IDE autocomplete and mypy --strict cannot see the accepted kwargs.
• A typo like write_vrt(..., crs_wtk=...) raises a TypeError from deep inside _vrt.write_vrt, not from the public entry point.

The underlying _vrt.write_vrt already has the explicit signature (vrt_path, source_files, *, relative=True, crs_wkt=None, nodata=None). The public wrapper should mirror it.

2. write_geotiff_gpu docstring omits 'cubic' from overview_resampling

xrspatial/geotiff/__init__.py:2727

to_geotiff's docstring lists 'mean', 'nearest', 'min', 'max', 'median', 'mode', and 'cubic' (__init__.py:944). write_geotiff_gpu's docstring drops 'cubic'. The underlying make_overview_gpu in _gpu_decode.py:2975 does accept 'cubic' (it falls back to the CPU implementation), so the docstring is incomplete.

3. write_geotiff_gpu(data) has no type hint while to_geotiff(data) does

xrspatial/geotiff/__init__.py:2666

to_geotiff(data: xr.DataArray | np.ndarray, path, ...) is fully typed. write_geotiff_gpu(data, path: str, ...) leaves data untyped even though the docstring says "xr.DataArray (CuPy-backed) or cupy.ndarray". Sibling functions in the same module should agree on hint coverage.

Severity

MEDIUM (Cat 3, documentation / signature drift). Not a correctness bug, but a consistency gap visible to anyone introspecting the API.

Proposed fix

1. Replace write_vrt(vrt_path, source_files, **kwargs) with the explicit signature, forwarding to _vrt.write_vrt.
2. Add 'cubic' to write_geotiff_gpu's overview_resampling docstring (matches to_geotiff and make_overview_gpu).
3. Add the type hint data: xr.DataArray | cupy.ndarray to write_geotiff_gpu. The hint uses a string form since cupy is imported lazily.

All three changes are non-breaking. Test coverage: a smoke test asserting inspect.signature(write_vrt) exposes the three accepted parameters and that write_geotiff_gpu(..., overview_resampling='cubic') works.

Discovered by

/sweep-api-consistency against the geotiff module on 2026-05-11.