stream_order_d8: accept method alias; basins_d8: emit DeprecationWarning

[brendancol]

Closes #2709

What changed

• stream_order_d8 now accepts a method keyword as an alias for ordering. This matches stream_order_dinf and stream_order_mfd, which already name the strahler/shreve selector method. ordering keeps working, so existing callers and the stream_order(routing=...) dispatcher (which passes ordering=) are unaffected. Passing both ordering and method with conflicting values raises ValueError.
• basins_d8 (the backward-compatible wrapper for basin_d8) now emits a DeprecationWarning, which its docstring already pointed users toward.

A full rename of ordering to method was avoided on purpose: the dispatcher in xrspatial/hydro/__init__.py (out of scope for this D8 sweep) passes ordering= straight to the D8 path, so deprecating ordering now would warn on every unified stream_order(routing='d8') call.

Backend coverage

The selector is a plain string passed to every backend, so the alias behaves the same on numpy, cupy, dask+numpy, and dask+cupy. Verified method/ordering parity on numpy and on a cupy DataArray.

Test plan

• method alias produces the same result as ordering (numpy)
• method parity on a cupy DataArray
• invalid method value raises ValueError
• conflicting ordering + method raises ValueError
• basins_d8 emits DeprecationWarning and still returns the basin result
• existing stream_order_d8 and watershed_d8 suites pass (70 passed)

[brendancol]

PR Review: stream_order_d8 method alias; basins_d8 DeprecationWarning

Blockers

None.

Suggestions

None. The conflict check and precedence logic hold up, and the tests cover alias parity, precedence, invalid value, conflict, and the case-insensitive non-conflict path.

Nits

• The pre-existing test_basins_backward_compat (test_watershed_d8.py:153) now emits an unasserted DeprecationWarning, since the unified basins path in hydro/init.py routes through basins_d8. The test still passes (warnings are not errors here). If you want a clean run, wrap that call in pytest.warns, or just leave it since basins is itself the deprecated alias. Not blocking.
• import warnings sits inside the basins_d8 body (watershed_d8.py:1095). It matches the local-import style the function already uses for basin_d8, so it's fine.

What looks good

• method as a case-insensitive alias for ordering lines up with the stream_order_dinf/stream_order_mfd signatures, and it doesn't break the stream_order(routing='d8') dispatcher, which still passes ordering=.
• The method: str | None = None sentinel plus a conflict check that only fires when ordering is set to a non-default value is the right call here. Python can't tell an explicit default from an unset arg, so this is about as good as it gets.
• The method: str | None hint matches the None default and the docstring.
• basins_d8 now emits the DeprecationWarning its docstring already implied, with stacklevel=2 pointing the warning at the caller.
• The selector is a plain string handed to every backend, so the alias behaves the same on numpy, cupy, dask+numpy, and dask+cupy. 71 D8 tests pass, including 16 cross-backend cupy/dask tests on this CUDA host.

Checklist

• Algorithm unchanged (alias routes to the existing strahler/shreve paths)
• Backends consistent (string selector, backend-agnostic)
• NaN handling unchanged
• Edge cases covered (invalid value, conflict, case-insensitivity)
• Dask chunk boundaries unaffected
• No premature materialization or extra copies
• Benchmark not needed (no perf-critical change)
• README feature matrix unaffected (no new public function)
• Docstrings present and accurate