abczarr.api.entrypoint

Open Zarr arrays and groups through a selected backend driver.

open opens a location and returns the array or group there, wrapped in the uniform surface. When no driver is named, it reads the array's metadata and picks a driver that provides every codec the array needs, described in [select_driver][abczarr.drivers.base.select_driver], then opens through that driver. open_array and open_group additionally check what they opened.

Functions:

open

open(path: PathLike, mode: str = ..., *, asynchronous: Literal[False] = ..., driver: _DriverArg = ..., **fields: Any) -> ZarrNode

open(path: PathLike, mode: str = ..., *, asynchronous: Literal[True], driver: _DriverArg = ..., **fields: Any) -> Awaitable[AsyncZarrNode]

Open, or on a create mode create, the Zarr node at path.

The mode follows the h5py/zarr convention, so open both opens an existing node and creates a new one:

mode	if it exists	if it is missing
`"r"`	open read-only	error
`"r+"`	open read-write	error
`"a"`	open	create
`"w"`	overwrite	create
`"w-"`, `"x"`	error	create

On a create mode the keyword fields describe the new node. These are the same fields create, ArrayConfig and GroupConfig accept. Array parameters, such as a shape or a dtype, create an array. With none, an empty group is created instead.

With asynchronous=True the return value is a coroutine that must be awaited. It opens or creates path through the backend's own async I/O and resolves to the coroutine twin of the node. Without it, the node is opened synchronously and returned directly.

Example

node = abczarr.open("data.zarr")                       # open (or make)
arr = abczarr.open("a.zarr", mode="w", shape=(4, 4), dtype="int8")
grp = abczarr.open("g.zarr", mode="w")                 # an empty group
node = await abczarr.open("data.zarr", asynchronous=True)  # async twin

Parameters:

Name	Type	Description	Default
`path`	`PathLike`	A local path or a URL, such as `"s3://bucket/dataset.zarr"`.	required
`mode`	`str`	The access mode, in the h5py/zarr convention described in the table above. `"r"` and `"r+"` open an existing node, read-only and read-write respectively, and error if it is missing. `"a"`, the default, opens it or creates one when nothing is there. `"w"` creates, overwriting whatever is there. `"w-"`, or its alias `"x"`, creates and fails if the target already exists.	`'a'`
`asynchronous`	`bool`	When true, return a coroutine that opens or creates `path` asynchronously and resolves to the coroutine twin, an AsyncZarrArray or AsyncZarrGroup, whose I/O is awaited. Whether that surface is native to the backend or synthesized in a thread pool is reported by `node.supports("async", native=True)`. When false, the default, the node is opened synchronously and returned directly.	`False`
`driver`	`str or Driver`	A driver, or its name, to open or create with. When omitted, a driver is chosen for what the node needs.	`None`
`**fields`	`Any`	Creation parameters, consulted only on a create mode. These are the fields an ArrayConfig or GroupConfig accepts.	`{}`

Returns:

Type	Description
`ZarrNode or Awaitable[AsyncZarrNode]`	The wrapped node directly, or, when `asynchronous` is true, a coroutine resolving to its async twin.

open_array

open_array(path: PathLike, mode: str = ..., *, asynchronous: Literal[False] = ..., driver: _DriverArg = ..., **fields: Any) -> ZarrArray

open_array(path: PathLike, mode: str = ..., *, asynchronous: Literal[True], driver: _DriverArg = ..., **fields: Any) -> Awaitable[AsyncZarrArray]

Open path, requiring it to be an array.

This function behaves like open, but raises if path is a group. On a create mode, fields must include array parameters, at least a shape. Creating a group this way is an error.

Parameters:

Name	Type	Description	Default
`path`	`PathLike`	A local path or a URL, such as `"s3://bucket/dataset.zarr"`.	required
`mode`	`str`	The access mode. See open for the modes and what each one does.	`'a'`
`asynchronous`	`bool`	When true, return a coroutine that opens or creates `path` asynchronously and resolves to the async array twin. When false, the default, the array is opened synchronously and returned directly.	`False`
`driver`	`str or Driver`	A driver, or its name, to open or create with. When omitted, a driver is chosen for what the array needs.	`None`
`**fields`	`Any`	Creation parameters, consulted only on a create mode. These are the fields an ArrayConfig accepts.	`{}`

Returns:

Type	Description
`ZarrArray or Awaitable[AsyncZarrArray]`	The wrapped array directly, or, when `asynchronous` is true, a coroutine resolving to its async twin.

open_group

open_group(path: PathLike, mode: str = ..., *, asynchronous: Literal[False] = ..., driver: _DriverArg = ..., **fields: Any) -> ZarrGroup

open_group(path: PathLike, mode: str = ..., *, asynchronous: Literal[True], driver: _DriverArg = ..., **fields: Any) -> Awaitable[AsyncZarrGroup]

Open path, requiring it to be a group.

This function behaves like open, but raises if path is an array. On a create mode, an empty group is created. Array parameters are an error.

Parameters:

Name	Type	Description	Default
`path`	`PathLike`	A local path or a URL, such as `"s3://bucket/dataset.zarr"`.	required
`mode`	`str`	The access mode. See open for the modes and what each one does.	`'a'`
`asynchronous`	`bool`	When true, return a coroutine that opens or creates `path` asynchronously and resolves to the async group twin. When false, the default, the group is opened synchronously and returned directly.	`False`
`driver`	`str or Driver`	A driver, or its name, to open or create with. When omitted, a driver is chosen for what the group needs.	`None`
`**fields`	`Any`	Creation parameters, consulted only on a create mode. These are the fields a GroupConfig accepts.	`{}`

Returns:

Type	Description
`ZarrGroup or Awaitable[AsyncZarrGroup]`	The wrapped group directly, or, when `asynchronous` is true, a coroutine resolving to its async twin.

create

create(location: PathLike, config: ArrayConfig | None = ..., *, data: Any, ome: Any = ..., asynchronous: Literal[False] = ..., **fields: Any) -> ZarrArray

create(location: PathLike, config: ArrayConfig | None = ..., *, data: Any, ome: Any = ..., asynchronous: Literal[True], **fields: Any) -> Awaitable[AsyncZarrArray]

create(location: PathLike, config: ArrayConfig, *, ome: Any = ..., asynchronous: Literal[False] = ..., **fields: Any) -> ZarrArray

create(location: PathLike, config: ArrayConfig, *, ome: Any = ..., asynchronous: Literal[True], **fields: Any) -> Awaitable[AsyncZarrArray]

create(location: PathLike, config: GroupConfig, *, ome: Any = ..., asynchronous: Literal[False] = ..., **fields: Any) -> ZarrGroup

create(location: PathLike, config: GroupConfig, *, ome: Any = ..., asynchronous: Literal[True], **fields: Any) -> Awaitable[AsyncZarrGroup]

create(location: PathLike, config: NodeMetadata, *, ome: Any = ..., asynchronous: Literal[False] = ..., **fields: Any) -> ZarrNode

create(location: PathLike, config: NodeMetadata, *, ome: Any = ..., asynchronous: Literal[True], **fields: Any) -> Awaitable[AsyncZarrNode]

Create the array or group config describes at location.

config is usually an ArrayConfig, which creates an array, or a GroupConfig, which creates a group. Keyword arguments override its fields, and the backend creates the node natively. For full control beyond what the config helpers express, config may instead be an exact metadata document, an ArrayMetadata or GroupMetadata, the lowered form a config would produce. Such a document is created as it is, and there driver and overwrite are the only accepted keywords. For a plain dict, wrap it first with ArrayMetadata.from_json(...) or ArrayConfig(**...).

An array is created from existing data when data is given. The array's shape and dtype then default to the data's. A shape or dtype in config or in the keyword arguments takes precedence over the data. The data is written into the new array, and config, when given, must be an ArrayConfig.

OME-Zarr metadata is written on the new node when ome is given. An OME object or a plain mapping is written as it is. An ImageConfig is lowered to base-level metadata first.

With asynchronous=True the return value is a coroutine that must be awaited. The backend creates through its own async I/O and resolves to the coroutine twin of the node, mirroring async open.

Example

arr = abczarr.create("a.zarr", ArrayConfig(shape=(4, 4), dtype="i1"))
arr = abczarr.create("a.zarr", data=np.zeros((4, 4), "i1"))
arr = await abczarr.create(
    "a.zarr", ArrayConfig(shape=(4, 4), dtype="i1"), asynchronous=True
)

Parameters:

Name	Type	Description	Default
`location`	`PathLike`	A local path or a URL, such as `"s3://bucket/dataset.zarr"`.	required
`config`	`(ArrayConfig, GroupConfig or NodeMetadata)`	What to create. An `ArrayConfig` or `GroupConfig` describes the node through abczarr's own creation options. An `ArrayMetadata` or `GroupMetadata` document is created exactly as it is. Omitted when `data` alone describes the array to create.	`None`
`data`	`array - like`	Existing data to size the new array from and write into it. Requires `config` to be an `ArrayConfig`, or omitted entirely.	`None`
`ome`	`(OME, ImageConfig or dict)`	OME-Zarr metadata to write on the new node.	`None`
`asynchronous`	`bool`	When true, return a coroutine that creates the node asynchronously and resolves to its coroutine twin. When false, the default, the node is created synchronously and returned directly.	`False`
`**fields`	`Any`	Individual fields that override the same field on `config`, such as `chunks` or `compressor`. Not accepted when `config` is a metadata document. There, only `driver` and `overwrite` are accepted.	`{}`

Returns:

Type	Description
`ZarrNode or Awaitable[AsyncZarrNode]`	The newly created node directly, or, when `asynchronous` is true, a coroutine resolving to its async twin.

create_group

create_group(location: PathLike, *, config: GroupConfig | None = ..., asynchronous: Literal[False] = ..., **fields: Any) -> ZarrGroup

create_group(location: PathLike, *, config: GroupConfig | None = ..., asynchronous: Literal[True], **fields: Any) -> Awaitable[AsyncZarrGroup]

Create a group at location, the metadata-free way.

Parameters:

Name	Type	Description	Default
`location`	`PathLike`	A local path or a URL, such as `"s3://bucket/group.zarr"`.	required
`config`	`GroupConfig`	A reusable GroupConfig. Individual fields, such as `zarr_version` or `overwrite`, may also be passed as keyword arguments, which override the config.	`None`
`asynchronous`	`bool`	When true, return a coroutine that creates the group asynchronously and resolves to the async group twin, mirroring async create. When false, the default, the group is created synchronously and returned directly.	`False`
`**fields`	`Any`	Individual GroupConfig fields that override the same field on `config`.	`{}`

Returns:

Type	Description
`ZarrGroup or Awaitable[AsyncZarrGroup]`	The newly created group directly, or, when `asynchronous` is true, a coroutine resolving to its async twin.

create_array

create_array(location: PathLike, *, config: ArrayConfig | None = ..., asynchronous: Literal[False] = ..., **fields: Any) -> ZarrArray

create_array(location: PathLike, *, config: ArrayConfig | None = ..., asynchronous: Literal[True], **fields: Any) -> Awaitable[AsyncZarrArray]

Create an array at location, the metadata-free way.

At least a shape, and a dtype, is needed to describe the array. A request with no array fields describes a group instead, so create_group should be used for that.

Parameters:

Name	Type	Description	Default
`location`	`PathLike`	A local path or a URL, such as `"s3://bucket/array.zarr"`.	required
`config`	`ArrayConfig`	A reusable ArrayConfig. Individual fields, such as `shape`, `dtype` or `chunks`, may also be passed as keyword arguments, which override the config.	`None`
`asynchronous`	`bool`	When true, return a coroutine that creates the array asynchronously and resolves to the async array twin, mirroring async create. When false, the default, the array is created synchronously and returned directly.	`False`
`**fields`	`Any`	Individual ArrayConfig fields that override the same field on `config`.	`{}`

Returns:

Type	Description
`ZarrArray or Awaitable[AsyncZarrArray]`	The newly created array directly, or, when `asynchronous` is true, a coroutine resolving to its async twin.