diff --git a/xrspatial/geotiff/__init__.py b/xrspatial/geotiff/__init__.py index 0eaf86cf2..a03fbdb4a 100644 --- a/xrspatial/geotiff/__init__.py +++ b/xrspatial/geotiff/__init__.py @@ -719,18 +719,24 @@ def open_geotiff(source: str | BinaryIO, *, sentinels (e.g. external tooling that writes ``"nan"`` on integer outputs). stable_only : bool, default False - [advanced] Read-side opt-in for stable-tier sources only. When - ``True``, a ``.vrt`` source raises + [advanced] Read-side opt-in that restricts the read to the + stable-tier local-file path. When ``True``, advanced-tier + sources are rejected: a ``.vrt`` source raises :class:`VRTStableSourcesOnlyError` because ``reader.vrt`` and the VRT child-source pipeline sit at the ``advanced`` / ``experimental`` tiers in - :data:`xrspatial.geotiff.SUPPORTED_FEATURES`. Non-VRT sources - on this entry point already ride the stable ``reader.local_file`` - path and the per-source codec gate, so the flag is a no-op for - them. The rejection names the file path and the + :data:`xrspatial.geotiff.SUPPORTED_FEATURES`, and HTTP / + fsspec sources (``http(s)://``, ``s3://``, etc.) are rejected + too because ``reader.http`` and ``reader.fsspec`` are also + ``advanced``. Only a local-file source riding the stable + ``reader.local_file`` path and the per-source codec gate is + accepted. The rejection names the offending source and the ``allow_experimental_codecs`` opt-in so the caller can unlock the broader tier set explicitly when needed. See - ``docs/source/reference/release_gate_geotiff.rst``. + ``docs/source/reference/release_gate_geotiff.rst``. The VRT + rejection is enforced today; the HTTP / fsspec rejection is the + documented contract being rolled out and may not yet fire on + every read path (tracked in issue #2820). allow_experimental_codecs : bool, default False Read-side opt-in for sources compressed with the Tier 3 experimental codecs (``lerc``, ``jpeg2000`` / ``j2k``, ``lz4``). diff --git a/xrspatial/geotiff/_backends/dask.py b/xrspatial/geotiff/_backends/dask.py index c4958e45b..1fc47f4eb 100644 --- a/xrspatial/geotiff/_backends/dask.py +++ b/xrspatial/geotiff/_backends/dask.py @@ -126,12 +126,16 @@ def read_geotiff_dask(source: str, *, ``InvalidIntegerNodataError`` at graph-build time. See ``open_geotiff`` for the full description. stable_only : bool, default False - [advanced] Read-side opt-in for stable-tier sources only. - Forwarded to ``read_vrt`` when the source ends in ``.vrt`` so - the rejection fires at graph-build time. Non-VRT sources on - this entry point already ride the stable ``reader.local_file`` - path, so the flag is a no-op for them. See ``open_geotiff`` for - the full description. + [advanced] Read-side opt-in that restricts the read to the + stable-tier local-file path. Forwarded to ``read_vrt`` when the + source ends in ``.vrt`` so the rejection fires at graph-build + time. Advanced-tier sources (VRT, and HTTP / fsspec sources + such as ``http(s)://`` or ``s3://``) are rejected; only a + local-file source on the stable ``reader.local_file`` path is + accepted. The VRT rejection is enforced today; the HTTP / + fsspec rejection is the documented contract being rolled out + (tracked in issue #2820). See ``open_geotiff`` for the full + description. allow_experimental_codecs : bool, default False [advanced] Read-side opt-in for Tier 3 experimental codecs (``lerc``, ``jpeg2000`` / ``j2k``, ``lz4``). Fires at graph