Skip to content

Fix to_geotiff docstring tier for extra_tags pass-through#3596

Merged
brendancol merged 1 commit into
mainfrom
deep-sweep-api-consistency-geotiff-2026-07-01
Jul 2, 2026
Merged

Fix to_geotiff docstring tier for extra_tags pass-through#3596
brendancol merged 1 commit into
mainfrom
deep-sweep-api-consistency-geotiff-2026-07-01

Conversation

@brendancol

Copy link
Copy Markdown
Contributor

Closes #3593

  • Moves "extra_tags pass-through" from the [advanced] bullet of to_geotiff's release-contract tier list to [experimental], matching SUPPORTED_FEATURES['writer.extra_tags'] and the _validate_write_rich_tag_optin gate (which raises ValueError on a fresh DataArray with attrs['extra_tags'] unless allow_experimental_codecs=True). The bullet now names the opt-in and the round-trip exemption, and mentions gdal_metadata_xml which shares the gate.
  • Clarifies the photometric parameter doc: the override rides attrs['extra_tags'] (not a kwarg) and sits at the experimental tier.
  • Adds test_to_geotiff_docstring_extra_tags_tier_matches_supported_features to tests/unit/test_signatures.py (Section 3, next to the existing rich-tag gate tests) so the docstring cannot drift from the tier map again.
  • Updates the api-consistency sweep state CSV row for geotiff.

Doc-only change, no behavior touched, so backend coverage is unaffected (the gate itself already fires identically on the CPU and GPU write paths).

Test plan:

  • pytest xrspatial/geotiff/tests/unit/test_signatures.py (197 passed, includes the new test)
  • pytest xrspatial/geotiff/tests/unit/test_photometric.py (37 passed)
  • flake8 clean on both touched source files
  • Empirical check on a CUDA host: fresh attrs['extra_tags'] write raises without the flag, succeeds with it, and the cupy write round-trip still works

The release-contract tier list said extra_tags pass-through was
[advanced] (no kwarg gate), but SUPPORTED_FEATURES['writer.extra_tags']
is 'experimental' and _validate_write_rich_tag_optin rejects a fresh
DataArray carrying attrs['extra_tags'] without
allow_experimental_codecs=True. Move the bullet to [experimental],
name the opt-in and the round-trip exemption, and add a drift-guard
test so the docstring cannot disagree with the tier map again.

Also updates the api-consistency sweep state CSV for the geotiff row.
@brendancol brendancol added documentation Improvements or additions to documentation api API design and consistency geotiff GeoTIFF module labels Jul 2, 2026

@brendancol brendancol left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doc-only change; I checked the claims against the code rather than just the prose.

  • The new [experimental] bullet matches _validate_write_rich_tag_optin: fresh attrs['extra_tags'] / attrs['gdal_metadata_xml'] raise without allow_experimental_codecs=True, and the _xrspatial_geotiff_contract marker exempts round-tripped attrs. SUPPORTED_FEATURES carries both keys at 'experimental', so the docstring and tier map now agree.
  • The drift-guard test scopes its string checks to the region before "Parameters", which keeps the photometric parameter doc (which legitimately mentions the extra_tags override) out of the assertion. The bullet slicing on '* [' holds because [internal-only] follows the experimental bullet.

Nits, not blocking:

  • The gate also fires on a dict attrs['gdal_metadata'] (#3320); the revised bullet doesn't name that third attr. The runtime error does, so this is fine to leave.
  • The test pins the two SUPPORTED_FEATURES tiers directly, which overlaps with the release-gate suite. Harmless redundancy that makes the test self-contained.

No blockers.

@brendancol brendancol merged commit c2bf13c into main Jul 2, 2026
18 checks passed
brendancol added a commit that referenced this pull request Jul 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

api API design and consistency documentation Improvements or additions to documentation geotiff GeoTIFF module

Projects

None yet

Development

Successfully merging this pull request may close these issues.

to_geotiff docstring lists extra_tags pass-through as advanced, but the write gate is experimental

1 participant