zarr.abc.store

Classes

ByteGetter	Base class for protocol classes.
ByteSetter	Base class for protocol classes.
Store	Abstract base class for Zarr stores.

Functions

set_or_delete(→ None)

Set or delete a value in a byte setter

Module Contents

class zarr.abc.store.ByteGetter

Bases: Protocol

Base class for protocol classes.

Protocol classes are defined as:

class Proto(Protocol):
    def meth(self) -> int:
        ...

Such classes are primarily used with static type checkers that recognize structural subtyping (static duck-typing).

For example:

class C:
    def meth(self) -> int:
        return 0

def func(x: Proto) -> int:
    return x.meth()

func(C())  # Passes static type check

See PEP 544 for details. Protocol classes decorated with @typing.runtime_checkable act as simple-minded runtime protocols that check only the presence of given attributes, ignoring their type signatures. Protocol classes can be generic, they are defined as:

class GenProto[T](Protocol):
    def meth(self) -> T:
        ...

async get(

prototype: zarr.core.buffer.BufferPrototype,

byte_range: ByteRequest | None = None,

) → zarr.core.buffer.Buffer | None

class zarr.abc.store.ByteSetter

Bases: Protocol

Base class for protocol classes.

Protocol classes are defined as:

class Proto(Protocol):
    def meth(self) -> int:
        ...

Such classes are primarily used with static type checkers that recognize structural subtyping (static duck-typing).

For example:

class C:
    def meth(self) -> int:
        return 0

def func(x: Proto) -> int:
    return x.meth()

func(C())  # Passes static type check

See PEP 544 for details. Protocol classes decorated with @typing.runtime_checkable act as simple-minded runtime protocols that check only the presence of given attributes, ignoring their type signatures. Protocol classes can be generic, they are defined as:

class GenProto[T](Protocol):
    def meth(self) -> T:
        ...

async delete() → None

async get(

prototype: zarr.core.buffer.BufferPrototype,

byte_range: ByteRequest | None = None,

) → zarr.core.buffer.Buffer | None

async set(

value: zarr.core.buffer.Buffer,

byte_range: ByteRequest | None = None,

) → None

async set_if_not_exists(default: zarr.core.buffer.Buffer) → None

class zarr.abc.store.Store(*, read_only: bool = False)

Bases: abc.ABC

Abstract base class for Zarr stores.

async clear() → None

Clear the store.

Remove all keys and values from the store.

close() → None

Close the store.

abstract delete(key: str) → None

Async:

Remove a key from the store

Parameters:

keystr

async delete_dir(prefix: str) → None

Remove all keys and prefixes in the store that begin with a given prefix.

abstract exists(key: str) → bool

Async:

Check if a key exists in the store.

Parameters:

keystr

Returns:

bool

abstract get(

key: str,

prototype: zarr.core.buffer.BufferPrototype,

byte_range: ByteRequest | None = None,

) → zarr.core.buffer.Buffer | None

Async:

Retrieve the value associated with a given key.

Parameters:

keystr

byte_rangeByteRequest, optional

ByteRequest may be one of the following. If not provided, all data associated with the key is retrieved.

• RangeByteRequest(int, int): Request a specific range of bytes in the form (start, end). The end is exclusive. If the given range is zero-length or starts after the end of the object, an error will be returned. Additionally, if the range ends after the end of the object, the entire remainder of the object will be returned. Otherwise, the exact requested range will be returned.

• OffsetByteRequest(int): Request all bytes starting from a given byte offset. This is equivalent to bytes={int}- as an HTTP header.

• SuffixByteRequest(int): Request the last int bytes. Note that here, int is the size of the request, not the byte offset. This is equivalent to bytes=-{int} as an HTTP header.

Returns:

Buffer

abstract get_partial_values(

prototype: zarr.core.buffer.BufferPrototype,

key_ranges: collections.abc.Iterable[tuple[str, ByteRequest | None]],

) → list[zarr.core.buffer.Buffer | None]

Async:

Retrieve possibly partial values from given key_ranges.

Parameters:

key_rangesIterable[tuple[str, tuple[int | None, int | None]]]

Ordered set of key, range pairs, a key may occur multiple times with different ranges

Returns:

list of values, in the order of the key_ranges, may contain null/none for missing keys

async getsize(key: str) → int

Return the size, in bytes, of a value in a Store.

Parameters:

keystr

Returns:

nbytesint

The size of the value (in bytes).

Raises:

FileNotFoundError

When the given key does not exist in the store.

async getsize_prefix(prefix: str) → int

Return the size, in bytes, of all values under a prefix.

Parameters:

prefixstr

The prefix of the directory to measure.

Returns:

nbytesint

The sum of the sizes of the values in the directory (in bytes).

See also

zarr.Array.nbytes_stored

Store.getsize

Notes

getsize_prefix is just provided as a potentially faster alternative to listing all the keys under a prefix calling Store.getsize() on each.

In general, prefix should be the path of an Array or Group in the Store. Implementations may differ on the behavior when some other prefix is provided.

async is_empty(prefix: str) → bool

Check if the directory is empty.

Parameters:

prefixstr

Prefix of keys to check.

Returns:

bool

True if the store is empty, False otherwise.

abstract list() → collections.abc.AsyncIterator[str]

Retrieve all keys in the store.

Returns:

AsyncIterator[str]

abstract list_dir(prefix: str) → collections.abc.AsyncIterator[str]

Retrieve all keys and prefixes with a given prefix and which do not contain the character “/” after the given prefix.

Parameters:

prefixstr

Returns:

AsyncIterator[str]

abstract list_prefix(prefix: str) → collections.abc.AsyncIterator[str]

Retrieve all keys in the store that begin with a given prefix. Keys are returned relative to the root of the store.

Parameters:

prefixstr

Returns:

AsyncIterator[str]

classmethod open(*args: Any, **kwargs: Any) → Self

Async:

Create and open the store.

Parameters:

*argsAny

Positional arguments to pass to the store constructor.

**kwargsAny

Keyword arguments to pass to the store constructor.

Returns:

Store

The opened store instance.

abstract set(key: str, value: zarr.core.buffer.Buffer) → None

Async:

Store a (key, value) pair.

Parameters:

keystr

valueBuffer

async set_if_not_exists(key: str, value: zarr.core.buffer.Buffer) → None

Store a key to value if the key is not already present.

Parameters:

keystr

valueBuffer

abstract set_partial_values(

key_start_values: collections.abc.Iterable[tuple[str, int, zarr.core.common.BytesLike]],

) → None

Async:

Store values at a given key, starting at byte range_start.

Parameters:

key_start_valueslist[tuple[str, int, BytesLike]]

set of key, range_start, values triples, a key may occur multiple times with different range_starts, range_starts (considering the length of the respective values) must not specify overlapping ranges for the same key

property read_only: bool

Is the store read-only?

property supports_deletes: bool

Abstractmethod:

Does the store support deletes?

property supports_listing: bool

Abstractmethod:

Does the store support listing?

property supports_partial_writes: bool

Abstractmethod:

Does the store support partial writes?

property supports_writes: bool

Abstractmethod:

Does the store support writes?

async zarr.abc.store.set_or_delete(

byte_setter: ByteSetter,

value: zarr.core.buffer.Buffer | None,

) → None

Set or delete a value in a byte setter

Parameters:

byte_setterByteSetter

valueBuffer | None

Notes

If value is None, the key will be deleted.