easy-eo 0.4.2__tar.gz → 0.5.0__tar.gz

{easy_eo-0.4.2 → easy_eo-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: easy-eo
-Version: 0.4.2
+Version: 0.5.0
 Summary: A lightweight Earth Observation utilities library for chainable raster operations
 Project-URL: Homepage, https://github.com/tommy-burns/easy-eo
 Project-URL: Repository, https://github.com/tommy-burns/easy-eo
@@ -52,6 +52,10 @@ Requires-Dist: pre-commit>=3.7; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: lazy
+Requires-Dist: dask[array]>=2024.8; extra == 'lazy'
+Requires-Dist: rioxarray<1,>=0.17; extra == 'lazy'
+Requires-Dist: xarray>=2024.7; extra == 'lazy'
 Provides-Extra: stac
 Requires-Dist: planetary-computer<2,>=1.0; extra == 'stac'
 Requires-Dist: pystac-client<1,>=0.8; extra == 'stac'
@@ -253,13 +257,14 @@ conda install -c conda-forge easy-eo
 ```
 
 That is everything you need for the core: raster I/O, algebra, indices,
-preprocessing and plotting. Two heavier integrations are kept separate, so you
-only install them if you use them:
+preprocessing and plotting. Three heavier integrations are kept separate, so
+you only install them if you use them:
 
 | Adds | pip | conda |
 | --- | --- | --- |
 | `stac_search()` and loading scenes from STAC catalogs | `pip install "easy-eo[stac]"` | `conda install -c conda-forge easy-eo pystac-client planetary-computer` |
 | `to_xarray()` / `from_xarray()` | `pip install "easy-eo[xarray]"` | `conda install -c conda-forge easy-eo xarray rioxarray` |
+| Opening a raster lazily (`load_raster(path, chunks=...)`), including over HTTP | `pip install "easy-eo[lazy]"` | `conda install -c conda-forge easy-eo xarray rioxarray dask-core` |
 
 pip extras compose - `pip install "easy-eo[stac,xarray]"` installs both. conda
 has no concept of extras, so `conda install "easy-eo[stac]"` is not a valid

{easy_eo-0.4.2 → easy_eo-0.5.0}/README.md

@@ -191,13 +191,14 @@ conda install -c conda-forge easy-eo
 ```
 
 That is everything you need for the core: raster I/O, algebra, indices,
-preprocessing and plotting. Two heavier integrations are kept separate, so you
-only install them if you use them:
+preprocessing and plotting. Three heavier integrations are kept separate, so
+you only install them if you use them:
 
 | Adds | pip | conda |
 | --- | --- | --- |
 | `stac_search()` and loading scenes from STAC catalogs | `pip install "easy-eo[stac]"` | `conda install -c conda-forge easy-eo pystac-client planetary-computer` |
 | `to_xarray()` / `from_xarray()` | `pip install "easy-eo[xarray]"` | `conda install -c conda-forge easy-eo xarray rioxarray` |
+| Opening a raster lazily (`load_raster(path, chunks=...)`), including over HTTP | `pip install "easy-eo[lazy]"` | `conda install -c conda-forge easy-eo xarray rioxarray dask-core` |
 
 pip extras compose - `pip install "easy-eo[stac,xarray]"` installs both. conda
 has no concept of extras, so `conda install "easy-eo[stac]"` is not a valid

{easy_eo-0.4.2 → easy_eo-0.5.0}/eeo/__init__.py

@@ -40,4 +40,4 @@ __all__ = [
     "MissingDependencyError",
 ]
 
-__version__ = "0.4.2"
+__version__ = "0.5.0"

{easy_eo-0.4.2 → easy_eo-0.5.0}/eeo/_optional.py

@@ -24,14 +24,17 @@ from .core.exceptions import MissingDependencyError
 # list with nothing to opt into, and `conda install "easy-eo[stac]"` does not
 # merely miss the extra — it fails to parse, because brackets already mean
 # key-value constraints in conda's match syntax. So a conda user installs the
-# same packages by name. The names happen to equal the PyPI ones for every
-# current extra, but that is not a rule (conda-forge ships Matplotlib as
-# `matplotlib-base`), which is why the mapping is written out rather than
-# derived. tests/test_optional_dependencies.py checks it covers every declared
-# extra, so a new extra cannot ship without its conda equivalent.
+# same packages by name. The names usually equal the PyPI ones, but that is not
+# a rule: conda-forge's `dask` is a metapackage that also pulls in `distributed`
+# and `bokeh`, so the lazy extra maps to `dask-core`, the equivalent of pip's
+# `dask[array]` (as Matplotlib is `matplotlib-base`). That is why the mapping is
+# written out rather than derived. tests/test_optional_dependencies.py checks it
+# covers every declared extra, so a new extra cannot ship without its conda
+# equivalent.
 _CONDA_PACKAGES: dict[str, tuple[str, ...]] = {
     "stac": ("pystac-client", "planetary-computer"),
     "xarray": ("xarray", "rioxarray"),
+    "lazy": ("xarray", "rioxarray", "dask-core"),
 }
 
 

{easy_eo-0.4.2 → easy_eo-0.5.0}/eeo/common.py

@@ -40,6 +40,73 @@ def is_rasterio_backed(ds: EEORasterDataset) -> bool:
     return isinstance(ds._adapter, RasterioAdapter)
 
 
+def require_rasterio(ds: EEORasterDataset, operation: str) -> EEORasterDataset:
+    """Return ``ds`` on the rasterio backend, for an op that needs one.
+
+    A lazy dataset is promoted, which for a file-backed one reopens the file
+    and reads nothing. A NumPy-backed one is refused rather than promoted
+    silently: its pixels are already in memory and promoting copies all of
+    them, so that is the caller's decision to make.
+
+    Parameters
+    ----------
+    ds : EEORasterDataset
+        Dataset the operation was called on.
+    operation : str
+        Name of the operation, used in the error message.
+
+    Returns
+    -------
+    EEORasterDataset
+        ``ds`` itself when it is rasterio-backed, else a promoted copy.
+
+    Raises
+    ------
+    BackendError
+        If ``ds`` uses the NumPy backend.
+    """
+    from eeo.core.exceptions import BackendError
+
+    if is_rasterio_backed(ds):
+        return ds
+    if _is_promotable_without_reading(ds):
+        return ds.to_rasterio()
+    raise BackendError(
+        f"{operation} requires a rasterio-backed dataset; this dataset uses the "
+        "NumPy backend. Call .to_rasterio() first."
+    )
+
+
+def promote_for_decimated_read(ds: EEORasterDataset) -> EEORasterDataset:
+    """Return a dataset that can serve a decimated (``out_shape``) read.
+
+    Only the rasterio backend reads decimated. A lazy dataset reaches it by
+    reopening its file, which is what keeps plotting a large lazy raster from
+    reading it whole. Anything else is returned unchanged, for the caller to
+    fall back on a full read.
+
+    Parameters
+    ----------
+    ds : EEORasterDataset
+        Dataset about to be read for display.
+
+    Returns
+    -------
+    EEORasterDataset
+        ``ds``, or a rasterio-backed promotion of it that cost no read.
+    """
+    if not is_rasterio_backed(ds) and _is_promotable_without_reading(ds):
+        return ds.to_rasterio()
+    return ds
+
+
+def _is_promotable_without_reading(ds: EEORasterDataset) -> bool:
+    """Report whether ``ds`` can reach the rasterio backend without a read."""
+    from eeo.core.adapters import XarrayAdapter
+
+    return isinstance(ds._adapter, XarrayAdapter) and ds._adapter.source_path is not None
+
+
 def normalize_resampling_method(value):
     """Normalize a resampling method to a ``rasterio.enums.Resampling`` value."""
     from eeo.core.exceptions import ValidationError

easy_eo-0.5.0/eeo/core/adapters/__init__.py

@@ -0,0 +1,15 @@
+"""Backend adapters abstracting NumPy-, rasterio- and xarray-backed rasters."""
+
+from .base import BaseRasterAdapter
+from .numpy import NumpyRasterioAdapter
+from .rasterio import RasterioAdapter
+
+# Importing the module does not import xarray; the adapter does so on use.
+from .xarray import XarrayAdapter
+
+__all__ = [
+    "BaseRasterAdapter",
+    "RasterioAdapter",
+    "NumpyRasterioAdapter",
+    "XarrayAdapter",
+]

{easy_eo-0.4.2 → easy_eo-0.5.0}/eeo/core/adapters/base.py

@@ -16,8 +16,8 @@ from eeo.core.types import StrPath
 class BaseRasterAdapter(ABC):
     """Backend-agnostic interface that every raster backend must implement.
 
-    Concrete adapters (NumPy-backed, rasterio-backed, and future lazy
-    backends) implement these methods so that operations in ``eeo`` stay
+    Concrete adapters (NumPy-backed, rasterio-backed, and the lazy
+    xarray-backed one) implement these methods so that operations in ``eeo`` stay
     backend-agnostic. Metadata accessors return rasterio/affine types
     regardless of the underlying backend.
     """
@@ -122,7 +122,8 @@ class BaseRasterAdapter(ABC):
     def backend(self) -> Any:
         """Return the underlying backend object.
 
-        Returns the raw ``rasterio.DatasetReader`` or ``numpy.ndarray``.
+        Returns the raw ``rasterio.DatasetReader``, ``numpy.ndarray`` or
+        ``xarray.DataArray``.
         This bypasses Easy-EO's abstractions; use it only for interop.
         """
         ...

{easy_eo-0.4.2 → easy_eo-0.5.0}/eeo/core/adapters/rasterio.py

@@ -9,6 +9,7 @@ import rasterio as rio
 from rasterio.io import DatasetReader, DatasetWriter, MemoryFile
 
 from eeo.core.exceptions import BackendError
+from eeo.core.remote import open_env
 from eeo.core.types import StrPath
 
 from .base import BaseRasterAdapter
@@ -47,7 +48,8 @@ class RasterioAdapter(BaseRasterAdapter):
     @classmethod
     def from_path(cls, path: StrPath) -> RasterioAdapter:
         try:
-            dataset = rio.open(path)
+            with open_env(path):
+                dataset = rio.open(path)
         except Exception as e:
             raise BackendError(f"failed to open raster: {path}") from e
         return cls(dataset)

easy_eo-0.5.0/eeo/core/adapters/xarray.py

@@ -0,0 +1,393 @@
+"""Lazy, dask-chunked raster adapter backed by xarray."""
+
+from __future__ import annotations
+
+import itertools
+from collections.abc import Sequence
+from typing import Any
+
+import numpy as np
+import rasterio as rio
+from rasterio.coords import BoundingBox
+from rasterio.crs import CRS
+from rasterio.transform import Affine, array_bounds
+from rasterio.windows import Window
+
+from eeo._optional import import_optional
+from eeo.core.exceptions import BackendError, ValidationError
+from eeo.core.remote import open_env
+from eeo.core.types import ChunkSpec, StrPath
+
+from .base import BaseRasterAdapter
+
+_PURPOSE = "the lazy backend"
+_DIMS = ("band", "y", "x")
+_CHUNK_DIMS = frozenset(_DIMS)
+
+
+def _import_rioxarray() -> Any:
+    """Import rioxarray, which also registers the ``.rio`` accessor."""
+    return import_optional("rioxarray", extra="lazy", purpose=_PURPOSE)
+
+
+def _auto_chunk_sizes(src: Any) -> dict[str, int]:
+    """Return the chunk sizes ``chunks="auto"`` means for an open raster.
+
+    The same sizes :func:`rioxarray.open_rasterio` computes for ``"auto"``:
+    what dask would pick for the configured chunk size, snapped to the file's
+    own internal blocks. They are computed here so they can be passed as a
+    dict keyed by dimension. rioxarray passes its own as a dimension-order
+    tuple, which xarray deprecated and warns about — a warning its callers can
+    do nothing about, and which only versions needing Python 3.12 have stopped
+    emitting.
+
+    Parameters
+    ----------
+    src : rasterio.io.DatasetReader
+        The open raster, for its shape, dtype and block layout.
+
+    Returns
+    -------
+    dict of str to int
+        Chunk size for each of ``"band"``, ``"y"`` and ``"x"``.
+    """
+    dask_array = import_optional("dask.array", extra="lazy", purpose=_PURPOSE)
+    # One band per chunk, as rioxarray does: bands are stored separately, so a
+    # chunk spanning several of them would read from several places at once.
+    blocks = dask_array.core.normalize_chunks(
+        chunks=(1, "auto", "auto"),
+        shape=(src.count, src.height, src.width),
+        dtype=np.dtype(src.dtypes[0]),
+        previous_chunks=tuple((size,) for size in (1, *src.block_shapes[0])),
+    )
+    # normalize_chunks returns every block's size per dimension, regular apart
+    # from a possibly short last one; the first is the size that generates them.
+    return {dim: int(sizes[0]) for dim, sizes in zip(_DIMS, blocks, strict=True) if sizes}
+
+
+def validate_chunks(chunks: object) -> ChunkSpec:
+    """Check a chunk specification before it reaches dask.
+
+    Parameters
+    ----------
+    chunks : object
+        Candidate chunk specification.
+
+    Returns
+    -------
+    str or int or dict
+        ``chunks`` unchanged, once validated.
+
+    Raises
+    ------
+    ValidationError
+        If ``chunks`` is not ``"auto"``, a positive int, or a dict mapping
+        some of ``"band"``, ``"y"``, ``"x"`` to a positive int or ``"auto"``.
+    """
+
+    def valid_size(value: object) -> bool:
+        if value == "auto":
+            return True
+        return isinstance(value, int) and not isinstance(value, bool) and value > 0
+
+    if isinstance(chunks, dict):
+        unknown = set(chunks) - _CHUNK_DIMS
+        if not unknown and all(valid_size(v) for v in chunks.values()):
+            return chunks
+    elif valid_size(chunks):
+        return chunks  # type: ignore[return-value]
+    raise ValidationError(
+        "chunks must be 'auto', a positive int, or a dict mapping 'band', 'y' "
+        f"and/or 'x' to a positive int or 'auto'; got {chunks!r}"
+    )
+
+
+class XarrayAdapter(BaseRasterAdapter):
+    """Lazy raster adapter over a dask-chunked :class:`xarray.DataArray`.
+
+    Opening a raster through this adapter reads metadata only; pixels stay in
+    the file until something asks for them, and then only the requested bands
+    and window are computed. Needs the optional ``lazy`` extra
+    (``pip install "easy-eo[lazy]"``).
+
+    Prefer :meth:`from_path` over calling the constructor directly.
+
+    Parameters
+    ----------
+    dataarray : xarray.DataArray
+        Georeferenced array with dimensions ``("band", "y", "x")``, laid out
+        as :func:`rioxarray.open_rasterio` returns it, holding raw stored values
+        (not masked or scaled).
+    driver : str, default "GTiff"
+        GDAL driver of the source, reported in the metadata.
+    source_path : str or path-like or None, default None
+        File the array was opened from, when it was opened from one. It is
+        what lets a lazy dataset be promoted to the rasterio backend by
+        reopening the file rather than by reading every pixel.
+
+    Raises
+    ------
+    MissingDependencyError
+        If the ``lazy`` extra is not installed.
+    ValidationError
+        If ``dataarray`` does not have dimensions ``("band", "y", "x")``.
+    """
+
+    def __init__(
+        self, dataarray: Any, *, driver: str = "GTiff", source_path: StrPath | None = None
+    ) -> None:
+        _import_rioxarray()
+        if tuple(dataarray.dims) != _DIMS:
+            raise ValidationError(
+                f"dataarray must have dimensions {_DIMS}; got {tuple(dataarray.dims)}"
+            )
+        self._da = dataarray
+        self._driver = driver
+        self._source_path = source_path
+
+    # ========================
+    # Factories
+    # ========================
+    @classmethod
+    def from_path(cls, path: StrPath, *, chunks: ChunkSpec = "auto") -> XarrayAdapter:
+        """Open a raster file lazily, split into dask chunks.
+
+        Parameters
+        ----------
+        path : str or path-like
+            Path to a GDAL-readable raster.
+        chunks : str or int or dict, default "auto"
+            Chunk sizes, as :func:`rioxarray.open_rasterio` takes them.
+            ``"auto"`` lets dask pick sizes aligned with the file's internal
+            blocks.
+
+        Returns
+        -------
+        XarrayAdapter
+            Adapter over the unread raster.
+
+        Raises
+        ------
+        MissingDependencyError
+            If the ``lazy`` extra is not installed.
+        ValidationError
+            If ``chunks`` is not a valid chunk specification.
+        BackendError
+            If the file cannot be opened as a raster.
+        """
+        # Widened because "auto" is resolved to concrete sizes below, and a
+        # dict[str, int] is not a dict[str, int | Literal["auto"]] to a type
+        # checker: dict values are invariant.
+        spec: ChunkSpec | dict[str, int] = validate_chunks(chunks)
+        rioxarray = _import_rioxarray()
+        # dask is not imported by rioxarray itself; check it up front so a
+        # missing package is reported as the extra, not as an xarray error.
+        import_optional("dask.array", extra="lazy", purpose=_PURPOSE)
+        try:
+            with open_env(path):
+                # rasterio supplies the driver, which rioxarray does not
+                # record, and the block layout "auto" is resolved against.
+                with rio.open(path) as src:
+                    driver = src.driver
+                    if spec == "auto":
+                        spec = _auto_chunk_sizes(src)
+                dataarray = rioxarray.open_rasterio(path, chunks=spec)
+        except Exception as e:
+            raise BackendError(f"failed to open raster lazily: {path}") from e
+        return cls(dataarray, driver=driver, source_path=path)
+
+    @property
+    def source_path(self) -> StrPath | None:
+        """File this array was opened from, or None if it was not opened from one."""
+        return self._source_path
+
+    # ========================
+    # Metadata
+    # ========================
+    def get_crs(self) -> CRS:
+        return self._da.rio.crs
+
+    def get_transform(self) -> Affine:
+        return self._da.rio.transform()
+
+    def get_bounds(self) -> BoundingBox:
+        height, width = self.get_shape()
+        return BoundingBox(*array_bounds(height, width, self.get_transform()))
+
+    def get_shape(self) -> tuple[int, int]:
+        return self.get_height(), self.get_width()
+
+    def get_width(self) -> int:
+        return int(self._da.sizes["x"])
+
+    def get_height(self) -> int:
+        return int(self._da.sizes["y"])
+
+    def get_count(self) -> int:
+        return int(self._da.sizes["band"])
+
+    def get_nodata(self) -> float | None:
+        # rioxarray reports nodata as a scalar of the band dtype; rasterio
+        # reports a float, and the rest of the library expects that.
+        nodata = self._da.rio.nodata
+        return None if nodata is None else float(nodata)
+
+    def get_metadata(self) -> dict:
+        return {
+            "driver": self._driver,
+            "dtype": str(self._da.dtype),
+            "nodata": self.get_nodata(),
+            "width": self.get_width(),
+            "height": self.get_height(),
+            "count": self.get_count(),
+            "crs": self.get_crs(),
+            "transform": self.get_transform(),
+        }
+
+    def get_band_descriptions(self) -> list[str | None]:
+        # rioxarray stores GDAL band descriptions as ``long_name``: a plain
+        # string for one band, a tuple otherwise, absent when none are set.
+        long_name = self._da.attrs.get("long_name")
+        if long_name is None:
+            return [None] * self.get_count()
+        if isinstance(long_name, str):
+            long_name = (long_name,)
+        return [(name or None) for name in long_name]
+
+    # ========================
+    # Data Access
+    # ========================
+    def read(
+        self,
+        indexes: int | Sequence[int] | None = None,
+        *,
+        window: Window | tuple | None = None,
+        **kwargs,
+    ) -> np.ndarray:
+        """Compute the requested bands and window as a NumPy array.
+
+        Follows :meth:`rasterio.io.DatasetReader.read` for the arguments it
+        supports: only the selected bands and window are computed, so reading
+        a window of a scene larger than memory stays bounded.
+
+        Parameters
+        ----------
+        indexes : int or sequence of int or None, default None
+            1-based band index (returns a 2D array), a sequence of them, or
+            ``None`` for every band (both return a 3D array).
+        window : rasterio.windows.Window or tuple or None, default None
+            Integer pixel window to read, or ``((row_start, row_stop),
+            (col_start, col_stop))``. ``None`` reads the whole raster.
+        **kwargs
+            Any other rasterio read option. None is supported.
+
+        Returns
+        -------
+        numpy.ndarray
+            The requested pixels, as stored.
+
+        Raises
+        ------
+        BackendError
+            If a rasterio read option this backend does not support is given.
+        IndexError
+            If a band index is out of range.
+        ValidationError
+            If ``window`` has fractional offsets or sizes, or does not lie
+            within the raster.
+        """
+        if kwargs:
+            raise BackendError(
+                f"the lazy backend's read() supports indexes and window only; "
+                f"got {', '.join(sorted(kwargs))}"
+            )
+        bands: int | list[int] | slice
+        if indexes is None:
+            bands = slice(None)
+        elif isinstance(indexes, (int, np.integer)):
+            bands = self._band_position(int(indexes))
+        else:
+            bands = [self._band_position(int(i)) for i in indexes]
+
+        rows, cols = self._window_slices(window)
+        return self._compute(self._da.data[bands, rows, cols])
+
+    def read_band(self, idx: int) -> np.ndarray:
+        return self.read(idx)
+
+    def _band_position(self, idx: int) -> int:
+        """Map a 1-based band index to its 0-based array position."""
+        count = self.get_count()
+        if idx < 1 or idx > count:
+            raise IndexError(
+                f"band index {idx} out of range; dataset has {count} band(s) (valid 1..{count})"
+            )
+        return idx - 1
+
+    def _window_slices(self, window: Window | tuple | None) -> tuple[slice, slice]:
+        """Validate a pixel window and return its row and column slices."""
+        if window is None:
+            return slice(None), slice(None)
+        win = window if isinstance(window, Window) else Window.from_slices(*window)
+        bounds = (win.row_off, win.col_off, win.height, win.width)
+        if any(float(v) != int(v) for v in bounds):
+            raise ValidationError(f"window must have integer offsets and sizes; got {win}")
+        row, col, height, width = (int(v) for v in bounds)
+        if row < 0 or col < 0 or row + height > self.get_height() or col + width > self.get_width():
+            raise ValidationError(
+                f"window {win} does not lie within the raster "
+                f"({self.get_height()} x {self.get_width()} pixels)"
+            )
+        return slice(row, row + height), slice(col, col + width)
+
+    @staticmethod
+    def _compute(data: Any) -> np.ndarray:
+        """Materialise a selection as a NumPy array that owns its memory."""
+        if hasattr(data, "compute"):
+            return np.asarray(data.compute())
+        # An in-memory DataArray hands out views of its own buffer; copy, so a
+        # caller writing into the result cannot reach back into the dataset.
+        return np.array(data, copy=True)
+
+    # ========================
+    # Persistence
+    # ========================
+    def write(
+        self, path: StrPath, driver: str = "GTiff", band_names: list[str | None] | None = None
+    ) -> None:
+        # One dask chunk is computed and written at a time, so peak memory
+        # follows the chunk size, not the raster size.
+        meta = self.get_metadata()
+        meta.update(driver=driver)
+        data = self._da.data
+        chunks = getattr(data, "chunks", None) or tuple((n,) for n in data.shape)
+
+        with rio.open(path, "w", **meta) as dst:
+            for band_s, row_s, col_s in itertools.product(*(_spans(c) for c in chunks)):
+                block = self._compute(data[band_s, row_s, col_s])
+                dst.write(
+                    block,
+                    indexes=list(range(band_s.start + 1, band_s.stop + 1)),
+                    window=Window.from_slices(row_s, col_s),
+                )
+            # Unnamed bands are left alone so the file records no description.
+            for i, name in enumerate(band_names or [], start=1):
+                if name:
+                    dst.set_band_description(i, name)
+
+    def close(self) -> None:
+        self._da.close()
+
+    # ========================
+    # Backend Access
+    # ========================
+    @property
+    def backend(self) -> Any:
+        return self._da
+
+
+def _spans(sizes: Sequence[int]) -> list[slice]:
+    """Turn one axis's chunk sizes into consecutive slices."""
+    stops = np.cumsum(sizes).tolist()
+    starts = [0, *stops[:-1]]
+    return [slice(start, stop) for start, stop in zip(starts, stops, strict=True)]

{easy_eo-0.4.2 → easy_eo-0.5.0}/eeo/core/blockwise.py

@@ -25,6 +25,7 @@ from rasterio.windows import Window
 from eeo.common import (
     apply_nodata_mask,
     get_nodata,
+    resolve_band_index,
     resolve_output_dtype,
     resolve_output_nodata,
 )
@@ -86,7 +87,7 @@ class BlockSource:
         self.nodata = nodata
 
     @classmethod
-    def from_dataset(cls, ds: EEORasterDataset, *, band: int | None = None) -> BlockSource:
+    def from_dataset(cls, ds: EEORasterDataset, *, band: int | str | None = None) -> BlockSource:
         """Wrap a raster operand, promoting it to the rasterio backend.
 
         Promotion matters for correctness, not just speed: the NumPy adapter's
@@ -97,15 +98,25 @@ class BlockSource:
         ----------
         ds : EEORasterDataset
             Raster operand.
-        band : int or None, default None
-            1-based band index to read, or None to read every band.
+        band : int or str or None, default None
+            1-based band index or band name to read, or None to read every
+            band. A name is resolved as it is everywhere else a band is
+            addressed.
 
         Returns
         -------
         BlockSource
             Source reading ``ds`` one window at a time.
+
+        Raises
+        ------
+        IndexError
+            If an int index is outside the range of available bands.
+        ValidationError
+            If a name is unknown or declared on more than one band.
         """
-        return cls(dataset=ds.to_rasterio(), band=band, value=None, nodata=get_nodata(ds))
+        index = None if band is None else resolve_band_index(ds, band)
+        return cls(dataset=ds.to_rasterio(), band=index, value=None, nodata=get_nodata(ds))
 
     @classmethod
     def from_scalar(cls, value: float) -> BlockSource: