Public geotiff API: type annotations missing on window / path / on_gpu_failure #1654

The api-consistency sweep on 2026-05-12 found one MEDIUM drift across the public xrspatial.geotiff surface: the same parameter is annotated on some siblings but not on others. Same kwarg, same semantics, different annotation behaviour for type-checkers and IDEs.

Missing annotations

window (4-tuple (r0, c0, r1, c1) or None):

• open_geotiff(source, *, dtype=None, window=None, ...) -- no annotation
• read_vrt(source: str, *, dtype=None, window=None, ...) -- no annotation
• read_geotiff_dask(source: str, *, ..., window: tuple | None = None, ...) -- has annotation
• read_geotiff_gpu(source: str, *, ..., window: tuple | None = None, ...) -- has annotation

path (str or binary file-like):

• to_geotiff(data, path, *, ...) -- no annotation
• write_geotiff_gpu(data, path, *, ...) -- no annotation
• write_vrt(vrt_path: str, ...) -- annotated (VRT is path-only, no file-like)

on_gpu_failure and the deprecated gpu alias:

• open_geotiff(... on_gpu_failure=_ON_GPU_FAILURE_SENTINEL) -- no annotation; docstring documents {'auto', 'strict'}
• read_geotiff_gpu(... on_gpu_failure=_ON_GPU_FAILURE_SENTINEL, gpu=_GPU_DEPRECATED_SENTINEL) -- both unannotated; the deprecated gpu alias accepts the same string values

The sentinel default does not block an annotation: the documented and accepted user values are 'auto' and 'strict', both str.

Severity

MEDIUM. These are public kwargs with documented value sets. Today mypy --strict and IDE autocomplete cannot validate user code against them, even though sibling functions in the same module do annotate them.

Not a breaking change

Annotation-only -- no runtime behaviour changes, no default changes, no kwarg renames. Compatible with existing callers because annotations are advisory and runtime accepts the same values.

Fix plan

Add annotations to the public signatures:

• window: tuple | None = None on open_geotiff and read_vrt
• path: str | typing.BinaryIO = ... (or equivalent) on to_geotiff and write_geotiff_gpu. write_vrt.vrt_path: str stays as-is because VRT writes are path-only.
• on_gpu_failure: str = _ON_GPU_FAILURE_SENTINEL on both open_geotiff and read_geotiff_gpu. The runtime check at the top of read_geotiff_gpu already validates against ('auto', 'strict'), so str is the right runtime contract.
• gpu: str = _GPU_DEPRECATED_SENTINEL (deprecated alias) on read_geotiff_gpu. Same runtime check.

The annotation choice is str over Literal['auto', 'strict'] because the validation happens at runtime and str keeps the contract symmetrical with the sentinel default; Literal would have to be wrapped in typing.Literal and would also need a TYPE_CHECKING block to avoid runtime import cost when sentinels are used.

Regression test

A new test should pin each affected parameter's annotation so future signature changes do not silently drop it. The existing test_signature_parity_1631.py is the right neighbour for this test.

Found via sweep

/sweep-api-consistency on 2026-05-12, focused on the geotiff subpackage. Audited categories 1-5; this is the only MEDIUM remaining after #1631 / #1644 / #1652 closed the earlier signature/docstring drifts. Other potential drifts (chunks default 512 vs None, crs vs crs_wkt, write_vrt return-type) are documented and intentional, no fix planned.