Expose coregistered reads through the xarray engine via like= (#3376)

[brendancol]

Closes #3376.

Adds a like= backend kwarg to the xrspatial xarray engine. When you pass it, the engine routes the read through like's .xrs.open_geotiff accessor instead of the standalone reader, so the coregistered-read options work through the standard xr.open_dataset / open_mfdataset API.

What changed

• like= (a DataArray or Dataset) triggers the coregister path. coregister, auto_reproject, resampling, and var are forwarded to the accessor.
• A Dataset like dispatches to the Dataset accessor, so var= picks the variable used for backend/CRS inference.
• The returned variable is named by the same default_name / source-stem rule as the plain engine path.
• open_mfdataset with a shared like= coregisters every source onto one grid in a single call.
• The accessor's GPU / .vrt / allow_rotated rejections apply through the engine without extra code.
• Passing coregister / auto_reproject / resampling / var without like= raises a ValueError that names like=, instead of the opaque TypeError the standalone reader would throw for an unknown kwarg.

Design decisions

The issue left two questions open. I went with like= for the kwarg name (the issue's first option, and it matches the xr.zeros_like / ones_like convention), and made like= the trigger: the coregister kwargs without it raise the pointed error rather than silently doing nothing.

Backend coverage

The coregister path is CPU-only (numpy and dask+numpy). GPU and .vrt sources already raise on the accessor, and the engine inherits that. The plain read path's backend support is unchanged.

Test plan

• coregister via engine matches the accessor output (same CRS, and CRS-mismatch reproject)
• auto_reproject via engine matches the accessor
• Dataset like with var=
• variable naming (stem and default_name override)
• open_mfdataset coregisters two files onto one grid
• guard raises ValueError for each coregister kwarg passed without like=
• GPU rejection inherited through the engine
• existing backend tests still pass

[brendancol]

PR Review: Expose coregistered reads through the xarray engine via like=

Blockers (must fix before merge)

None.

Suggestions (should fix, not blocking)

• _xarray_backend.py:106 — when like is not a DataArray or Dataset (say a path or a bare numpy array), like.xrs raises a generic AttributeError, which is harder to read than the pointed ValueError the no-like path gives. A short isinstance(like, (xr.DataArray, xr.Dataset)) guard with a clear message would round out the error handling.

Nits (optional improvements)

• _xarray_backend.py:110-115 — when the only offending kwarg is var, the message ("reproject/resample a source onto a target grid") doesn't quite fit, since var just selects the inference variable on a Dataset target. The like= pointer is still correct, so this is cosmetic.

What looks good

• The routing is a thin wrapper: like present → accessor, else standalone, with the variable-naming and drop_variables promotion shared across both paths. No duplicated read logic.
• Tests assert parity against the accessor output rather than just "it runs", and cover same-CRS, CRS-mismatch reproject, Dataset var=, naming, open_mfdataset, the per-kwarg guard, and the inherited GPU rejection.
• GPU / .vrt / allow_rotated rejections are inherited from the accessor instead of being re-implemented, so they can't drift out of sync.
• open_dataset_parameters is left untouched, so like travels through backend_kwargs like the other read options and doesn't trip xarray's CF decoder collision.

Checklist

• Routing matches the accessor (parity asserted in tests)
• All implemented backends consistent (CPU-only path; GPU rejection inherited)
• NaN handling unchanged (delegated to accessor)
• Edge cases covered by tests (guards, naming, mfdataset)
• Dask path exercised via open_mfdataset
• No premature materialization or extra copies
• Benchmark not needed (thin routing wrapper)
• README feature matrix not applicable (no new function)
• Docstrings / docs updated

[brendancol]

Follow-up review (after 7f47195)

Both findings from the first pass are addressed:

• Suggestion (like= type guard) — fixed. _xarray_backend.py:102-107 now raises TypeError naming the expected type when like is not a DataArray/Dataset, instead of falling through to an AttributeError on .xrs. Covered by test_non_array_like_raises_typeerror.
• Nit (guard wording) — fixed. _xarray_backend.py:117-122 reads "only apply when reading onto a target grid", which fits var as well as the reproject/resample kwargs.

No new issues. Tests: 15 coregister cases plus the 17 existing backend tests pass locally.