Add Convention option & extract CF logic to cf.py

[emmanuelmathot]

This is the first in a series of PRs splitting #883 as requested by maintainers.

Summary

This PR establishes the framework for supporting multiple geospatial metadata conventions. Reading auto-detects conventions from existing attributes, while writing uses the convention setting.

Changes

New Convention Framework

• Add Convention enum with CF value in rioxarray/enum.py
• Add convention option to set_options() for controlling write behavior
• Create ConventionProtocol interface for consistent convention module APIs

CF Convention Module (rioxarray/_convention/cf.py)

• Extract CF-specific read/write logic from rioxarray.py
• read_crs() - Read CRS from CF grid_mapping coordinate
• read_transform() - Read transform from GeoTransform attribute
• read_spatial_dimensions() - Detect spatial dimensions from standard names/attrs
• write_crs() - Write CRS with CF conventions (handles grid_mapping_name defaults)
• write_transform() - Write transform with CF conventions
• _write_grid_mapping() - Internal helper for grid_mapping encoding

Auto-detect Layer (rioxarray/_convention/__init__.py)

• read_crs_auto() - Try all convention readers, with legacy attrs['crs'] fallback
• read_transform_auto() - Try all convention readers, with legacy attrs['transform'] fallback
• read_spatial_dimensions_auto() - Try all convention readers
• _get_convention() - Get convention module based on setting

Refactored rioxarray.py

• crs property now uses read_crs_auto() for auto-detection
• _cached_transform() now uses read_transform_auto()
• write_crs() delegates to convention module, accepts convention parameter
• write_transform() delegates to convention module, accepts convention parameter
• write_grid_mapping() method kept for backwards compatibility
• Spatial dimension detection uses read_spatial_dimensions_auto()

API Design Principles

• Reading: Auto-detects conventions by trying each reader until one succeeds
• Writing: Uses global convention setting (default: CF) or per-method convention parameter
• Backwards compatible: Legacy crs/transform attrs still supported for reading
• Keyword-only arguments: All CF functions use *, for clarity and API stability

Files Changed

• rioxarray/enum.py - New Convention enum
• rioxarray/_options.py - Add convention option
• rioxarray/_convention/__init__.py - Convention interface and auto-detect functions
• rioxarray/_convention/cf.py - CF convention implementation
• rioxarray/rioxarray.py - Refactored to use convention modules
• rioxarray/_spatial_utils.py - Updated write_crs call with grid_mapping_name
• test/unit/test_convention_cf.py - New unit tests for CF module
• test/unit/test_options.py - Tests for convention option
• docs/history.rst - Document changes
• docs/rioxarray.rst - Document enum module

---

• Closes Implement Zarr spatial and proj conventions support #883 (partial - first of series)
• Tests added
• Fully documented, including history.rst for all changes and rioxarray.rst for new API

[snowman2]

When reading attributes from a file, it shouldn't be limited by the convention and should attempt to detect the convention and read from the xarray object based on the detected convention.

The convention should mainly be used for writing to the xarray object.

[snowman2]

This is a really good strategy: #883 (review). I suggest using this strategy when writing to the xarray object.

[snowman2]

This is looking pretty good. I suggest moving the crs & transform attribute logic to the _auto methods as they aren't part of the CF convention.

[snowman2]

See pylint complaints: https://github.com/corteva/rioxarray/actions/runs/21526722800/job/62037060257?pr=899

[emmanuelmathot]

remaining failing tests atre test_clip_geojson__no_drop, unrelated to this PR. I verified that the exact same 8 tests fail on the master.

[snowman2]

Suggested change

	crs: rasterio.crs.CRS,
	*,
	crs: rasterio.crs.CRS,

[snowman2]

Suggested change

	transform: Affine,
	*,
	transform: Affine,

[snowman2]

Thanks @emmanuelmathot 👍