Add VRT missing source policy

[brendancol]

Closes #1799.\n\nAdds read_vrt(missing_sources=...) with warn and raise modes, preserving historical warn behavior while giving pipelines an explicit fail-fast option.\n\nTested: pytest xrspatial/geotiff/tests/test_vrt_missing_sources_policy_1799.py

[Copilot]

Pull request overview

This PR adds an explicit, API-level policy to control how read_vrt handles unreadable/missing VRT source files, preserving the historical “warn and continue” behavior by default while enabling a fail-fast option for production pipelines (closes #1799).

Changes:

• Add missing_sources={'warn','raise'} parameter to both internal VRT assembly and the public xrspatial.geotiff.read_vrt API.
• Validate missing_sources values and implement fail-fast behavior when set to 'raise'.
• Add tests and reference documentation describing the new policy.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
xrspatial/geotiff/_vrt.py	Adds missing_sources handling to the internal VRT reader and integrates it with the existing strict-mode behavior.
xrspatial/geotiff/__init__.py	Exposes missing_sources on the public read_vrt API and forwards it to the internal reader; documents the new parameter.
xrspatial/geotiff/tests/test_vrt_missing_sources_policy_1799.py	Adds regression tests for warn vs raise behavior and policy validation.
docs/source/reference/geotiff.rst	Documents the new missing-source policy option for VRT reads.

Comments suppressed due to low confidence (1)

xrspatial/geotiff/_vrt.py:907

• The fallback warning text still suggests only XRSPATIAL_GEOTIFF_STRICT=1 as the way to raise on unreadable VRT sources. Now that missing_sources='raise' exists, the warning message should mention that option as well (otherwise users may miss the new API-level fail-fast control).

                    f"VRT source {src.filename!r} could not be read "
                    f"({type(e).__name__}: {e}); skipping. The output "
                    f"mosaic will have a hole at this tile. Inspect "
                    f"``DataArray.attrs['vrt_holes']`` or set "
                    f"XRSPATIAL_GEOTIFF_STRICT=1 to raise instead.",

---

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