`ngff_zarr._remote_reader`¶

Remote OME-Zarr reads through zarrista’s async API over obstore.

zarrista’s synchronous Array/Group only accept its closed store union (FilesystemStore/MemoryStore/ZipStore); remote object stores are reached through AsyncArray/AsyncGroup over any obstore store (HTTP(S), S3, GCS, Azure). This module bridges that async surface to ngff-zarr’s synchronous read path:

Every zarrista coroutine runs on a dedicated daemon event-loop thread. asyncio.run would fail inside environments that already run a loop (e.g. Jupyter), and zarrista’s pyo3 futures require a running loop at call time, so calls are submitted as coroutine factories executed inside the loop.
fsspec-style storage_options are translated to obstore configuration where a mapping exists; unrecognized keys are first passed through verbatim (so obstore-native option names keep working) and dropped with a warning only when obstore rejects them.
class:

RemoteZarrGroup/:class:RemoteZarrArray provide the same read surface as the compat layer’s LocalZarrGroup/LocalZarrArray.

zarrista requires Python >= 3.11 and obstore is an optional dependency (the remote extra), so both are imported lazily inside each function.

Module Contents¶

Classes¶

`RemoteZarrStore`	Handle for a remote OME-Zarr store read via zarrista’s async API.
`RemoteZarrArray`	Read-only handle for an array node within a remote store.
`RemoteZarrGroup`	Read-only handle for a group node within a remote store.

Functions¶

`remote_read_available`	Whether the zarrista/obstore remote read engine can be used.
`_io_loop`	The shared event loop running on a daemon thread, started on demand.
`_run`	Execute the awaitable produced by factory on the IO loop.
`_translate_storage_options`	Split fsspec-style storage_options into obstore option dicts.
`_resolve_bucket_region`	The region AWS reports for bucket, or `None` if it does not say.
`_fill_bucket_region`	Add the bucket’s region to translated when nothing else supplies one.
`_build_obstore`	Construct the obstore store for url, translating storage_options.
`_async_adapter`	dask adapter over an `AsyncArray`, fetching through the IO loop.
`_remote_array_to_dask`	Wrap `AsyncArray` arr as a lazy dask array on its chunk grid.
`_is_missing_metadata`
`_fetch_v2_group_attrs`	The `.zattrs` of the zarr format 2 group at component, if one exists.
`open_remote_node`	Open the node at component within remote store.
`open_remote_lazy`	Open the array at component within store as a lazy dask array.

Data¶

`__all__`
`_REMOTE_READ_AVAILABLE`
`_MISSING_METADATA_MARKER`
`_IO_LOOP`
`_IO_LOOP_LOCK`
`_S3_ALIASES`
`_GS_ALIASES`
`_AZURE_ALIASES`
`_HTTP_ALIASES`
`_SCHEME_ALIASES`
`_CLIENT_KWARGS_ALIASES`
`_BUCKET_REGIONS`
`_REGION_TIMEOUT`

API¶

ngff_zarr._remote_reader.__all__¶: [‘RemoteZarrArray’, ‘RemoteZarrGroup’, ‘RemoteZarrStore’, ‘open_remote_lazy’, ‘open_remote_node’, ‘r…

ngff_zarr._remote_reader._REMOTE_READ_AVAILABLE: bool | None¶: None

ngff_zarr._remote_reader._MISSING_METADATA_MARKER¶: ‘metadata is missing’

ngff_zarr._remote_reader.remote_read_available() → bool¶: Whether the zarrista/obstore remote read engine can be used.

ngff_zarr._remote_reader._IO_LOOP: asyncio.AbstractEventLoop | None¶: None

ngff_zarr._remote_reader._IO_LOOP_LOCK¶: ‘Lock(…)’

ngff_zarr._remote_reader._io_loop() → asyncio.AbstractEventLoop¶: The shared event loop running on a daemon thread, started on demand.

ngff_zarr._remote_reader._run(factory)¶

Execute the awaitable produced by factory on the IO loop.

factory is a zero-argument callable evaluated inside the loop, not a coroutine object: zarrista’s pyo3 methods create their futures at call time and require the running loop to exist then.

ngff_zarr._remote_reader._S3_ALIASES¶: None

ngff_zarr._remote_reader._GS_ALIASES¶: None

ngff_zarr._remote_reader._AZURE_ALIASES¶: None

ngff_zarr._remote_reader._HTTP_ALIASES¶: None

ngff_zarr._remote_reader._SCHEME_ALIASES¶: None

ngff_zarr._remote_reader._CLIENT_KWARGS_ALIASES¶: None

ngff_zarr._remote_reader._translate_storage_options( scheme: str, storage_options: dict | None, ) → tuple[dict, dict]¶

Split fsspec-style storage_options into obstore option dicts.

Returns (translated, passthrough): translated holds options with a known obstore equivalent, passthrough the remaining keys forwarded verbatim (they may already be obstore-native names). The caller drops the passthrough set with a warning when obstore rejects it.

ngff_zarr._remote_reader._BUCKET_REGIONS: dict[str, str]¶: None

ngff_zarr._remote_reader._REGION_TIMEOUT¶: 10.0

ngff_zarr._remote_reader._resolve_bucket_region(bucket: str) → str | None¶

The region AWS reports for bucket, or None if it does not say.

obstore sends the request to us-east-1 when no region is configured, and S3 answers for a bucket held elsewhere with a 301 that carries no Location, so the read fails instead of being redirected. AWS names the region in a header on the bucket itself, and answers unsigned.

ngff_zarr._remote_reader._fill_bucket_region(url: str, translated: dict, passthrough: dict) → None¶: Add the bucket’s region to translated when nothing else supplies one.

ngff_zarr._remote_reader._build_obstore(url: str, storage_options: dict | None)¶: Construct the obstore store for url, translating storage_options.

class ngff_zarr._remote_reader.RemoteZarrStore(url: str, storage_options: dict | None = None, prefix: str = '')¶

Handle for a remote OME-Zarr store read via zarrista’s async API.

Wraps the obstore store for url plus an optional node prefix (HCS well/field views). str() is the full URL so shared error messages keep pointing at what the user passed in.

Initialization

with_prefix(prefix: str) → ngff_zarr._remote_reader.RemoteZarrStore¶: A view of the same store narrowed to prefix (joined to any existing prefix). The underlying obstore client is shared.

node_path(component: str | None = None) → str¶: The zarrista node path for component under this view’s prefix.

__str__() → str¶

ngff_zarr._remote_reader._async_adapter(arr)¶: dask adapter over an AsyncArray, fetching through the IO loop.

ngff_zarr._remote_reader._remote_array_to_dask(arr) → dask.array.Array¶

Wrap AsyncArray arr as a lazy dask array on its chunk grid.

Mirrors the sync zarrista_array_to_dask: sharded arrays chunk on the subchunk (inner chunk) shape so reads stay at the efficient granularity.

class ngff_zarr._remote_reader.RemoteZarrArray( store: ngff_zarr._remote_reader.RemoteZarrStore, component: str, arr, )¶

Read-only handle for an array node within a remote store.

The read half of :class:~ngff_zarr._zarrista_utils.LocalZarrArray: the node’s shape, dtype, chunks and attrs, numpy style [] reads, and :meth:to_dask for lazy pixel access. Writes are refused, a remote store being read-only here.

Initialization

_array()¶: The synchronous adapter over the async node, made once.

property dtype: numpy.dtype¶

property chunks: tuple[int, ...]¶: The stored chunk grid, the inner chunk shape of a sharded array.

__getitem__(selection) → numpy.ndarray¶

__setitem__(selection, value) → None¶

to_dask() → dask.array.Array¶

class ngff_zarr._remote_reader.RemoteZarrGroup( store: ngff_zarr._remote_reader.RemoteZarrStore, component: str, group, )¶

Read-only handle for a group node within a remote store.

Provides the slice of the group surface the read path uses – attrs (a dict with asdict()), __contains__/__getitem__ path navigation, and keys() – backed by zarrista AsyncGroup metadata reads. Child arrays open their pixel data lazily.

Initialization

_child_component(name) → str¶

__getitem__(name)¶

__contains__(name) → bool¶

keys() → list[str]¶

Names of all immediate child nodes, sorted.

Requires a store that supports listing (S3/GCS/Azure); plain HTTP servers generally do not, in which case this returns an empty list with a warning – remote navigation should rely on metadata-declared paths instead.

ngff_zarr._remote_reader._is_missing_metadata(error: Exception) → bool¶

ngff_zarr._remote_reader._fetch_v2_group_attrs( store: ngff_zarr._remote_reader.RemoteZarrStore, component: str | None, ) → dict | None¶

The .zattrs of the zarr format 2 group at component, if one exists.

Used when auto-detection opened a format 3 group with empty attributes: like the local read path, a spurious zarr.json sitting on top of a format 2 store must not hide the real .zgroup/.zattrs documents. Returns None when there is no format 2 group here.

ngff_zarr._remote_reader.open_remote_node( store: ngff_zarr._remote_reader.RemoteZarrStore, component: str | None = None, )¶

Open the node at component within remote store.

Returns a :class:RemoteZarrGroup or :class:RemoteZarrArray, or None when neither node type exists there (missing metadata). zarrista auto-detects the zarr format, preferring format 3; transport and store errors propagate unchanged.

ngff_zarr._remote_reader.open_remote_lazy( store: ngff_zarr._remote_reader.RemoteZarrStore, component: str | None = None, ) → dask.array.Array¶: Open the array at component within store as a lazy dask array.

ngff_zarr._remote_reader¶

Module Contents¶

Classes¶

Functions¶

Data¶

API¶

`ngff_zarr._remote_reader`¶