geotiff: write_geotiff_gpu kwarg order matches to_geotiff (#1922)#1925
Merged
brendancol merged 1 commit intoMay 15, 2026
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR aligns the public GPU GeoTIFF writer signature with to_geotiff so documented API-parity siblings present matching keyword order in introspection, IDEs, and generated docs.
Changes:
- Reordered
write_geotiff_gpukeyword-only parameters sostreaming_buffer_bytesprecedesmax_z_error. - Reordered the matching GPU writer docstring parameter entries.
- Added regression tests for kwarg-order parity and shared default parity.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
xrspatial/geotiff/_writers/gpu.py |
Aligns write_geotiff_gpu signature and docs with to_geotiff. |
xrspatial/geotiff/tests/test_writer_kwarg_order_1922.py |
Adds regression coverage for signature order and default parity. |
.claude/sweep-api-consistency-state.csv |
Updates sweep state metadata for issue #1922. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This was referenced May 15, 2026
to_geotiff and write_geotiff_gpu are documented parity siblings, but
the two signatures put max_z_error and streaming_buffer_bytes in
opposite order:
to_geotiff: ..., bigtiff, gpu, streaming_buffer_bytes,
max_z_error, photometric, ...
write_geotiff_gpu: ..., bigtiff, max_z_error,
streaming_buffer_bytes, photometric, ...
Both kwargs are keyword-only so caller code does not break, but the
drift surfaced in inspect.signature, IDE autocomplete, and Sphinx
docs against the GPU writer's own "Accepted at the signature level
for API parity with to_geotiff" docstring promise.
Reorder write_geotiff_gpu to match to_geotiff. The 'gpu' auto-dispatch
kwarg is the only one to_geotiff has that the GPU entry point does
not, so the gap stays in place; everything else after 'bigtiff' lines
up. Also reorder the docstring to keep doc order parallel.
New regression test test_writer_kwarg_order_1922.py pins kwarg order
parity (modulo 'gpu') and shared-default parity so future signature
edits trip the test instead of silently re-introducing drift.
Detected by deep-sweep-api-consistency on 2026-05-15.
Refs #1922
brendancol
force-pushed
the
deep-sweep-api-consistency-geotiff-2026-05-15-1778854324
branch
from
8422bc9 to
7c790a3
Compare
brendancol
added a commit
that referenced
this pull request
May 15, 2026
read_geotiff_gpu and read_geotiff_dask listed shared keyword-only params in different orders than open_geotiff. The kwargs are all keyword-only so callers were not broken, but inspect.signature, IDE autocomplete, and Sphinx docs all showed the drift. Pick open_geotiff as the canonical reference (the public dispatcher). Swap window and overview_level in read_geotiff_gpu. Reorder read_geotiff_dask so window, overview_level, band, name, chunks, max_pixels match the canonical position. read_vrt already conformed and is covered by the new regression test. Regression test (test_reader_kwarg_order_1935.py) pins each reader's kw-only param order via inspect.signature and asserts no pairwise inversions across the four readers, so future kwargs cannot be added in arbitrary positions. Mirrors the writer-side fix in #1922 / #1925.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
to_geotiffandwrite_geotiff_gpuare documented parity siblings, but the two signatures putmax_z_errorandstreaming_buffer_bytesin opposite order. Both kwargs are keyword-only so caller code did not break, but the drift surfaced ininspect.signature, IDE autocomplete, and Sphinx docs against the GPU writer's own "Accepted at the signature level for API parity withto_geotiff" promise.write_geotiff_gputo matchto_geotiff(streaming_buffer_bytesbeforemax_z_error). Thegpuauto-dispatch kwarg is the only oneto_geotiffhas that the GPU entry point does not, so the gap stays in place. Docstring reordered to keep doc order parallel.test_writer_kwarg_order_1922.pypins kwarg-order parity (modulogpu) and shared-default parity so future signature edits trip the test instead of silently re-introducing drift.Detected by
deep-sweep-api-consistencyon 2026-05-15. Refs #1922.Test plan
pytest xrspatial/geotiff/tests/test_writer_kwarg_order_1922.py(2 passed)pytest xrspatial/geotiff/tests/test_signature_parity_1631.py xrspatial/geotiff/tests/test_signature_annotations_1654.py xrspatial/geotiff/tests/test_signature_annotations_1705.py(34 passed)pytest xrspatial/geotiff/tests/ -k "max_z_error or streaming_buffer or kwarg_order"(14 passed)pytest xrspatial/geotiff/tests/test_to_geotiff_allow_internal_only_jpeg_parity.py(8 passed)