geotiff: document attrs tier classification in _attrs.py (#1984)

[brendancol]

Summary

PR 1 of 7 from the implementation plan on issue #1984.

Documents the three-tier attrs contract in the module docstring of xrspatial/geotiff/_attrs.py. Docstring-only; no behaviour change.

The three tiers are:

• Canonical: keys xrspatial owns and round-trips without loss (crs, crs_wkt, transform, nodata, raster_type, extra_tags, gdal_metadata, gdal_metadata_xml, x_resolution, y_resolution, resolution_unit, _xrspatial_geotiff_contract).
• Compatibility alias: read for ecosystem interop, never emitted by writers when the canonical key is present (nodatavals from rioxarray, _FillValue from CF).
• Best-effort pass-through: preserved when the writer can reconstruct from canonical state, otherwise dropped (GeoKey-derived fields, image_description, extra_samples, colormap variants).

The contract version key _xrspatial_geotiff_contract is referenced in the docstring; population of that key lands in a later PR in the series.

Note on nodata

Issue #1988 (declared-vs-masked nodata split) is a prerequisite for tightening the nodata canonical semantics. The docstring records the intended semantics post-#1988: nodata is the declared file sentinel as stored in the GDAL_NODATA tag.

Test plan

• pytest xrspatial/geotiff/tests/test_attrs_parity_1548.py -x -q (5 passed)

[brendancol]

PR Review: geotiff: document attrs tier classification in _attrs.py

Blockers (must fix before merge)

• xrspatial/geotiff/_attrs.py:27 — the transform definition is wrong. The docstring says tuple of (origin_x, origin_y, pixel_width, pixel_height) (a 4-tuple), but the value emitted by _transform_tuple_from_pixel_geometry is a rasterio-style 6-tuple (pixel_width, 0.0, origin_x, 0.0, pixel_height, origin_y). See xrspatial/geotiff/_coords.py:91-115. PR geotiff: add attrs contract documentation page (#1984) #2001 documents the same key with a different (also wrong) layout, so both need to be fixed together. Correct text: tuple of (pixel_width, 0.0, origin_x, 0.0, pixel_height, origin_y).

Suggestions (should fix, not blocking)

• xrspatial/geotiff/_attrs.py:25 — crs_wkt is described as "Always emitted." The reader emits it only when geo_info.crs_wkt is not None (see _attrs.py:107). The user-guide page in PR geotiff: add attrs contract documentation page (#1984) #2001 says "Always present on read when any CRS information is available", which matches the code. Match that wording.
• xrspatial/geotiff/_attrs.py:35 — gdal_metadata is the parsed dict and gdal_metadata_xml is the raw XML string. The writer prefers the XML form when both are present. A one-line note about that precedence would help.

Nits (optional improvements)

• Worth documenting that extra_tags is omitted when no out-of-band tags are present, similar to how transform is omitted on no-georef files.

What looks good

• Tier names (canonical, compatibility alias, best-effort pass-through) line up with the user-guide page in PR geotiff: add attrs contract documentation page (#1984) #2001 and the locking tests in PRs geotiff: add attrs compatibility-alias locking test (#1984) #2002 and geotiff: add attrs pass-through locking test (#1984) #2004.
• Every key listed under canonical is set somewhere in _populate_attrs_from_geo_info or the writer-side path for nodata.
• Pass-through keys match the keys populated by _populate_attrs_from_geo_info lines 128-184.

Checklist

• Tier classification matches code paths
• transform layout is wrong (see Blocker)
• No code paths changed; docstring-only
• Coordinated with PR geotiff: add attrs contract documentation page (#1984) #2001 user-guide page