Split SUPPORTED_FEATURES into writer.cog / reader.local_cog / reader.http_cog (#2291)

xrspatial/geotiff/_attrs.py

@@ -195,6 +195,16 @@
 # See ``xrspatial/geotiff/__init__.py`` for the per-tier semantics; the
 # inline comments here track the codec/reader/writer split used by the
 # user-guide notebook table.
+#
+# COG entries are split into three keys (issue #2291, part of the #2286
+# rollout) so the writer, local reader, and HTTP reader can move between
+# tiers on their own track. The three code paths have different stability
+# profiles: the writer emits a self-contained COG layout, the local reader
+# parses overview IFDs out of an on-disk file, and the HTTP reader adds
+# range-request fetching and partial-IFD handling on top of that. Folding
+# them into a single ``cog`` key would tie a promotion of any one path to
+# a promotion of all three. The keys carry no behaviour today; production
+# code still gates on the underlying writer / reader options.
 SUPPORTED_FEATURES = {
     # Codecs. Tier 1 lossless integer + float byte-for-byte round-trip.
     'codec.none': 'stable',
@@ -218,6 +228,12 @@
     'reader.sidecar_ovr': 'advanced',
     'reader.allow_rotated': 'advanced',
     'reader.allow_unparseable_crs': 'advanced',
+    # COG reader paths (issue #2291): split out from the previous
+    # single COG concept (which only carried ``writer.cog``) so the
+    # local and HTTP reader variants can promote independently of the
+    # writer and of each other.
+    'reader.local_cog': 'advanced',
+    'reader.http_cog': 'advanced',
     'reader.gpu': 'experimental',
     # Write paths.
     'writer.local_file': 'stable',

xrspatial/geotiff/tests/test_supported_features_tiers_2137.py

@@ -102,6 +102,25 @@ def test_supported_features_is_a_mapping():
         assert tier in _TIER_VALUES, (name, tier)
 
 
+def test_supported_features_has_split_cog_keys():
+    """The COG entry is split into three keys (issue #2291) so the
+    writer, local reader, and HTTP reader can promote between tiers on
+    independent tracks. All three keys must resolve in
+    ``SUPPORTED_FEATURES`` with a known tier label.
+
+    Pinned here so a future refactor that folds the keys back together
+    has to update the docs, the notebook, and this test in one commit.
+    """
+    for key in ('writer.cog', 'reader.local_cog', 'reader.http_cog'):
+        assert key in SUPPORTED_FEATURES, (
+            f"{key!r} missing from SUPPORTED_FEATURES; the split was "
+            "introduced in #2291 and must stay surfaced so the writer / "
+            "local reader / HTTP reader tracks stay independent."
+        )
+        assert SUPPORTED_FEATURES[key] in _TIER_VALUES, (
+            key, SUPPORTED_FEATURES[key])
+
+
 def test_supported_features_covers_every_valid_codec():
     """Every codec name in ``_VALID_COMPRESSIONS`` carries a tier in
     ``SUPPORTED_FEATURES``. The gate cannot silently miss a codec.