Reference#
The API surface of pyramids_lazy, generated from the docstrings by
mkdocstrings.
What this package publishes is one backend object, not an API you call directly. It is
registered with pyramids-core through the pyramids.compute_backend entry-point group, so
installing the package is the whole integration: pyramids then dispatches every lazy operation to
it.
from pyramids.netcdf import NetCDF
cube = NetCDF.read_file("era5.nc")
arr = cube.read_array(variable="pr", chunks="auto") # → this package's read_array_lazy
So the backend contract below is the surface that matters. Each method forwards to one implementation module, and each module has its own page.
| Backend method | Backs | Page |
|---|---|---|
read_array_lazy |
NetCDF.read_array(chunks=…) (not Dataset) |
Lazy raster reads |
build_lazy_cube |
NetCDF.chunk() |
Lazy NetCDF cube |
to_dask_dataframe |
NetCDF.to_dask_dataframe() |
Dask dataframe view |
open_mfdataset |
NetCDF.open_mfdataset() |
Multi-file reads |
to_kerchunk, combine_kerchunk |
NetCDF.to_kerchunk(), DatasetCollection.to_kerchunk() |
Kerchunk manifests |
write_dataset_to_zarr, read_dataset_from_zarr, classify_zarr_store |
Dataset.to_zarr() / from_zarr(), read_file GeoZarr routing |
Zarr (Dataset) |
write_collection_to_zarr, read_collection_from_zarr |
DatasetCollection.to_zarr() / from_zarr() |
Zarr (DatasetCollection) |
read_vector_lazy, read_vector_parquet_lazy |
FeatureCollection.read_file(backend="dask") / read_parquet(backend="dask") |
Lazy vector reads |
lazy_netcdf_type, lazy_feature_collection_type |
the classes core forwards its public names to | Backend contract |
The contract itself#
pyramids.base._compute_backend.ComputeBackend is the authoritative Protocol — the method
signatures here mirror it one-for-one, and it is the file to read before changing one. The backend
declares an api_version that core checks on resolution; adding a Protocol method is additive and
does not bump it, while removing a name or changing semantics does.
Two public view classes are re-exported from the package root, because core forwards its own public
pyramids.netcdf.LazyNetCDF and pyramids.feature.LazyFeatureCollection names — and their
isinstance checks — to them:
LazyNetCDF— a wrapper holding one dask array per gridded variableLazyFeatureCollection— adask_geopandas.GeoDataFramesubclass
Package root#
pyramids_lazy
#
pyramids-lazy: the lazy / dask compute backend for pyramids.
This package implements the ComputeBackend contract published by pyramids-core and registers
it under the pyramids.compute_backend entry-point group. Installing pyramids-lazy alongside
pyramids-core turns on every lazy/dask operation (raster, raster-cube and vector) without the
dask/zarr stack ever being pulled into a bare pyramids-core install.
Discovery works two ways, both resolving to the same singleton :data:backend:
- the
pyramids.compute_backendentry point (pyramids_lazy.backend:backend), the path core prefers; and - :func:
get_compute_backend, the first-party fallback core calls by name when no entry point is registered (e.g. an editable checkout onPYTHONPATHwith no installed metadata).
The lazy view classes are public here so core can forward its public names (and their isinstance
checks) to them: today core forwards pyramids.netcdf.LazyNetCDF and
pyramids.feature.LazyFeatureCollection. :class:LazyMeshDataset is exposed on the same footing so
core can forward a pyramids.netcdf.ugrid.LazyMeshDataset name once its mesh half ships -- the
core-side MeshDataset.open_mfdataset(chunks=...) forwarder (serapeum-org/pyramids-core#1458) is not
released yet, so no shipped core forwards this one today. :class:LazyNetCDF and
:class:LazyMeshDataset import eagerly (they need only dask at call time); LazyFeatureCollection
is resolved lazily via module __getattr__ because its module hard-imports dask_geopandas (the
[parquet] extra).
get_compute_backend()
#
Return the singleton compute backend (core's first-party fallback entry point).
pyramids.base._compute_backend.require_compute_backend calls this by name when no backend is
registered on the pyramids.compute_backend entry-point group, so the plugin is usable from a
bare checkout on PYTHONPATH as well as from an installed distribution.