Skip to content

abczarr.drivers.base

What a driver is.

A Driver is the object abczarr opens Zarr through: zarr-python, TensorStore, or another backend. Each driver declares what it provides, through the same Support model the rest of the surface uses. That declaration covers both coarse capabilities, such as "sharding" and "async", and fine-grained feature keys, such as "v3:codec:zstd". A driver also answers whether it can open a given array, by comparing what the array's metadata requires against what the driver provides.

Which drivers exist, and how one is chosen for an array, is described in abczarr.api.registry.

Classes

Verdict 

Verdict(driver: str, missing: Iterable[str])

Whether a driver can open an array, and what it lacks if not.

bool(verdict) is True when nothing is missing. missing lists the feature keys the driver does not provide. reason renders a one-line explanation of the verdict.

Attributes

driver instance-attribute 
driver = driver
missing instance-attribute 
missing = tuple(sorted(missing))
reason property 
reason: str

Methods:

__bool__ 
__bool__() -> bool
__repr__ 
__repr__() -> str

Driver

Bases: SupportsCapabilities

A backend abczarr opens Zarr through.

A concrete driver declares what it provides, as capabilities and feature keys. Given an array's metadata, it answers whether it can open that array.

Attributes

name class-attribute 
name: str = ''
available property 
available: bool

Whether this driver's backend is installed and usable.

Methods:

can_open 
can_open(metadata: ArrayMetadata) -> Verdict

Whether this driver provides every feature metadata requires.

open 
open(location: Any, mode: str = 'r', *, asynchronous: bool = False) -> ZarrNode | Awaitable[AsyncZarrNode]

Open location and wrap it as a node.

Note

With asynchronous=True, the return value is a coroutine that must be awaited. The metadata read is awaited internally, so the open performs its I/O asynchronously and resolves to the coroutine twin of the node: an AsyncZarrArray or an AsyncZarrGroup. Whether that surface is native to the backend or synthesized in a thread pool depends on the driver. Without the flag, the node is opened synchronously and returned directly.

Parameters:

Name Type Description Default
location Any

The location to open.

 required
mode str

The access mode.

 'r'
asynchronous bool

When true, return a coroutine resolving to the async twin.

 False

Returns:

Type Description
ZarrNode or Awaitable[AsyncZarrNode]

The node, or, when asynchronous is true, a coroutine resolving to its async twin.

Raises:

Type Description
[UnsupportedZarrOperation][UnsupportedZarrOperation]

When this driver cannot open a location.
create 
create(location: Any, config: ZarrConfig, *, asynchronous: bool = False) -> ZarrNode | Awaitable[AsyncZarrNode]

Create the node config describes at location, and open it.

By default, config is lowered to a metadata document, and the node is created from that document. A backend may override the underlying create it runs to build the node through its own machinery from the config's coarse fields instead, so the backend writes its own metadata.

Note

With asynchronous=True, the return value is a coroutine that must be awaited, resolving to the async twin of the node. This mirrors async open.

Parameters:

Name Type Description Default
location Any

Where to create the node.

 required
config ZarrConfig

The array or group to create.

 required
asynchronous bool

When true, return a coroutine resolving to the async twin.

 False

Returns:

Type Description
ZarrNode or Awaitable[AsyncZarrNode]
create_from_metadata 
create_from_metadata(location: Any, metadata: NodeMetadata, *, overwrite: bool = False, asynchronous: bool = False) -> ZarrNode | Awaitable[AsyncZarrNode]

Create a node from an exact metadata document, and open it.

This method is the escape hatch for a setup the config helpers do not express. An ArrayMetadata or GroupMetadata document is written and opened exactly as given, with nothing resolved or filled in. By default, the metadata is written to the store and then opened. A driver may override the underlying create it runs to build the node through its own backend instead.

Note

With asynchronous=True, the return value is a coroutine that must be awaited, resolving to the async twin of the node.

Parameters:

Name Type Description Default
location Any

Where to create the node.

 required
metadata NodeMetadata

The exact metadata document to write.

 required
overwrite bool

Replace whatever is already at location.

 False
asynchronous bool

When true, return a coroutine resolving to the async twin.

 False

Returns:

Type Description
ZarrNode or Awaitable[AsyncZarrNode]

Raises:

Type Description
FileExistsError

When something already exists at location and overwrite is false.
create_group 
create_group(location: Any, *, config: ZarrConfig | None = None, **fields: Any) -> ZarrNode

Create a new group at location, and open it.

A GroupConfig may be passed as config. Its individual fields, such as zarr_version and overwrite, may instead be passed as keyword arguments. A keyword argument overrides the corresponding field of config.

Parameters:

Name Type Description Default
location Any

Where to create the group.

 required
config GroupConfig

The group to create. Defaults to a GroupConfig built from fields alone.

 None
**fields Any

Individual GroupConfig fields, overriding the matching field of config.

 {}

Returns:

Type Description
ZarrNode

The newly created group, opened through this driver.