Reject fills the output dtype cannot represent exactly

[brendancol]

Closes #3054

rasterize() casts its float64 work buffer to the output dtype at the end of every backend, while the attrs block stores the original fill verbatim. The old guard only caught fill=NaN against integer dtypes, so two cases slipped through and left the burned array disagreeing with its nodata/_FillValue/nodatavals attrs:

• dtype=np.uint8, fill=-9999 burned an actual fill of 241 but advertised -9999.
• dtype=np.bool_, fill=np.nan turned every unwritten pixel into True with no nodata attrs (since np.issubdtype(np.bool_, np.integer) is False, bool dodged the integer-only guard).

Change

• Replace the NaN-only-integer guard with a round-trip representability test: for integer and boolean output dtypes, reject any fill that changes value when cast to the dtype and back. Float dtypes are left alone (NaN is representable, ordinary rounding is expected).
• Update the fill docstring to describe the broadened guard.
• Relax the rasterize: silent NaN-to-integer fill cast loses sentinel, no _FillValue emitted #2504 regression match strings to the shared "cannot be represented" substring.

Backend coverage

The guard runs before any host/device allocation, so it fires identically on numpy, cupy, dask+numpy, and dask+cupy. New tests parametrize the out-of-range-int and bool cases across all four (cupy/dask paths skip when unavailable).

Test plan

• New regression tests in test_rasterize_fill_dtype_3054.py pass
• Existing rasterize: silent NaN-to-integer fill cast loses sentinel, no _FillValue emitted #2504 guard tests still pass
• test_rasterize.py full suite passes (249 passed, 2 skipped)
• flake8 clean on changed files

[brendancol]

PR Review: Reject fills the output dtype cannot represent exactly

Blockers (must fix before merge)

None.

Suggestions (should fix, not blocking)

• xrspatial/rasterize.py:3378 — the round-trip cast originally caught only (TypeError, ValueError). A fill wider than the platform C long (e.g. fill=2**100) lands in an object array whose astype(<int>) raises OverflowError, which would escape as a stray traceback instead of the guard's actionable message. Fixed during review by adding OverflowError to the caught set and a regression test (test_huge_int_fill_raises_cleanly).

Nits (optional improvements)

None.

What looks good

• The round-trip representability test is the right generalization. It subsumes the old NaN-into-integer case and extends cleanly to out-of-range integers and bool, without special-casing each.
• Bool is handled explicitly via the final_dtype_np == np.bool_ branch, since np.issubdtype(np.bool_, np.integer) is False.
• Float dtypes are deliberately untouched, so NaN fills and ordinary float rounding still pass.
• The guard sits before backend dispatch in the single public entry point, so all four backends (numpy, cupy, dask+numpy, dask+cupy) hit it before any allocation. Tests parametrize each.
• The RuntimeWarning from the NaN-to-int probe cast is suppressed locally, matching the existing pattern in _run_numpy.
• The valid-fill round-trip tests confirm the nodata/_FillValue/nodatavals triplet stays consistent with the burned value.

Checklist

• Algorithm matches the stated contract (exact round-trip)
• All four backends hit the guard before allocation
• NaN handling correct (float NaN passes, int/bool NaN rejected)
• Edge cases covered (out-of-range int, bool, huge int, valid round-trips)
• No premature materialization (guard is a scalar check)
• Benchmark not needed (validation-only change)
• README feature matrix not applicable (no new function, no backend change)
• Docstrings present and updated for the broadened guard