Store

Available stores.

AsyncStore module-attribute

AsyncStore: TypeAlias = 'ObjectStore | Session | AsyncZipStore'

A store that the async API accepts.

This is an obstore ObjectStore, an icechunk Session, or an AsyncZipStore. An ObjectStore supports any object-store backend, such as S3, GCS, or the local filesystem. A Session gives a transactional, versioned store.

Note: the Rust extension serializes an icechunk Session and reconstructs it as a separate icechunk instance. That instance must also be able to read the session's data. Therefore, keep the data in storage such as a local filesystem or S3. A session from icechunk.in_memory_storage() does not work, because the data exists only in the Python process, and the reads cannot find it.

SyncStore module-attribute

SyncStore: TypeAlias = FilesystemStore | MemoryStore | ZipStore

A store that the sync API accepts.

This is a FilesystemStore, a MemoryStore, or a ZipStore.

AsyncZipStore

A read-only store backed by a zip file that another async store holds.

This is the async form of ZipStore. Use it with AsyncArray and AsyncGroup.

This store is read only and does not support writing.

open async staticmethod

open(store: AsyncStore, key: str, *, path: str | None = None) -> AsyncZipStore

Open the zip file that is stored at key in store.

Parameters:

• store (AsyncStore) –

  The async store that holds the zip file.

• key (str) –

  The store key of the zip file, such as archive.zip.

• path (str | None, default: None ) –

  The directory inside the zip file to use as the root of this store. A value of None uses the whole zip file. The store accepts nested, nested/, and /nested/ as the same directory.

Returns:

• AsyncZipStore –

  The store for the zip file at key.

Raises:

• StorageError –

  If store holds no value at key, or if that value is not a valid zip file.

• ValueError –

  If key is not a valid store key.

FilesystemStore

A store backed by a local directory.

__init__

__init__(path: str | Path) -> None

Open a filesystem store rooted at path.

This does not check that path exists. The store reports an error only when you read from it or write to it.

Parameters:

• path (str | Path) –

  The path to the root directory of the store.

MemoryStore

An in-memory store, primarily useful for testing.

ZipStore

A read-only store backed by a zip file that another store holds.

The store reads the zip metadata when you open it, and then serves each Zarr key from an entry in the zip file.

This store is read only and does not support writing.

Examples:

Open a Zarr array that is held in a local zip file:

>>> from zarrista import Array
>>> from zarrista.store import FilesystemStore, ZipStore
>>> backing = FilesystemStore("/data")
>>> store = ZipStore(backing, "archive.zip")
>>> array = Array.open(store)

__init__

__init__(store: SyncStore, key: str, *, path: str | None = None) -> None

Open the zip file that is stored at key in store.

Parameters:

• store (SyncStore) –

  The store that holds the zip file.

• key (str) –

  The store key of the zip file, such as archive.zip.

• path (str | None, default: None ) –

  The directory inside the zip file to use as the root of this store. A value of None uses the whole zip file. The store accepts nested, nested/, and /nested/ as the same directory.

Raises:

• StorageError –

  If store holds no value at key, or if that value is not a valid zip file.

• ValueError –

  If key is not a valid store key.

open staticmethod

open(store: SyncStore, key: str, *, path: str | None = None) -> ZipStore

Open the zip file that is stored at key in store.

This is an alias for ZipStore.

Parameters:

• store (SyncStore) –

  The store that holds the zip file.

• key (str) –

  The store key of the zip file, such as archive.zip.

• path (str | None, default: None ) –

  The directory inside the zip file to use as the root of this store. A value of None uses the whole zip file. The store accepts nested, nested/, and /nested/ as the same directory.

Returns:

• ZipStore –

  The store for the zip file at key.

Raises:

• StorageError –

  If store holds no value at key, or if that value is not a valid zip file.

• ValueError –

  If key is not a valid store key.