`ngff_zarr._v2_store_reader`¶

Minimal pure-Python reader for zarr MutableMapping stores.

zarrista only opens FilesystemStore/MemoryStore/ZipStore — its SyncStore is a closed union with no way to feed it an arbitrary key-to-bytes mapping (see the Phase 01 capability matrix). This module covers the store types that therefore cannot go through zarrista: zip archives read as name-to-bytes mappings, tifffile’s aszarr virtual store, and plain in-memory dicts.

The zarr format 2 reader parses .zgroup/.zattrs/.zarray documents (consolidated .zmetadata is used for all metadata lookups when present, matching zarr-python’s consolidated semantics) and decodes chunks with numcodecs (compressor + filters, C/F order, fill_value for missing chunks, . and / dimension separators). A companion zarr format 3 reader parses zarr.json documents for unsharded arrays whose codec chain is the bytes codec plus numcodecs-decodable compression (what tifffile’s aszarr store serves); sharded v3 stores must be read through zarrista. Arrays are exposed as lazy dask arrays with one delayed chunk fetch per stored chunk. This module intentionally imports neither zarr-python nor zarrista.

Module Contents¶

Classes¶

`AttrsDict`	Plain dict exposing zarr-python’s `Attributes.asdict()` surface.
`_BytesBufferShim`	Buffer factory returning plain `bytes`, ducking zarr’s Buffer API.
`_BytesPrototypeShim`	The `prototype.buffer` surface async stores build results through.
`AsyncStoreMapping`	Read-only `Mapping[str, bytes]` view over an async byte store.
`_V2Source`	A `MutableMapping[str, bytes]` plus its consolidated metadata.
`_LazyChunkedArray`	Shared lazy-dask surface for chunked array nodes read from a mapping.
`V2Array`	A zarr format 2 array node read lazily from a bytes mapping.
`V2Group`	A zarr format 2 group node read from a bytes mapping.
`V3Array`	An unsharded zarr format 3 array node read lazily from a bytes mapping.
`V3Group`	A zarr format 3 group node read from a bytes mapping.

Functions¶

`_normalize_path`	Normalize a node path to the store-key form (no leading/trailing /).
`_decode_dtype`	Decode a `.zarray` dtype: a numpy string or the structured list form.
`_parse_fill_value`	Decode a JSON `fill_value` to a numpy scalar of dtype.
`_run_coroutine`	Run coro to completion from synchronous code.
`_doc_key`
`open_v2`	Open the node at path within a v2 bytes-mapping store.
`open_v2_array`	Open the array node at path within a v2 bytes-mapping store.
`open_v2_group`	Open the group node at path within a v2 bytes-mapping store.
`_v3_bytes_codec`	A numcodecs codec that decodes the given v3 bytes-to-bytes codec.
`open_v3`	Open the node at path within a v3 bytes-mapping store.
`open_store_node`	Open the node at path within store, auto-detecting the zarr format.
`open_store_array`	Open the array node at path within store (either zarr format).

Data¶

`__all__`
`_FLOAT_FILLS`
`_V3_BLOSC_SHUFFLE`

API¶

ngff_zarr._v2_store_reader.__all__¶: [‘AsyncStoreMapping’, ‘AttrsDict’, ‘V2Array’, ‘V2Group’, ‘V3Array’, ‘V3Group’, ‘open_store_array’, ‘…

ngff_zarr._v2_store_reader._FLOAT_FILLS¶: None

class ngff_zarr._v2_store_reader.AttrsDict¶

Bases: dict

Plain dict exposing zarr-python’s Attributes.asdict() surface.

Lets the read path treat node attributes uniformly across backends (zarr-python groups, this reader, the compat-layer local reader).

Initialization

Initialize self. See help(type(self)) for accurate signature.

asdict() → dict¶

ngff_zarr._v2_store_reader._normalize_path(path) → str¶: Normalize a node path to the store-key form (no leading/trailing /).

ngff_zarr._v2_store_reader._decode_dtype(spec) → numpy.dtype¶: Decode a .zarray dtype: a numpy string or the structured list form.

ngff_zarr._v2_store_reader._parse_fill_value(fill, dtype: numpy.dtype)¶

Decode a JSON fill_value to a numpy scalar of dtype.

None (JSON null, “undefined” in the v2 spec) maps to zero, matching what zarr-python materializes for missing chunks in that case. Float specials arrive as the strings "NaN"/"Infinity"/"-Infinity"; fixed-length bytes and structured fills arrive base64-encoded.

ngff_zarr._v2_store_reader._run_coroutine(coro)¶

Run coro to completion from synchronous code.

Chunk fetches happen inside dask worker threads, which have no running event loop; when one is running (e.g. the caller’s thread in Jupyter), the coroutine runs on a private loop in a helper thread instead.

class ngff_zarr._v2_store_reader._BytesBufferShim¶

Buffer factory returning plain bytes, ducking zarr’s Buffer API.

static from_bytes(data) → bytes¶

static from_array_like(array_like) → bytes¶

class ngff_zarr._v2_store_reader._BytesPrototypeShim¶

The prototype.buffer surface async stores build results through.

buffer¶: None

class ngff_zarr._v2_store_reader.AsyncStoreMapping(store)¶

Bases: collections.abc.Mapping

Read-only Mapping[str, bytes] view over an async byte store.

Adapts stores implementing the zarr-python 3 async Store interface (await get(key, prototype), async for key in list()) – e.g. tifffile’s aszarr ZarrTiffStore – to the bytes-mapping surface

Func:: open_v2 consumes, without importing zarr-python: the prototype handed to get is a minimal shim producing plain bytes.

Iteration yields the store’s listable keys (for tifffile these are the metadata documents; chunk keys are computed on demand), which is exactly the surface :class:_V2Source needs for metadata lookups and child listing. Missing keys – including chunks the store reports as absent – raise KeyError, which the reader materializes as fill_value.

Initialization

__getitem__(key: str) → bytes¶

_list_keys() → list[str]¶

__iter__() → collections.abc.Iterator[str]¶

__len__() → int¶

class ngff_zarr._v2_store_reader._V2Source(mapping: collections.abc.Mapping)¶

A MutableMapping[str, bytes] plus its consolidated metadata.

Shared by every node opened from one store so .zmetadata is parsed once. When consolidated metadata is present it is the sole source for metadata documents and child listing (zarr-python’s consolidated semantics); chunk payloads always come from the mapping.

Initialization

raw(key: str) → bytes | None¶

doc(key: str) → dict | None¶: The metadata JSON document at key, or None when absent.

metadata_keys() → collections.abc.Iterator[str]¶

ngff_zarr._v2_store_reader._doc_key(path: str, doc_name: str) → str¶

class ngff_zarr._v2_store_reader._LazyChunkedArray¶

Shared lazy-dask surface for chunked array nodes read from a mapping.

Subclasses set shape/chunks/dtype/ndim and implement _read_chunk(chunk_index) -> np.ndarray returning the in-bounds extent at that grid position.

property size: int¶

_trim_edge_chunk( chunk: numpy.ndarray, chunk_index: tuple[int, ...], ) → numpy.ndarray¶

Trim a full-shape stored chunk to its in-bounds extent.

Both zarr formats store edge chunks padded to the full chunk shape.

to_dask() → dask.array.Array¶

The array as a lazy dask array chunked on the stored chunk grid.

One delayed chunk fetch per stored chunk; nothing is read until compute. pure=False keeps dask from tokenizing the fetch arguments, which would hash (or choke on) the backing store object.

class ngff_zarr._v2_store_reader.V2Array(source: ngff_zarr._v2_store_reader._V2Source, path: str, meta: dict)¶

Bases: ngff_zarr._v2_store_reader._LazyChunkedArray

A zarr format 2 array node read lazily from a bytes mapping.

Initialization

_chunk_key(chunk_index: tuple[int, ...]) → str¶

_decode_chunk(raw) → numpy.ndarray¶

_read_chunk(chunk_index: tuple[int, ...]) → numpy.ndarray¶

class ngff_zarr._v2_store_reader.V2Group(source: ngff_zarr._v2_store_reader._V2Source, path: str)¶

A zarr format 2 group node read from a bytes mapping.

Initialization

_child_path(name) → str¶

__contains__(name) → bool¶

__getitem__(name)¶

open_array(name) → ngff_zarr._v2_store_reader.V2Array¶

open_group(name) → ngff_zarr._v2_store_reader.V2Group¶

_child_names(doc_name: str) → list[str]¶

array_keys() → list[str]¶: Names of the immediate child arrays, sorted.

group_keys() → list[str]¶: Names of the immediate child groups, sorted.

keys() → list[str]¶: Names of all immediate child nodes (arrays and groups), sorted.

ngff_zarr._v2_store_reader.open_v2(store: collections.abc.Mapping, path=None)¶

Open the node at path within a v2 bytes-mapping store.

Returns a :class:V2Array or :class:V2Group depending on the node type (arrays win when both documents exist, matching zarr-python), or raises KeyError when neither metadata document is present.

ngff_zarr._v2_store_reader.open_v2_array( store: collections.abc.Mapping, path=None, ) → ngff_zarr._v2_store_reader.V2Array¶: Open the array node at path within a v2 bytes-mapping store.

ngff_zarr._v2_store_reader.open_v2_group( store: collections.abc.Mapping, path=None, ) → ngff_zarr._v2_store_reader.V2Group¶: Open the group node at path within a v2 bytes-mapping store.

ngff_zarr._v2_store_reader._V3_BLOSC_SHUFFLE¶: None

ngff_zarr._v2_store_reader._v3_bytes_codec(codec: dict)¶: A numcodecs codec that decodes the given v3 bytes-to-bytes codec.

class ngff_zarr._v2_store_reader.V3Array(mapping: collections.abc.Mapping, path: str, doc: dict)¶

Bases: ngff_zarr._v2_store_reader._LazyChunkedArray

An unsharded zarr format 3 array node read lazily from a bytes mapping.

Supports the bytes array-to-bytes codec (either endian) followed by numcodecs-decodable compression. The sharding and transpose codecs are rejected: stores using them should be read through zarrista instead.

Initialization

_chunk_key(chunk_index: tuple[int, ...]) → str¶

_read_chunk(chunk_index: tuple[int, ...]) → numpy.ndarray¶

class ngff_zarr._v2_store_reader.V3Group(mapping: collections.abc.Mapping, path: str, doc: dict)¶

A zarr format 3 group node read from a bytes mapping.

Initialization

_child_path(name) → str¶

_child_doc(path: str) → dict | None¶

__contains__(name) → bool¶

__getitem__(name)¶

_child_names(node_type: str) → list[str]¶

array_keys() → list[str]¶: Names of the immediate child arrays, sorted.

group_keys() → list[str]¶: Names of the immediate child groups, sorted.

keys() → list[str]¶: Names of all immediate child nodes (arrays and groups), sorted.

ngff_zarr._v2_store_reader.open_v3(store: collections.abc.Mapping, path=None)¶

Open the node at path within a v3 bytes-mapping store.

Returns a :class:V3Array or :class:V3Group, or raises KeyError when no zarr.json document is present at that path.

ngff_zarr._v2_store_reader.open_store_node(store: collections.abc.Mapping, path=None)¶

Open the node at path within store, auto-detecting the zarr format.

Zarr format 3 (zarr.json) wins when both formats are present, matching zarr-python’s auto-detection order.

ngff_zarr._v2_store_reader.open_store_array(store: collections.abc.Mapping, path=None)¶: Open the array node at path within store (either zarr format).

ngff_zarr._v2_store_reader¶

Module Contents¶

Classes¶

Functions¶

Data¶

API¶

`ngff_zarr._v2_store_reader`¶