to_geotiff and write_geotiff_gpu are documented as parity siblings. The GPU writer's docstring says "Accepted at the signature level for API parity with to_geotiff" for several kwargs. The two signatures put max_z_error and streaming_buffer_bytes in different positions though.
to_geotiff (xrspatial/geotiff/_writers/eager.py:50-67):
..., bigtiff, gpu, streaming_buffer_bytes, max_z_error, photometric, allow_internal_only_jpeg
write_geotiff_gpu (xrspatial/geotiff/_writers/gpu.py:33-49):
..., bigtiff, max_z_error, streaming_buffer_bytes, photometric, allow_internal_only_jpeg
Both kwargs are keyword-only so caller code does not break. The drift surfaces in inspect.signature(), IDE autocomplete, and Sphinx-rendered docs -- the "two writers look identical from outside" promise leaks there.
Proposed fix
Reorder write_geotiff_gpu to match to_geotiff (streaming_buffer_bytes before max_z_error). gpu is the only kwarg to_geotiff has that the GPU entry point does not, so the gap stays in place; everything else after bigtiff lines up.
No deprecation shim needed: both args are keyword-only, defaults are unchanged, behaviour is unchanged.
Detected by
deep-sweep-api-consistency on 2026-05-15.
Severity: MEDIUM (Cat 1 — parameter naming/ordering drift between explicit-parity siblings).
to_geotiffandwrite_geotiff_gpuare documented as parity siblings. The GPU writer's docstring says "Accepted at the signature level for API parity withto_geotiff" for several kwargs. The two signatures putmax_z_errorandstreaming_buffer_bytesin different positions though.to_geotiff(xrspatial/geotiff/_writers/eager.py:50-67):write_geotiff_gpu(xrspatial/geotiff/_writers/gpu.py:33-49):Both kwargs are keyword-only so caller code does not break. The drift surfaces in
inspect.signature(), IDE autocomplete, and Sphinx-rendered docs -- the "two writers look identical from outside" promise leaks there.Proposed fix
Reorder
write_geotiff_gputo matchto_geotiff(streaming_buffer_bytesbeforemax_z_error).gpuis the only kwargto_geotiffhas that the GPU entry point does not, so the gap stays in place; everything else afterbigtifflines up.No deprecation shim needed: both args are keyword-only, defaults are unchanged, behaviour is unchanged.
Detected by
deep-sweep-api-consistency on 2026-05-15.
Severity: MEDIUM (Cat 1 — parameter naming/ordering drift between explicit-parity siblings).