Block write_geotiff_gpu(file_like, cog=True) for parity with to_geotiff (#1652)

to_geotiff has long rejected cog=True + file-like destinations, but the
explicit write_geotiff_gpu entry point silently accepted the combo and
emitted a COG into the buffer. The two writers should agree on which
inputs they refuse: to_geotiff(gpu=True, cog=True, path=BytesIO) raises,
so write_geotiff_gpu(da, BytesIO, cog=True) should too.

Mirror the existing to_geotiff guard on the GPU entry point. Non-cog
file-like writes remain supported on this path (the gate is targeted at
cog=True only). Add regression coverage in test_bytesio_source.py.

Also clarify the path/compression docstring on write_geotiff_gpu:

- path: document that file-like destinations are accepted (cog=True
  requires a string path).
- compression: list the full codec set the function actually accepts
  and note the deliberate JPEG asymmetry with to_geotiff (#1651
  downgraded to docs-only after PR #1647 confirmed advanced-API
  intent).

Update .claude/sweep-api-consistency-state.csv with the 2026-05-11
re-audit row.

Author: brendancol

.claude/sweep-api-consistency-state.csv

@@ -1,3 +1,3 @@
 module,last_inspected,issue,severity_max,categories_found,notes
-geotiff,2026-05-11,1631,MEDIUM,3,"Filed write_vrt and write_geotiff_gpu signature/docstring drift vs to_geotiff (MEDIUM, #1631). Fix in PR (TBD): explicit write_vrt(relative, crs_wkt, nodata) signature (was **kwargs); 'cubic' added to write_geotiff_gpu overview_resampling docstring; write_geotiff_gpu(data) typed xr.DataArray|cupy.ndarray to match to_geotiff. Prior 1605/1606/1611/1612/1613/1615/1623 all CLOSED."
+geotiff,2026-05-11,1652,MEDIUM,5,"Filed MEDIUM file-like cog=True drift #1652 (write_geotiff_gpu accepted BytesIO+cog=True; to_geotiff blocked it). Fixed in PR (TBD): mirror to_geotiff's gate on the explicit GPU writer; add regression tests in test_bytesio_source.py. Also filed #1651 (JPEG acceptance drift) but downgraded to LOW after #1647 confirmed write_geotiff_gpu(jpeg) is deliberate advanced-API; PR (TBD) carries the docstring clarification. Prior 1631/1644 noted in earlier rows (1644 open, fix in PR #1649). LOW: streaming_buffer_bytes default drift to_geotiff=256MB vs write_geotiff_gpu=None (no functional impact, explicit forwarding); to_geotiff data: annotation misses cupy.ndarray (accepted via auto-dispatch). cuda-validated."
 reproject,2026-05-10,1570,HIGH,2;5,"Filed cross-module attrs['vertical_crs'] type collision (string vs EPSG int) vs xrspatial.geotiff. Fixed in PR (TBD): reproject now writes EPSG int and preserves friendly token under vertical_datum. MEDIUM kwarg-order drift (transform_precision vs chunk_size) and missing type hints vs geotiff documented but not fixed (cosmetic, kwarg-only)."

xrspatial/geotiff/__init__.py

@@ -2714,7 +2714,7 @@ def _read_once():
 
 
 def write_geotiff_gpu(data: xr.DataArray | cupy.ndarray | np.ndarray,
-                      path: str, *,
+                      path, *,
                       crs: int | str | None = None,
                       nodata=None,
                       compression: str = 'zstd',
@@ -2747,15 +2747,27 @@ def write_geotiff_gpu(data: xr.DataArray | cupy.ndarray | np.ndarray,
         2D or 3D raster. CuPy-backed inputs stay on device; NumPy/Dask
         inputs are uploaded via ``cupy.asarray(np.asarray(data))``
         before compression (matches ``to_geotiff`` parity).
-    path : str
-        Output file path.
+    path : str or binary file-like
+        Output file path or any object with a ``write`` method
+        (e.g. ``io.BytesIO``). ``cog=True`` requires a string path:
+        the auto-dispatch path through ``to_geotiff(gpu=True, cog=True)``
+        rejects file-like destinations, and the explicit GPU writer
+        mirrors that rule (issue #1652).
     crs : int, str, or None
         EPSG code or WKT string.
     nodata : float, int, or None
         NoData value.
     compression : str
-        'zstd' (default, fastest on GPU), 'deflate', 'jpeg', or 'none'.
-        JPEG uses nvJPEG when available, falling back to Pillow.
+        Codec name. Accepts the full set ``to_geotiff`` does:
+        ``'none'``, ``'deflate'``, ``'lzw'``, ``'jpeg'``, ``'packbits'``,
+        ``'zstd'`` (default, fastest on GPU), ``'lz4'``, ``'jpeg2000'``
+        (alias ``'j2k'``), or ``'lerc'``. ``'jpeg'`` uses nvJPEG when
+        available, falling back to Pillow. Note that ``to_geotiff``
+        rejects ``compression='jpeg'`` up front because the encoder
+        omits the JPEGTables tag (347); the explicit GPU writer
+        accepts it on the understanding that callers know the
+        cross-reader caveat. Codecs unsupported by nvCOMP fall back
+        to the CPU encoder transparently.
     compression_level : int or None
         Compression effort level. Accepted for API compatibility but
         currently ignored -- nvCOMP does not expose level control.
@@ -2810,6 +2822,17 @@ def write_geotiff_gpu(data: xr.DataArray | cupy.ndarray | np.ndarray,
             "max_z_error is not supported on the GPU writer "
             "(nvCOMP has no LERC backend). Use to_geotiff(..., gpu=False) "
             "or omit max_z_error.")
+    # Mirror to_geotiff's file-like + cog=True rejection. The auto-dispatch
+    # path through ``to_geotiff(gpu=True, cog=True, path=BytesIO)`` raises
+    # before reaching here; the explicit GPU writer mirrors the gate so
+    # callers cannot bypass it (issue #1652). Non-cog file-like writes
+    # remain supported on this entry point.
+    _path_is_file_like = (
+        not isinstance(path, str)) and hasattr(path, 'write')
+    if _path_is_file_like and cog:
+        raise ValueError(
+            "cog=True is not supported for file-like destinations on the "
+            "GPU writer. Pass a string path or set cog=False.")
     # streaming_buffer_bytes is intentionally a no-op on the GPU path;
     # the kwarg exists for API parity with to_geotiff so callers can pass
     # the same kwargs to both entry points without filtering.

xrspatial/geotiff/tests/test_bytesio_source.py

@@ -268,3 +268,50 @@ def seek(self, *a, **k):
 
     assert _is_file_like(io.BytesIO(b'x')) is True
     assert _is_file_like(ReadSeekNoTell()) is False
+
+
+class TestWriteGeotiffGpuBytesIO:
+    """Regression coverage for ``write_geotiff_gpu`` file-like behaviour.
+
+    ``to_geotiff(gpu=True, ...)`` always rejects BytesIO destinations paired
+    with ``cog=True`` (the auto-dispatch path's existing guard). The explicit
+    GPU writer used to silently accept that combo and produce a COG into the
+    buffer, so the two entry points disagreed on what ``to_geotiff(gpu=True,
+    cog=True, path=BytesIO)`` does. These tests pin the mirrored gate added
+    by issue #1652 and confirm the non-cog file-like path still works.
+    """
+
+    def test_cog_with_bytesio_rejected_1652(self):
+        cupy = pytest.importorskip("cupy")
+        da = xr.DataArray(
+            cupy.asarray(np.random.rand(64, 64).astype(np.float32)),
+            dims=['y', 'x'],
+            coords={'y': np.arange(64.0), 'x': np.arange(64.0)},
+            attrs={'crs': 4326},
+        )
+        from xrspatial.geotiff import write_geotiff_gpu
+
+        buf = io.BytesIO()
+        with pytest.raises(ValueError, match='cog=True'):
+            write_geotiff_gpu(da, buf, cog=True)
+
+    def test_non_cog_bytesio_still_works_1652(self):
+        cupy = pytest.importorskip("cupy")
+        arr_cpu = np.random.rand(64, 64).astype(np.float32)
+        da = xr.DataArray(
+            cupy.asarray(arr_cpu),
+            dims=['y', 'x'],
+            coords={'y': np.arange(64.0), 'x': np.arange(64.0)},
+            attrs={'crs': 4326},
+        )
+        from xrspatial.geotiff import write_geotiff_gpu
+
+        buf = io.BytesIO()
+        # Non-cog file-like write is still supported on the explicit GPU
+        # writer; only cog=True is gated.
+        write_geotiff_gpu(da, buf)
+        assert len(buf.getvalue()) > 0
+
+        # Verify it round-trips through open_geotiff
+        rd = open_geotiff(io.BytesIO(buf.getvalue()))
+        np.testing.assert_allclose(np.asarray(rd.values), arr_cpu)