Skip to content

Align SUPPORTED_FEATURES with epic #2340 tiering #2348

@brendancol

Description

@brendancol

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    apiAPI design and consistencyenhancementNew feature or requestgeotiffGeoTIFF module

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions