Description
The four public read entry points in xrspatial/geotiff/ all accept allow_rotated and allow_unparseable_crs, but the Parameters section of each backend reader's docstring omits them. open_geotiff also omits allow_unparseable_crs from its own Parameters section; the kwarg is only mentioned in the Tier prose paragraph at the top of the docstring.
The three direct backend readers also accept several gated kwargs (missing_sources, band_nodata, on_gpu_failure, max_cloud_bytes, and overview_level on VRT) that exist only to raise ValueError on the wrong backend so all four readers stay error-symmetric. Those kwargs sit in the signature without a Parameters entry on the backends where they raise.
Evidence
Scanning each function's inspect.signature(...) parameter names against the regex ^(\w+) : in inspect.getdoc(...):
open_geotiff: missing ['allow_unparseable_crs']
read_geotiff_dask: missing ['allow_rotated', 'allow_unparseable_crs',
'max_cloud_bytes', 'missing_sources',
'on_gpu_failure']
read_geotiff_gpu: missing ['allow_rotated', 'allow_unparseable_crs',
'band_nodata', 'max_cloud_bytes',
'missing_sources']
read_vrt: missing ['allow_rotated', 'allow_unparseable_crs',
'max_cloud_bytes', 'on_gpu_failure',
'overview_level']
Proposed Fix
- Add Parameters entries for
allow_rotated and allow_unparseable_crs on every read entry point. Both affect read behaviour on every backend.
- Add one-line Parameters entries for the gated kwargs on the backends that raise on them. Point at
open_geotiff or the owning backend for the full description so the long form lives in one place.
- Add a regression test in
xrspatial/geotiff/tests/ that parametrises over (open_geotiff, read_geotiff_dask, read_geotiff_gpu, read_vrt) and asserts every signature parameter has a Parameters entry. Same pattern as test_open_geotiff_max_cloud_bytes_annot_2106.py.
Scope is documentation-only. No signature, default, or dispatch logic changes.
Found by the API consistency sweep for the geotiff module on 2026-05-21 (deep-sweep-api-consistency-geotiff-2026-05-21). Cat 3 finding, severity MEDIUM.
Description
The four public read entry points in
xrspatial/geotiff/all acceptallow_rotatedandallow_unparseable_crs, but the Parameters section of each backend reader's docstring omits them.open_geotiffalso omitsallow_unparseable_crsfrom its own Parameters section; the kwarg is only mentioned in the Tier prose paragraph at the top of the docstring.The three direct backend readers also accept several gated kwargs (
missing_sources,band_nodata,on_gpu_failure,max_cloud_bytes, andoverview_levelon VRT) that exist only to raiseValueErroron the wrong backend so all four readers stay error-symmetric. Those kwargs sit in the signature without a Parameters entry on the backends where they raise.Evidence
Scanning each function's
inspect.signature(...)parameter names against the regex^(\w+) :ininspect.getdoc(...):Proposed Fix
allow_rotatedandallow_unparseable_crson every read entry point. Both affect read behaviour on every backend.open_geotiffor the owning backend for the full description so the long form lives in one place.xrspatial/geotiff/tests/that parametrises over(open_geotiff, read_geotiff_dask, read_geotiff_gpu, read_vrt)and asserts every signature parameter has a Parameters entry. Same pattern astest_open_geotiff_max_cloud_bytes_annot_2106.py.Scope is documentation-only. No signature, default, or dispatch logic changes.
Found by the API consistency sweep for the geotiff module on 2026-05-21 (deep-sweep-api-consistency-geotiff-2026-05-21). Cat 3 finding, severity MEDIUM.