geotiff: open_geotiff(max_cloud_bytes=...) missing type annotation

[brendancol]

Found by deep-sweep api-consistency on 2026-05-18.

Issue

xrspatial.geotiff.open_geotiff is the only kwarg on the public signature without a Python type annotation. Every other kwarg on the function (and every kwarg on every other public reader/writer in the module) has one.

>>> import inspect, xrspatial.geotiff as g
>>> sig = inspect.signature(g.open_geotiff)
>>> for n, p in sig.parameters.items():
...     ann = "NO-HINT" if p.annotation is inspect.Parameter.empty else str(p.annotation)
...     print(f"{n}: {ann}")
source: str | BinaryIO
dtype: str | np.dtype | None
window: tuple | None
overview_level: int | None
band: int | None
name: str | None
chunks: int | tuple | None
gpu: bool
max_pixels: int | None
max_cloud_bytes: NO-HINT      <-- only kwarg without an annotation
on_gpu_failure: str
missing_sources: str
allow_rotated: bool
allow_unparseable_crs: bool
band_nodata: str | None
mask_nodata: bool

The docstring already declares the type:

max_cloud_bytes : int or None, optional

so the surface and the docs disagree. inspect.signature, IDE autocomplete, Sphinx output, and mypy --strict all see a bare parameter for the only fsspec-related kwarg on the public read entry point.

The default is the module-internal _MAX_CLOUD_BYTES_SENTINEL (used so the function can distinguish "caller passed nothing" from "caller passed None"); the annotation should still be int | None to match the docstring and what callers actually pass.

Cat / Severity

API Consistency Cat 3 (type hints and docstrings), severity MEDIUM. Type annotation is missing on a public function while sibling parameters in the same function -- and every other public read/write entry point in the module -- have them.

Fix

Add int | None annotation to max_cloud_bytes on open_geotiff. No behaviour change; the sentinel default is preserved. Regression test imports open_geotiff and asserts inspect.signature(...)'s annotation on the kwarg is non-empty so the gap cannot reopen.

Out of scope

• Renaming or default change. Default stays the sentinel; semantics unchanged.
• Other geotiff entry points: every other kwarg on every other public reader/writer already has an annotation, so no follow-up rows to address.