Summary
build_vrt is public right now: it's in __all__, it's documented, and it has a row in the README feature matrix. It takes a list of existing GeoTIFF files and writes a VRT mosaic index over them. I'd like to drop it from the public API and keep it as an internal helper that only runs when to_geotiff writes a .vrt path.
Motivation
The public GeoTIFF surface is open_geotiff / to_geotiff / build_vrt. The first two are read and write. build_vrt is the odd one out because it doesn't take a DataArray at all, it just indexes files already sitting on disk. Anyone who wants a VRT mosaic from xrspatial-written tiles already gets one by writing to a .vrt path with to_geotiff, so the second entry point adds contract surface without adding much most people need.
The giveaway: to_geotiff's .vrt branch (_write_vrt_tiled) doesn't even call build_vrt. It calls _vrt.write_vrt directly. So build_vrt is public API with no internal caller.
Proposed change
- Rename the wrapper
build_vrt to _build_vrt and drop it from __all__ and the package docstring.
- Point
to_geotiff's VRT write path (_write_vrt_tiled) at _build_vrt so there's a single internal entry point for emitting the VRT index.
- Pull
build_vrt out of the docs reference, the README feature matrix, and the release-gate contract table.
- Update the tests that import the public name to use
_build_vrt, and flip the API-surface assertion to expect just open_geotiff and to_geotiff.
Compatibility
build_vrt is advanced-tier, not stable, so it's allowed to change between releases. Anyone calling xrspatial.geotiff.build_vrt directly will need to either write to a .vrt path through to_geotiff or import _build_vrt.
Backend coverage
No behavior changes. VRT writing already runs on the eager and dask paths; this is an API-surface refactor.
Summary
build_vrtis public right now: it's in__all__, it's documented, and it has a row in the README feature matrix. It takes a list of existing GeoTIFF files and writes a VRT mosaic index over them. I'd like to drop it from the public API and keep it as an internal helper that only runs whento_geotiffwrites a.vrtpath.Motivation
The public GeoTIFF surface is
open_geotiff/to_geotiff/build_vrt. The first two are read and write.build_vrtis the odd one out because it doesn't take a DataArray at all, it just indexes files already sitting on disk. Anyone who wants a VRT mosaic from xrspatial-written tiles already gets one by writing to a.vrtpath withto_geotiff, so the second entry point adds contract surface without adding much most people need.The giveaway:
to_geotiff's.vrtbranch (_write_vrt_tiled) doesn't even callbuild_vrt. It calls_vrt.write_vrtdirectly. Sobuild_vrtis public API with no internal caller.Proposed change
build_vrtto_build_vrtand drop it from__all__and the package docstring.to_geotiff's VRT write path (_write_vrt_tiled) at_build_vrtso there's a single internal entry point for emitting the VRT index.build_vrtout of the docs reference, the README feature matrix, and the release-gate contract table._build_vrt, and flip the API-surface assertion to expect justopen_geotiffandto_geotiff.Compatibility
build_vrtis advanced-tier, not stable, so it's allowed to change between releases. Anyone callingxrspatial.geotiff.build_vrtdirectly will need to either write to a.vrtpath throughto_geotiffor import_build_vrt.Backend coverage
No behavior changes. VRT writing already runs on the eager and dask paths; this is an API-surface refactor.