geotiff: reader trio dtype kwarg lacks type annotation #1775

Summary

Follow-up to #1654, #1705, and #1754 (annotation-parity sweep work). The api-consistency sweep on 2026-05-13 found that the dtype kwarg on all four public reader entry points (open_geotiff, read_geotiff_dask, read_geotiff_gpu, read_vrt) lacks a type annotation, while the docstrings consistently document the accepted type as str, numpy.dtype, or None.

Detail

Current signatures (xrspatial/geotiff/init.py):

def open_geotiff(source: str | BinaryIO, *, dtype=None, ...) -> xr.DataArray: ...

def read_geotiff_dask(source: str, *, dtype=None, chunks: int | tuple = 512, ...) -> xr.DataArray: ...

def read_geotiff_gpu(source: str, *, dtype=None, ...) -> xr.DataArray: ...

def read_vrt(source: str, *, dtype=None, ...) -> xr.DataArray: ...

Each docstring documents:

dtype : str, numpy.dtype, or None
    Cast the result to this dtype after reading. None keeps the
    file's native dtype. Float-to-int casts raise ValueError.

inspect.signature(...).parameters['dtype'].annotation is inspect.Parameter.empty for all four. mypy --strict therefore infers Any for dtype= on every reader entry point, while the same kwarg on sibling kwargs like chunks, window, band, name is annotated.

Severity

MEDIUM (Cat 3, type hint drift). Annotation-only; no runtime behaviour change. Same shape as the gaps #1654, #1705, and #1754 closed for window, path, on_gpu_failure, nodata, streaming_buffer_bytes, and source annotations across the public API.

Proposed fix

1. Annotate dtype on all four readers as str | np.dtype | None = None. The module already imports numpy as np at runtime and has from __future__ import annotations, so the annotation is a forward reference with no runtime import cost.
2. Extend xrspatial/geotiff/tests/test_signature_annotations_1654.py with four new pins covering dtype on every reader entry point.

Non-breaking. dtype=None is the existing default and str/numpy.dtype are the accepted input types per the docstring; the runtime branches on np.dtype(dtype) after the call, which already accepts both.

Deprecation impact

None. Annotation-only change with no signature renames.

Related cross-sibling drift (NOT addressed by this fix)

The api-consistency sweep also surfaced a return-type drift in the writer trio:

• to_geotiff(...) -> None
• write_geotiff_gpu(...) -> None
• write_vrt(...) -> str

write_vrt returns the written path while the two geotiff writers return None. A caller forwarding the same args to either entry point sees different return types. Tracking separately because changing either side is a behaviour change and needs its own deprecation discussion.

Discovered by

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