Rasterio 1.4.0

A month ago I wrote a long-ish post about Fiona 1.10.0. I'll try to keep this one shorter. Rasterio 1.4.0 has three main changes: Python openers, detailed error chaining, and a new statistics API.

Python openers can connect filesystems implemented in Python, like fsspec or tiledb.vfs, to GDAL's own virtual filesystem machinery. In most cases, you should reply on GDAL's built-in virtual filesystem handlers. On the other hand, if you have unique or proprietary data access protocols, then Rasterio's new openers may be useful.

Often enough, I want more visibility into the errors that occur during GDAL I/O functions. I'd like to see all the errors, not just the last one. So, I've implemented Python-like chaining of GDAL errors. It's not perfectly analogous, because we don't have frames for GDAL code like we do for Python, but look at the kind of details you can get now:

>>> src.read()
rasterio._err.CPLE_AppDefinedError: TIFFFillTile:Read error at row 512, col 0, tile 3; got 38232 bytes, expected 47086

The above exception was the direct cause of the following exception:

rasterio._err.CPLE_AppDefinedError: TIFFReadEncodedTile() failed.

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "rasterio/_io.pyx", line 968, in rasterio._io.DatasetReaderBase._read
    io_multi_band(self._hds, 0, xoff, yoff, width, height, out, indexes_arr, resampling=resampling)
  File "rasterio/_io.pyx", line 207, in rasterio._io.io_multi_band
    with stack_errors() as checker:
  File "rasterio/_io.pyx", line 213, in rasterio._io.io_multi_band
    return checker.exc_wrap_int(retval)
  File "rasterio/_err.pyx", line 307, in rasterio._err.StackChecker.exc_wrap_int
    raise last
rasterio._err.CPLE_AppDefinedError: /app/tests/data/corrupt.tif, band 1: IReadBlock failed at X offset 1, Y offset 1: TIFFReadEncodedTile() failed.

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "<console>", line 1, in <module>
  File "rasterio/_io.pyx", line 650, in rasterio._io.DatasetReaderBase.read
    out = self._read(indexes, out, window, dtype, resampling=resampling)
  File "rasterio/_io.pyx", line 971, in rasterio._io.DatasetReaderBase._read
    raise RasterioIOError("Read or write failed. See context for details.") from cplerr
rasterio.errors.RasterioIOError: Read or write failed. See context for details.

Lastly, the flawed, multimodal statistics() method of datasets has been deprecated and is replaced by new, simpler stats(), clear_stats(), and update_stats() methods.

Rasterio 1.4.0 remains limited to "classical" rasters, those with a handful of bands or channels all of the same type. For hyperspectral data cubes and the like, you should use h5py, xarray, or other emerging software. I'm quite interested in working on new software in that area, but I'd like to do so without any classical raster legacy.