Skip to content

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:

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_backend entry 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 on PYTHONPATH with 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.