Reason or Problem
Epic #2340 defines the GeoTIFF release contract and proposes a tiering: Stable, Advanced, Experimental, Internal-only. SUPPORTED_FEATURES in xrspatial/geotiff/_attrs.py is the single source of truth that docs, the user-guide notebook, and writer gates read from. Its contents need to be reconciled with the epic so the public surface matches the release promise.
Proposal
Audit SUPPORTED_FEATURES against epic #2340 and fix the drift.
Tier shape per epic:
- Stable: local GeoTIFF r/w, COG r/w for lossless codecs (none/deflate/lzw/packbits/zstd), CRS/transform/nodata attrs, windowed reads, dask reads where parity-tested.
- Advanced: simple VRT mosaics, HTTP/fsspec reads, external
.ovr sidecars, BigTIFF, overview generation/selection.
- Experimental: GPU r/w, LERC/J2K/LZ4, explicit-CRS permissive escape hatches.
- Internal-only: JPEG-in-TIFF.
Concrete changes:
- Add
reader.windowed at stable. The window-read tests in xrspatial/geotiff/tests/ already cover it.
- Add
reader.dask at stable. test_backend_parity_matrix.py and test_backend_full_parity_2211.py cover it.
- Demote
reader.allow_unparseable_crs from advanced to experimental. The epic places explicit-CRS permissive escape hatches in Experimental.
- Demote
reader.allow_rotated from advanced to experimental. The rotated read path is an opt-in escape hatch and the epic lists rotated writes as Unsupported, so the read-side opt-in sits in Experimental.
- Add a shape unit test under
xrspatial/geotiff/tests/ that asserts every entry carries a tier label and the tier set is closed ({stable, advanced, experimental, internal_only}). Future drift fails CI.
- Add a CHANGELOG entry.
Out of scope, handled by sibling PRs under epic #2340:
- Docstring rewrites for public read/write entry points.
- Docs page or feature-tier table in
docs/source/.
- New opt-in enforcement on experimental paths.
Stakeholders and Impacts
GeoTIFF module callers who read SUPPORTED_FEATURES to gate optional features. The change is metadata-only. Runtime behaviour of every read/write path stays put. Downstream code that asserted SUPPORTED_FEATURES['reader.allow_rotated'] == 'advanced' will see 'experimental' after this PR. That string is the only break.
Drawbacks
This is a public-API change to a documented constant. Callers gating on the exact string value have to update.
Alternatives
Leave the constant alone and document the drift in release notes. The epic asks for the constant to match the release contract, so this defeats the point.
Additional Notes or Context
Parent epic: #2340. PR 1 of 6.
Reason or Problem
Epic #2340 defines the GeoTIFF release contract and proposes a tiering: Stable, Advanced, Experimental, Internal-only.
SUPPORTED_FEATURESinxrspatial/geotiff/_attrs.pyis the single source of truth that docs, the user-guide notebook, and writer gates read from. Its contents need to be reconciled with the epic so the public surface matches the release promise.Proposal
Audit
SUPPORTED_FEATURESagainst epic #2340 and fix the drift.Tier shape per epic:
.ovrsidecars, BigTIFF, overview generation/selection.Concrete changes:
reader.windowedatstable. The window-read tests inxrspatial/geotiff/tests/already cover it.reader.daskatstable.test_backend_parity_matrix.pyandtest_backend_full_parity_2211.pycover it.reader.allow_unparseable_crsfromadvancedtoexperimental. The epic places explicit-CRS permissive escape hatches in Experimental.reader.allow_rotatedfromadvancedtoexperimental. The rotated read path is an opt-in escape hatch and the epic lists rotated writes as Unsupported, so the read-side opt-in sits in Experimental.xrspatial/geotiff/tests/that asserts every entry carries a tier label and the tier set is closed ({stable, advanced, experimental, internal_only}). Future drift fails CI.Out of scope, handled by sibling PRs under epic #2340:
docs/source/.Stakeholders and Impacts
GeoTIFF module callers who read
SUPPORTED_FEATURESto gate optional features. The change is metadata-only. Runtime behaviour of every read/write path stays put. Downstream code that assertedSUPPORTED_FEATURES['reader.allow_rotated'] == 'advanced'will see'experimental'after this PR. That string is the only break.Drawbacks
This is a public-API change to a documented constant. Callers gating on the exact string value have to update.
Alternatives
Leave the constant alone and document the drift in release notes. The epic asks for the constant to match the release contract, so this defeats the point.
Additional Notes or Context
Parent epic: #2340. PR 1 of 6.