Replace silent except-return-None with typed warnings + strict mode (#1662)

Each broad `except Exception: return None` site flagged in #1662 now
emits a GeoTIFFFallbackWarning carrying the original exception type and
message. The new XRSPATIAL_GEOTIFF_STRICT=1 env var (read by
_geotiff_strict_mode()) re-raises instead of warning so CI can fail on
silent GPU or VRT fallbacks.

Sites covered:
- _wkt_to_epsg, _epsg_to_wkt: pyproj-missing vs broken-input
- _vrt.py source read skip: surface missing-tile holes
- _gds_read_tiles, _try_nvcomp_batch_decompress (kvikio + ctypes),
  _try_nvjpeg_batch_decode, _nvjpeg_batch_encode,
  _try_nvcomp_from_device_bufs, _nvcomp_batch_compress,
  _try_nvjpeg2k_batch_decode, _nvjpeg2k_batch_encode
- read_geotiff_gpu(on_gpu_failure='auto') stages also honor the env var

Author: brendancol

xrspatial/geotiff/__init__.py

@@ -32,6 +32,7 @@
 from __future__ import annotations
 
 import math
+import os
 import warnings
 
 import numpy as np
@@ -75,17 +76,50 @@
 _BAND_DIM_NAMES = ('band', 'bands', 'channel')
 
 
+class GeoTIFFFallbackWarning(UserWarning):
+    """Warning emitted when a geotiff helper falls back to a slower path.
+
+    Raised in the same call sites that would silently return ``None`` under
+    the historic ``except Exception: return None`` pattern. See issue #1662
+    for the audit and the ``XRSPATIAL_GEOTIFF_STRICT=1`` env var that
+    promotes these warnings to exceptions.
+    """
+
+
+def _geotiff_strict_mode() -> bool:
+    """Return True when ``XRSPATIAL_GEOTIFF_STRICT`` is set to a truthy value.
+
+    Strict mode promotes the silent fallbacks audited in issue #1662 into
+    raised exceptions. Useful in CI to catch GPU-path or VRT regressions
+    that would otherwise hide behind a CPU fallback or a missing tile.
+    """
+    return os.environ.get(
+        'XRSPATIAL_GEOTIFF_STRICT', '').lower() in ('1', 'true', 'yes')
+
+
 def _wkt_to_epsg(wkt_or_proj: str) -> int | None:
     """Try to extract an EPSG code from a WKT or PROJ string.
 
     Returns None if pyproj is not installed or the string can't be parsed.
+
+    Under ``XRSPATIAL_GEOTIFF_STRICT=1`` the underlying exception is
+    re-raised instead of being swallowed. In the default mode a
+    ``GeoTIFFFallbackWarning`` is emitted so callers can tell
+    pyproj-missing from pyproj-broken-input.
     """
     try:
         from pyproj import CRS
         crs = CRS.from_user_input(wkt_or_proj)
         epsg = crs.to_epsg()
         return epsg
-    except Exception:
+    except Exception as e:
+        if _geotiff_strict_mode():
+            raise
+        warnings.warn(
+            f"_wkt_to_epsg failed ({type(e).__name__}: {e}); returning None.",
+            GeoTIFFFallbackWarning,
+            stacklevel=2,
+        )
         return None
 
 
@@ -1968,7 +2002,7 @@ def _gpu_decode_single_band_tiles(
             byte_order=byte_order,
         )
     except Exception as e:
-        if gpu == 'strict':
+        if gpu == 'strict' or _geotiff_strict_mode():
             raise
         warnings.warn(
             f"read_geotiff_gpu: GPU decode failed "
@@ -1992,7 +2026,7 @@ def _gpu_decode_single_band_tiles(
                 byte_order=byte_order,
             )
         except Exception as e:
-            if gpu == 'strict':
+            if gpu == 'strict' or _geotiff_strict_mode():
                 raise
             warnings.warn(
                 f"read_geotiff_gpu: GPU decode failed "
@@ -2588,7 +2622,7 @@ def _read_once():
                 masked_fill=masked_fill,
             )
         except Exception as e:
-            if gpu == 'strict':
+            if gpu == 'strict' or _geotiff_strict_mode():
                 raise
             warnings.warn(
                 f"read_geotiff_gpu: GPU decode failed "
@@ -2620,7 +2654,7 @@ def _read_once():
                 masked_fill=masked_fill,
             )
         except Exception as e:
-            if gpu == 'strict':
+            if gpu == 'strict' or _geotiff_strict_mode():
                 raise
             warnings.warn(
                 f"read_geotiff_gpu: GPU decode failed "

xrspatial/geotiff/_geotags.py

@@ -235,11 +235,24 @@ def _epsg_to_wkt(epsg: int) -> str | None:
     """Resolve an EPSG code to a WKT string using pyproj.
 
     Returns None if pyproj is not installed or the code is unknown.
+
+    Under ``XRSPATIAL_GEOTIFF_STRICT=1`` the underlying exception is
+    re-raised instead of being swallowed. See issue #1662.
     """
     try:
         from pyproj import CRS
         return CRS.from_epsg(epsg).to_wkt()
-    except Exception:
+    except Exception as e:
+        import warnings
+        from . import _geotiff_strict_mode, GeoTIFFFallbackWarning
+        if _geotiff_strict_mode():
+            raise
+        warnings.warn(
+            f"_epsg_to_wkt({epsg!r}) failed "
+            f"({type(e).__name__}: {e}); returning None.",
+            GeoTIFFFallbackWarning,
+            stacklevel=2,
+        )
         return None
 
 

xrspatial/geotiff/_gpu_decode.py

@@ -7,10 +7,31 @@
 from __future__ import annotations
 
 import math
+import warnings
 
 import numpy as np
 from numba import cuda
 
+
+def _warn_or_raise_gpu_fallback(stage: str, exc: BaseException) -> None:
+    """Report a GPU helper falling back to None (issue #1662).
+
+    Under ``XRSPATIAL_GEOTIFF_STRICT=1`` the original exception is
+    re-raised so CI catches silent fast-path regressions. In the default
+    mode a ``GeoTIFFFallbackWarning`` is emitted with the exception type
+    and message; the caller still receives ``None`` and chooses its own
+    next step (typically another decoder or CPU fallback).
+    """
+    from . import _geotiff_strict_mode, GeoTIFFFallbackWarning
+    if _geotiff_strict_mode():
+        raise exc
+    warnings.warn(
+        f"{stage} fell back to None "
+        f"({type(exc).__name__}: {exc}).",
+        GeoTIFFFallbackWarning,
+        stacklevel=3,
+    )
+
 #: Fraction of free GPU memory we're willing to allocate in a single call.
 #: Above this, raise MemoryError up-front so the caller gets an actionable
 #: error rather than a CUDA OOM deep inside the kernel launch.
@@ -941,14 +962,17 @@ def _try_kvikio_read_tiles(file_path, tile_offsets, tile_byte_counts, tile_bytes
                 d_tiles.append(buf)
         cupy.cuda.Device().synchronize()
         return d_tiles
-    except Exception:
-        # GDS not available, version mismatch, or CUDA error
-        # Reset CUDA error state if possible
+    except Exception as e:
+        # GDS not available, version mismatch, or CUDA error.
+        # Reset CUDA error state if possible (the inner pass stays broad
+        # because a failed synchronize() during error recovery has no
+        # better recovery path; see issue #1662).
         try:
             import cupy
             cupy.cuda.Device().synchronize()
         except Exception:
             pass
+        _warn_or_raise_gpu_fallback("_gds_read_tiles", e)
         return None
 
 
@@ -1051,7 +1075,9 @@ def _try_nvcomp_batch_decompress(compressed_tiles, tile_bytes, compression):
             ]
             d_decompressed = manager.decompress(d_compressed)
             return cupy.concatenate([d.ravel() for d in d_decompressed])
-        except Exception:
+        except Exception as e:
+            _warn_or_raise_gpu_fallback(
+                "_try_nvcomp_batch_decompress (kvikio DeflateManager)", e)
             return None
 
     # Direct ctypes nvCOMP C API
@@ -1170,7 +1196,9 @@ class _NvcompDeflateDecompOpts(ctypes.Structure):
 
         return d_decomp
 
-    except Exception:
+    except Exception as e:
+        _warn_or_raise_gpu_fallback(
+            "_try_nvcomp_batch_decompress (ctypes nvCOMP C API)", e)
         return None
 
 
@@ -1347,7 +1375,8 @@ class _NvjpegImage(ctypes.Structure):
             if destroy_fn is not None:
                 destroy_fn(nvjpeg_handle)
 
-    except Exception:
+    except Exception as e:
+        _warn_or_raise_gpu_fallback("_try_nvjpeg_batch_decode", e)
         return None
 
 
@@ -1491,7 +1520,8 @@ class _NvjpegImage(ctypes.Structure):
             if destroy_fn is not None:
                 destroy_fn(nvjpeg_handle)
 
-    except Exception:
+    except Exception as e:
+        _warn_or_raise_gpu_fallback("_nvjpeg_batch_encode", e)
         return None
 
 
@@ -1622,7 +1652,8 @@ class _NvcompDecompOpts(ctypes.Structure):
             return None
 
         return cupy.concatenate(d_decomp_bufs)
-    except Exception:
+    except Exception as e:
+        _warn_or_raise_gpu_fallback("_try_nvcomp_from_device_bufs", e)
         return None
 
 
@@ -2408,7 +2439,8 @@ class _DeflateCompOpts(ctypes.Structure):
 
         return result
 
-    except Exception:
+    except Exception as e:
+        _warn_or_raise_gpu_fallback("_nvcomp_batch_compress", e)
         return None
 
 
@@ -2597,7 +2629,8 @@ class _NvJpeg2kImage(ctypes.Structure):
 
         return d_all_tiles
 
-    except Exception:
+    except Exception as e:
+        _warn_or_raise_gpu_fallback("_try_nvjpeg2k_batch_decode", e)
         return None
 
 
@@ -2742,7 +2775,8 @@ class _CompInfo(ctypes.Structure):
 
         return result
 
-    except Exception:
+    except Exception as e:
+        _warn_or_raise_gpu_fallback("_nvjpeg2k_batch_encode", e)
         return None
 
 

xrspatial/geotiff/_vrt.py

@@ -356,7 +356,22 @@ def read_vrt(vrt_path: str, *, window=None,
                     window=(src_r0, src_c0, src_r1, src_c1),
                     band=src.band - 1,  # convert 1-based to 0-based
                 )
-            except Exception:
+            except Exception as e:
+                # Under XRSPATIAL_GEOTIFF_STRICT=1, surface the read failure
+                # so partial mosaics are caught in CI. Default mode warns
+                # once per missing source then continues, preserving the
+                # historical behaviour. See issue #1662.
+                import warnings
+                from . import _geotiff_strict_mode, GeoTIFFFallbackWarning
+                if _geotiff_strict_mode():
+                    raise
+                warnings.warn(
+                    f"VRT source {src.filename!r} could not be read "
+                    f"({type(e).__name__}: {e}); skipping. The output "
+                    f"mosaic will have a hole at this tile.",
+                    GeoTIFFFallbackWarning,
+                    stacklevel=2,
+                )
                 continue  # skip missing/unreadable sources
 
             # Handle source nodata.  Cast the sentinel to the *source*