Annotate open_geotiff(source) as str | BinaryIO (#1754)

[brendancol]

Summary

Closes #1754. The api-consistency sweep on 2026-05-12 found that
open_geotiff(source, ...) lacks a str | BinaryIO type annotation
even though the docstring documents str or binary file-like and the
runtime accepts BytesIO buffers. Sibling reader functions
(read_geotiff_gpu, read_geotiff_dask, read_vrt) are annotated
source: str because they reject file-like sources. The writer entry
points (to_geotiff, write_geotiff_gpu) carry path: str | BinaryIO
for the same file-like-or-string surface that open_geotiff exposes.

PR #1654 closed annotation gaps across window, path, and
on_gpu_failure but skipped source on open_geotiff. This PR
finishes the job.

Detail

• xrspatial/geotiff/__init__.py: annotate
  open_geotiff(source: str | BinaryIO, ...). BinaryIO is already
  imported under TYPE_CHECKING in this module since PR Public geotiff API: type annotations missing on window / path / on_gpu_failure #1654, so the
  runtime import cost stays at zero with
  from __future__ import annotations.
• xrspatial/geotiff/tests/test_signature_annotations_1654.py: four
  new pins covering source on all four reader entry points
  (open_geotiff accepts both str and BinaryIO; the dedicated readers
  stay str-only), plus a runtime smoke test that a BytesIO source
  round-trips through open_geotiff.
• .claude/sweep-api-consistency-state.csv: v3 sweep row with the
  finding metadata.

Annotation-only change. No runtime behaviour, no defaults, no kwarg
renames. No deprecation impact.

Test plan

• pytest xrspatial/geotiff/tests/test_signature_annotations_1654.py -v
  passes all 16 tests (existing 12 + 4 new pins).
• pytest xrspatial/geotiff/tests/test_namespace_no_leak_1708.py xrspatial/geotiff/tests/test_open_geotiff_on_gpu_failure_1615.py xrspatial/geotiff/tests/test_signature_annotations_1654.py -v
  passes 30/30.
• CUDA-validated host: GPU read/write smoke tests work unchanged.

[Copilot]

Pull request overview

This PR completes a public API type-hint parity fix in xrspatial.geotiff by annotating open_geotiff(source, ...) to reflect its documented and supported ability to accept either a string path/URI or a binary file-like object (e.g., io.BytesIO). It also adds regression tests to pin the source annotations across the reader entry points and a small runtime smoke test ensuring BytesIO inputs continue to work.

Changes:

• Annotate open_geotiff(source) as str | BinaryIO (consistent with docstring and runtime behavior).
• Add tests that pin source annotations for open_geotiff, read_geotiff_dask, read_geotiff_gpu, and read_vrt, plus a runtime BytesIO smoke test.
• Update the API-consistency sweep state CSV to record the resolved finding.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
xrspatial/geotiff/__init__.py	Adds `source: str
xrspatial/geotiff/tests/test_signature_annotations_1654.py	Adds annotation “pins” for source across reader functions and a runtime test verifying open_geotiff(BytesIO(...)) works.
.claude/sweep-api-consistency-state.csv	Records sweep v3 finding (#1754) as filed and fixed.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.