geotiff: write_vrt's first positional kwarg vrt_path drifts from to_geotiff/write_geotiff_gpu path

[brendancol]

Summary

xrspatial.geotiff exposes three writers whose docstrings advertise themselves as parity siblings: to_geotiff, write_geotiff_gpu, and write_vrt. The first two use path as the destination kwarg; write_vrt uses vrt_path. A caller using write_vrt(path=...) hits TypeError: write_vrt() got an unexpected keyword argument 'path' even though the rest of the writer trio accepts path=.

from xrspatial.geotiff import to_geotiff, write_geotiff_gpu, write_vrt
import inspect

print(list(inspect.signature(to_geotiff).parameters)[:2])         # ['data', 'path']
print(list(inspect.signature(write_geotiff_gpu).parameters)[:2])  # ['data', 'path']
print(list(inspect.signature(write_vrt).parameters)[:2])          # ['vrt_path', 'source_files']

Severity

MEDIUM. Cat 1 (parameter naming drift) per the API consistency sweep. Both names exist in the public API, but most callers use the positional form (sweep grep through xrspatial/geotiff/tests/ finds zero vrt_path= kwargs), so the real-world impact is small. Renaming is a breaking change, so the fix is a deprecation shim.

Proposed fix

1. Add a path keyword-only alias on write_vrt. Accept either path or vrt_path; emit DeprecationWarning on vrt_path calls; raise TypeError if both are supplied.
2. Update the docstring to lead with path, retain vrt_path under a deprecated note for the historical alias.
3. Regression test that pins both names work and that the deprecation warning fires.

Detected by the deep-sweep-api-consistency sweep on 2026-05-15.