geotiff: deprecate matplotlib colormap variants in DataArray.attrs (#1984) (#2014)

* geotiff: deprecate matplotlib colormap variants in DataArray.attrs (#1984)

Issue #1984 PR 7. The reader emits ``attrs['cmap']`` (when matplotlib
is importable) and ``attrs['colormap_rgba']`` whenever the source file
declares Photometric=3 (palette). The writer never selects
Photometric=3 from attrs alone, so PR 6 (#2004) locked the round-trip
drop for both keys as part of the attrs-contract pass-through tier.

This PR deprecates the read-side emission of both keys for one
release cycle. Callers who want a matplotlib ListedColormap should
build one from the canonical ``attrs['colormap']`` (raw uint16 RGB
triples from TIFF tag 320) instead. ``attrs['colormap']`` is the
canonical-tier replacement and is intentionally kept: it round-trips
through ``_merge_friendly_extra_tags`` already.

During the deprecation window both attrs still land on the returned
DataArray; only a DeprecationWarning is added. Removal is a follow-up
PR. The new attrs-contract docstring split moves both keys into a
"Deprecated" section so the contract stays explicit about which keys
have a future.

The new test file
``xrspatial/geotiff/tests/test_attrs_pr7_deprecate_colormap_variants_1984.py``
pins three behaviours: the warning fires on a Photometric=3 fixture
for ``colormap_rgba`` (always) and for ``cmap`` (when matplotlib is
installed); the attrs are still emitted; the plain
``attrs['colormap']`` key is unaffected.

Existing tests that read palette fixtures (the TestPalette block in
``test_features.py`` and ``test_colormap_round_trip`` in
``test_metadata_round_trip_1484.py``) ignore the new DeprecationWarning
locally to keep their reports clean.

* geotiff: factor shared _emit_deprecated_geokey_attr helper

PR review on #2014 flagged that the three colormap deprecation sites
copy-paste the same nine-line ``warnings.warn(...)`` block with only
the attr name and migration hint varying. Sibling PRs #2010 / #2013
have the same shape; PR #2011 already factors a slice-specific
helper. Introduce a generic helper in ``_attrs.py`` so all four PR 7
slices can share it.

``_emit_deprecated_geokey_attr(attrs, name, value, *, reason,
migration=None)`` builds the canonical warning text shape:

    xrspatial.geotiff: attrs['<name>'] is deprecated; <reason>.
    [<migration>.] It will be removed in a future release. See
    issue #1984.

then sets ``attrs[name] = value`` (read-side emission still alive for
the deprecation window). ``stacklevel=2`` lands the warning at the
caller of ``_populate_attrs_from_geo_info``; ``DeprecationWarning`` is
silenced for library code by default in Python's filters, so this is
mainly visible to test runners and developers who opt in.

The colormap-variants deprecation now routes ``cmap`` and the two
``colormap_rgba`` branches (matplotlib present + ImportError fallback)
through the helper, replacing 27 lines of copy-paste with three
calls. The emitted warning text is byte-identical to the previous
inline strings, so the existing tests (``pytest.warns`` plus the
TestPalette / test_metadata_round_trip filter regexes) keep passing
unchanged.

Sibling PRs #2010 and #2013 can adopt the helper on rebase; #2011's
existing geographic-specific helper can be inlined onto this one in
a follow-up.

Test plan:
- pytest xrspatial/geotiff/tests/test_attrs_pr7_deprecate_colormap_variants_1984.py -- 4 passed.
- pytest xrspatial/geotiff/tests/test_attrs_contract_*_1984.py xrspatial/geotiff/tests/test_metadata_round_trip_1484.py -- 57 passed.
- pytest xrspatial/geotiff/tests/test_features.py::TestPalette -- 7 passed.

* geotiff: address self-review on shared deprecation helper

Self-review on PR #2014 flagged one blocker and two suggestions on
the shared-helper refactor. This commit addresses them.

Blocker -- ``stacklevel`` regression (``_attrs.py:179``):
    Wrapping the inline ``warnings.warn(..., stacklevel=2)`` call in
    a helper shifted the warning location by one frame; the warning
    was surfacing at ``_attrs.py`` (the helper call site) instead of
    at the backend that called ``_populate_attrs_from_geo_info``.
    Bumped ``stacklevel=2`` to ``stacklevel=3`` so the warning is
    attributed to the backend frame, matching the pre-refactor
    behaviour (verified empirically: warning now surfaces at
    ``xrspatial/geotiff/__init__.py:518`` instead of ``_attrs.py:350``).

Suggestion -- helper name (``_attrs.py:152``):
    Renamed ``_emit_deprecated_geokey_attr`` to ``_emit_deprecated_attr``
    because the colormap variants (cmap, colormap_rgba) come from
    TIFF tag 320 (ColorMap), not from a GeoKey. The new name covers
    every PR 7 slice; docstring notes why the ``_geokey_`` qualifier
    was dropped.

Suggestion -- user-guide doc:
    Added a new "Deprecated keys" section to
    ``docs/source/user_guide/attrs_contract.rst`` so users reading
    the contract page see the new tier alongside the existing
    canonical / compatibility-alias / pass-through tiers. Mirrors
    the module docstring.

Suggestion -- direct unit test for the helper:
    Added ``test_emit_deprecated_attr_with_migration_text`` and
    ``test_emit_deprecated_attr_without_migration_text``. The first
    pins the exact warning text shape; the second pins the
    ``migration=None`` branch which the existing colormap tests do
    not exercise.

Nit -- migration hints:
    Lifted ``_colormap_reason`` / ``_colormap_migration`` to module-
    level constants and split them into ``_DEPRECATED_COLORMAP_REASON``,
    ``_DEPRECATED_CMAP_MIGRATION``, and
    ``_DEPRECATED_COLORMAP_RGBA_MIGRATION``. The new
    ``colormap_rgba``-specific migration ("Reshape attrs['colormap']
    to (n_colors, 3) and append an alpha channel") is more direct
    than the previous shared ``ListedColormap`` hint, which only
    matched ``cmap`` cleanly.

Test plan:
- pytest test_attrs_pr7_deprecate_colormap_variants_1984.py (6 passed)
- pytest test_attrs_contract_*_1984.py test_metadata_round_trip_1484.py
  test_features.py::TestPalette -- 70 passed total

Author: brendancol

CHANGELOG.md

@@ -11,6 +11,7 @@
 - Refresh the geotiff mmap cache when a file is replaced under the same path so re-reads after an atomic-rename overwrite no longer return stale bytes
 - Decode TIFF predictor=3 un-transpose by file byte order so big-endian floating-point TIFFs read back exactly
 - Default internal `_vrt.read_vrt` `missing_sources` to `'raise'` so an unreadable VRT source no longer produces a silent zero-fill hole on integer rasters; pass `missing_sources='warn'` to opt back into the previous lenient behaviour (#1843)
+- Deprecate read-side emission of matplotlib colormap-derived attrs (cmap, colormap_rgba) on palette TIFFs; the writer cannot set Photometric=3 so they do not round-trip. Construct ListedColormap from attrs['colormap'] in caller code. These attrs still emit for now but trigger a DeprecationWarning. Removal planned for a future release. (#1984)
 
 
 ### Version 0.9.9 - 2026-05-05

docs/source/user_guide/attrs_contract.rst

@@ -180,15 +180,38 @@ must not assume a specific pass-through key survives a round-trip.
    * - ``colormap``
      - tuple
      - Raw ``ColorMap`` TIFF tag (tag id 320) values.
+
+
+Deprecated keys
+===============
+
+These keys are still emitted on read for one release cycle, but each
+emission triggers a ``DeprecationWarning``. The writer cannot
+reconstruct them from canonical attrs, so they do not round-trip.
+Callers should migrate to the canonical alternative listed below
+before the warning-only window closes. See issue #1984.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 22 18 60
+
+   * - Key
+     - Type
+     - Definition and migration
    * - ``colormap_rgba``
      - array
-     - Decoded RGBA colormap. Emitted only when the file's photometric
-       interpretation is ``Photometric == 3`` (palette).
+     - Decoded RGBA colormap. Emitted on read when the file's
+       photometric interpretation is ``Photometric == 3`` (palette).
+       The writer cannot set ``Photometric == 3`` so the attr does
+       not round-trip. Reshape ``attrs['colormap']`` to
+       ``(n_colors, 3)`` and append an alpha channel in caller code
+       if needed.
    * - ``cmap``
      - ``matplotlib.colors.ListedColormap``
-     - Matplotlib colormap built from ``colormap_rgba``. Present only
-       when matplotlib is importable and the same ``Photometric == 3``
-       gate is satisfied.
+     - Matplotlib colormap built from the palette. Same
+       ``Photometric == 3`` gate, same round-trip gap. Construct a
+       ``ListedColormap`` from ``attrs['colormap']`` in caller code
+       if needed.
 
 
 Round-trip invariants

xrspatial/geotiff/_attrs.py

@@ -63,8 +63,8 @@
 
 - ``image_description``: TIFF ImageDescription tag.
 - ``extra_samples``: TIFF ExtraSamples tag.
-- ``colormap``, ``colormap_rgba``, ``cmap``: palette data attached to
-  single-band paletted images.
+- ``colormap``: raw uint16 RGB triples from the TIFF ColorMap tag (320),
+  attached to single-band paletted images.
 
 Deprecated (will be removed in a future release; see issue #1984):
 
@@ -103,6 +103,17 @@
   reason as ``vertical_crs``.
 - ``vertical_units``: VerticalUnitsGeoKey value. Same deprecation reason
   as ``vertical_crs``.
+Colormap variants (different root cause: photometric gate, not GeoKey):
+
+- ``colormap_rgba``: RGBA palette array, only emitted on read when the
+  source file is Photometric==3 (palette). The writer never selects
+  Photometric=3, so this attr does not round-trip. Reshape
+  ``attrs['colormap']`` to ``(n_colors, 3)`` and append an alpha
+  channel in caller code if needed.
+- ``cmap``: matplotlib ``ListedColormap`` built from the palette. Same
+  Photometric==3 gate, same round-trip gap. Construct a
+  ``ListedColormap`` from ``attrs['colormap']`` in caller code if
+  needed.
 
 Migration recipe (the canonical replacement is ``crs`` / ``crs_wkt``
 plus a one-liner with :mod:`pyproj` when a derived value is needed)::
@@ -208,6 +219,25 @@
 )
 
 
+# Shared wording for the colormap-variants slice of the PR 7 deprecation
+# series. The root cause is a different one (the writer cannot set
+# ``Photometric=3``) so the GeoKey-tier reason templates above don't
+# fit; these constants are spliced into ``_emit_deprecated_attr`` with
+# a per-attr migration recipe so users see how to derive an RGBA palette
+# or matplotlib ``ListedColormap`` from canonical ``attrs['colormap']``.
+_DEPRECATED_COLORMAP_REASON = (
+    "the writer cannot set Photometric=3 so it does not round-trip"
+)
+_DEPRECATED_CMAP_MIGRATION = (
+    "Construct a ListedColormap from attrs['colormap'] in caller code "
+    "if needed"
+)
+_DEPRECATED_COLORMAP_RGBA_MIGRATION = (
+    "Reshape attrs['colormap'] to (n_colors, 3) and append an alpha "
+    "channel in caller code if needed"
+)
+
+
 def _deprecated_geokey_warning(name: str, *, reason: str) -> str:
     """Warning text for a deprecated GeoKey-derived attr.
 
@@ -332,6 +362,54 @@ def _emit_deprecated_geographic_geokey(attrs: dict, name: str, value) -> None:
     )
 
 
+def _emit_deprecated_attr(
+    attrs: dict,
+    name: str,
+    value,
+    *,
+    reason: str,
+    migration: str | None = None,
+) -> None:
+    """Emit a deprecated attr with a ``DeprecationWarning`` and a
+    per-attr migration recipe.
+
+    Sibling of :func:`_emit_deprecated_geokey_attr` that adds support
+    for an optional ``migration`` clause spliced into the warning. The
+    GeoKey-tier helper uses a fixed sentence ("... so it will not
+    round-trip ..."); the colormap-variants tier needs to point users
+    at how to derive an RGBA palette or matplotlib ``ListedColormap``
+    from canonical ``attrs['colormap']``, which doesn't fit that
+    template. A follow-up may unify the two helpers; for now they live
+    side-by-side because the warning-text contracts are pinned by
+    separate test suites and converging them is out of scope for the
+    colormap slice.
+
+    Warning text shape::
+
+        xrspatial.geotiff: attrs['<name>'] is deprecated; <reason>
+        <migration?> It will be removed in a future release. See
+        issue #1984.
+
+    The ``stacklevel`` is taken from
+    :func:`_stacklevel_to_external_caller` so the warning is attributed
+    to the user's call site, matching the GeoKey-tier slices.
+    """
+    parts = [
+        f"xrspatial.geotiff: attrs[{name!r}] is deprecated;",
+        reason.rstrip('.') + '.',
+    ]
+    if migration:
+        parts.append(migration.rstrip('.') + '.')
+    parts.append("It will be removed in a future release. See issue #1984.")
+    warnings.warn(
+        ' '.join(parts),
+        DeprecationWarning,
+        stacklevel=_stacklevel_to_external_caller(),
+    )
+    attrs[name] = value
+
+
+
 def _extent_to_window(transform, file_height, file_width,
                       y_min, y_max, x_min, x_max):
     """Convert geographic extent to pixel window (row_start, col_start, row_stop, col_stop).
@@ -513,11 +591,23 @@ def _populate_attrs_from_geo_info(attrs: dict, geo_info, *, window=None) -> None
     if geo_info.colormap is not None:
         try:
             from matplotlib.colors import ListedColormap
-            attrs['cmap'] = ListedColormap(
-                geo_info.colormap, name='tiff_palette')
-            attrs['colormap_rgba'] = geo_info.colormap
+            _emit_deprecated_attr(
+                attrs, 'cmap',
+                ListedColormap(geo_info.colormap, name='tiff_palette'),
+                reason=_DEPRECATED_COLORMAP_REASON,
+                migration=_DEPRECATED_CMAP_MIGRATION,
+            )
+            _emit_deprecated_attr(
+                attrs, 'colormap_rgba', geo_info.colormap,
+                reason=_DEPRECATED_COLORMAP_REASON,
+                migration=_DEPRECATED_COLORMAP_RGBA_MIGRATION,
+            )
         except ImportError:
-            attrs['colormap_rgba'] = geo_info.colormap
+            _emit_deprecated_attr(
+                attrs, 'colormap_rgba', geo_info.colormap,
+                reason=_DEPRECATED_COLORMAP_REASON,
+                migration=_DEPRECATED_COLORMAP_RGBA_MIGRATION,
+            )
 
     if geo_info.extra_tags is not None:
         for _tag_id, _tt, _tc, _tv in geo_info.extra_tags: