`zarr.api.asynchronous`

zarr.api.asynchronous ¶

PathLike `module-attribute` ¶

PathLike = str

all `module-attribute` ¶

__all__ = [
    "array",
    "consolidate_metadata",
    "copy",
    "copy_all",
    "copy_store",
    "create",
    "create_array",
    "create_hierarchy",
    "empty",
    "empty_like",
    "from_array",
    "full",
    "full_like",
    "group",
    "load",
    "ones",
    "ones_like",
    "open",
    "open_array",
    "open_consolidated",
    "open_group",
    "open_like",
    "save",
    "save_array",
    "save_group",
    "tree",
    "zeros",
    "zeros_like",
]

ArrayLike ¶

ArrayLike = AnyAsyncArray | AnyArray | NDArray[Any]

array `async` ¶

array(
    data: ArrayLike | AnyArray, **kwargs: Any
) -> AnyAsyncArray

Create an array filled with data.

Parameters:

data (array_like) –

The data to fill the array with.
**kwargs (Any, default: {} ) –

Passed through to create.

Returns:

array ( array ) –

The new array.

Source code in src/zarr/api/asynchronous.py

async def array(data: npt.ArrayLike | AnyArray, **kwargs: Any) -> AnyAsyncArray:
    """Create an array filled with `data`.

    Parameters
    ----------
    data : array_like
        The data to fill the array with.
    **kwargs
        Passed through to [`create`][zarr.api.asynchronous.create].

    Returns
    -------
    array : array
        The new array.
    """

    if isinstance(data, Array):
        return await from_array(data=data, **kwargs)

    # ensure data is array-like
    if not hasattr(data, "shape") or not hasattr(data, "dtype"):
        data = np.asanyarray(data)

    # setup dtype
    kw_dtype = kwargs.get("dtype")
    if kw_dtype is None and hasattr(data, "dtype"):
        kwargs["dtype"] = data.dtype
    else:
        kwargs["dtype"] = kw_dtype

    # setup shape and chunks
    data_shape, data_chunks = _get_shape_chunks(data)
    kwargs["shape"] = data_shape
    kw_chunks = kwargs.get("chunks")
    if kw_chunks is None:
        kwargs["chunks"] = data_chunks
    else:
        kwargs["chunks"] = kw_chunks

    read_only = kwargs.pop("read_only", False)
    if read_only:
        raise ValueError("read_only=True is no longer supported when creating new arrays")

    # instantiate array
    z = await create(**kwargs)

    # fill with data
    await z.setitem(Ellipsis, data)

    return z

consolidate_metadata `async` ¶

consolidate_metadata(
    store: StoreLike,
    path: str | None = None,
    zarr_format: ZarrFormat | None = None,
) -> AsyncGroup

Consolidate the metadata of all nodes in a hierarchy.

Upon completion, the metadata of the root node in the Zarr hierarchy will be updated to include all the metadata of child nodes. For Stores that do not support consolidated metadata, this operation raises a TypeError.

Parameters:

store (StoreLike) –

The store-like object whose metadata you wish to consolidate. See the storage documentation in the user guide for a description of all valid StoreLike values.
path (str, default: None ) –

A path to a group in the store to consolidate at. Only children below that group will be consolidated.

By default, the root node is used so all the metadata in the store is consolidated.
zarr_format ((2, 3, None), default: 2 ) –

The zarr format of the hierarchy. By default the zarr format is inferred.

Returns:

group ( AsyncGroup ) –

The group, with the consolidated_metadata field set to include the metadata of each child node. If the Store doesn't support consolidated metadata, this function raises a TypeError. See Store.supports_consolidated_metadata.

Source code in src/zarr/api/asynchronous.py

async def consolidate_metadata(
    store: StoreLike,
    path: str | None = None,
    zarr_format: ZarrFormat | None = None,
) -> AsyncGroup:
    """
    Consolidate the metadata of all nodes in a hierarchy.

    Upon completion, the metadata of the root node in the Zarr hierarchy will be
    updated to include all the metadata of child nodes. For Stores that do
    not support consolidated metadata, this operation raises a `TypeError`.

    Parameters
    ----------
    store : StoreLike
        The store-like object whose metadata you wish to consolidate. See the
        [storage documentation in the user guide][user-guide-store-like]
        for a description of all valid StoreLike values.
    path : str, optional
        A path to a group in the store to consolidate at. Only children
        below that group will be consolidated.

        By default, the root node is used so all the metadata in the
        store is consolidated.
    zarr_format : {2, 3, None}, optional
        The zarr format of the hierarchy. By default the zarr format
        is inferred.

    Returns
    -------
    group: AsyncGroup
        The group, with the `consolidated_metadata` field set to include
        the metadata of each child node. If the Store doesn't support
        consolidated metadata, this function raises a `TypeError`.
        See `Store.supports_consolidated_metadata`.
    """
    store_path = await make_store_path(store, path=path)

    if not store_path.store.supports_consolidated_metadata:
        store_name = type(store_path.store).__name__
        raise TypeError(
            f"The Zarr Store in use ({store_name}) doesn't support consolidated metadata",
        )

    group = await AsyncGroup.open(store_path, zarr_format=zarr_format, use_consolidated=False)
    group.store_path.store._check_writable()

    members_metadata = {
        k: v.metadata
        async for k, v in group.members(max_depth=None, use_consolidated_for_children=False)
    }
    # While consolidating, we want to be explicit about when child groups
    # are empty by inserting an empty dict for consolidated_metadata.metadata
    for k, v in members_metadata.items():
        if isinstance(v, GroupMetadata) and v.consolidated_metadata is None:
            v = dataclasses.replace(v, consolidated_metadata=ConsolidatedMetadata(metadata={}))
            members_metadata[k] = v

    if any(m.zarr_format == 3 for m in members_metadata.values()):
        warnings.warn(
            "Consolidated metadata is currently not part in the Zarr format 3 specification. It "
            "may not be supported by other zarr implementations and may change in the future.",
            category=ZarrUserWarning,
            stacklevel=1,
        )

    ConsolidatedMetadata._flat_to_nested(members_metadata)

    consolidated_metadata = ConsolidatedMetadata(metadata=members_metadata)
    metadata = dataclasses.replace(group.metadata, consolidated_metadata=consolidated_metadata)
    group = dataclasses.replace(
        group,
        metadata=metadata,
    )
    await group._save_metadata()
    return group

copy `async` ¶

copy(*args: Any, **kwargs: Any) -> tuple[int, int, int]

Not implemented.

Source code in src/zarr/api/asynchronous.py

async def copy(*args: Any, **kwargs: Any) -> tuple[int, int, int]:
    """
    Not implemented.
    """
    raise NotImplementedError

copy_all `async` ¶

copy_all(*args: Any, **kwargs: Any) -> tuple[int, int, int]

Not implemented.

Source code in src/zarr/api/asynchronous.py

async def copy_all(*args: Any, **kwargs: Any) -> tuple[int, int, int]:
    """
    Not implemented.
    """
    raise NotImplementedError

copy_store `async` ¶

copy_store(
    *args: Any, **kwargs: Any
) -> tuple[int, int, int]

Not implemented.

Source code in src/zarr/api/asynchronous.py

async def copy_store(*args: Any, **kwargs: Any) -> tuple[int, int, int]:
    """
    Not implemented.
    """
    raise NotImplementedError

create `async` ¶

create(
    shape: tuple[int, ...] | int,
    *,
    chunks: ChunksLike | None = None,
    dtype: ZDTypeLike | None = None,
    compressor: CompressorLike = "auto",
    fill_value: Any | None = DEFAULT_FILL_VALUE,
    order: MemoryOrder | None = None,
    store: StoreLike | None = None,
    synchronizer: Any | None = None,
    overwrite: bool = False,
    path: PathLike | None = None,
    chunk_store: StoreLike | None = None,
    filters: Iterable[dict[str, JSON] | Numcodec]
    | None = None,
    cache_metadata: bool | None = None,
    cache_attrs: bool | None = None,
    read_only: bool | None = None,
    object_codec: Codec | None = None,
    dimension_separator: Literal[".", "/"] | None = None,
    write_empty_chunks: bool | None = None,
    zarr_format: ZarrFormat | None = None,
    meta_array: Any | None = None,
    attributes: dict[str, JSON] | None = None,
    chunk_shape: ChunksLike | None = None,
    chunk_key_encoding: ChunkKeyEncoding
    | tuple[Literal["default"], Literal[".", "/"]]
    | tuple[Literal["v2"], Literal[".", "/"]]
    | None = None,
    codecs: Iterable[Codec | dict[str, JSON]] | None = None,
    dimension_names: DimensionNamesLike = None,
    storage_options: dict[str, Any] | None = None,
    config: ArrayConfigLike | None = None,
    mode: AccessModeLiteral | None = None,
    data: ArrayLike | None = None,
) -> AnyAsyncArray

Create an array.

Parameters:

shape (int or tuple of ints) –

Array shape.
chunks (ChunksLike, default: None ) –

Chunk shape. If None (the default), it is guessed from shape and dtype. If False, it is set to shape, i.e., a single chunk for the whole array. If an int, the chunk size in each dimension is given by the value of chunks. True is not a chunk shape and raises a ValueError.
dtype (str or dtype, default: None ) –

NumPy dtype.
compressor (Codec, default: 'auto' ) –

Primary compressor to compress chunk data. Zarr format 2 only. Zarr format 3 arrays should use codecs instead.

If neither compressor nor filters are provided, the default compressor zarr.codecs.ZstdCodec is used.

If compressor is set to None, no compression is used.
fill_value (Any, default: DEFAULT_FILL_VALUE ) –

Fill value for the array.
order (('C', 'F'), default: 'C' ) –

Deprecated in favor of the config keyword argument. Pass {'order': <value>} to create instead of using this parameter. Memory layout to be used within each chunk. If not specified, the array.order parameter in the global config will be used.
store (StoreLike or None, default: None ) –

StoreLike object to open. See the storage documentation in the user guide for a description of all valid StoreLike values.
synchronizer (object, default: None ) –

Array synchronizer.
overwrite (bool, default: False ) –

If True, delete all pre-existing data in store at path before creating the array.
path (str, default: None ) –

Path under which array is stored.
chunk_store (StoreLike or None, default: None ) –

Separate storage for chunks. If not provided, store will be used for storage of both chunks and metadata.
filters (Iterable[Codec] | Literal['auto'], default: None ) –

Iterable of filters to apply to each chunk of the array, in order, before serializing that chunk to bytes.

For Zarr format 3, a "filter" is a codec that takes an array and returns an array, and these values must be instances of zarr.abc.codec.ArrayArrayCodec, or a dict representations of zarr.abc.codec.ArrayArrayCodec.

For Zarr format 2, a "filter" can be any numcodecs codec; you should ensure that the order of your filters is consistent with the behavior of each filter.

The default value of "auto" instructs Zarr to use a default based on the data type of the array and the Zarr format specified. For all data types in Zarr V3, and most data types in Zarr V2, the default filters are empty. The only cases where default filters are not empty is when the Zarr format is 2, and the data type is a variable-length data type like zarr.dtype.VariableLengthUTF8 or zarr.dtype.VariableLengthBytes. In these cases, the default filters contains a single element which is a codec specific to that particular data type.

To create an array with no filters, provide an empty iterable or the value None.
cache_metadata (bool, default: None ) –

If True, array configuration metadata will be cached for the lifetime of the object. If False, array metadata will be reloaded prior to all data access and modification operations (may incur overhead depending on storage and data access pattern).
cache_attrs (bool, default: None ) –

If True (default), user attributes will be cached for attribute read operations. If False, user attributes are reloaded from the store prior to all attribute read operations.
read_only (bool, default: None ) –

True if array should be protected against modification.
object_codec (Codec, default: None ) –

A codec to encode object arrays, only needed if dtype=object.
dimension_separator (('.', '/'), default: '.' ) –

Separator placed between the dimensions of a chunk. Zarr format 2 only. Zarr format 3 arrays should use chunk_key_encoding instead.
write_empty_chunks (bool, default: None ) –

Deprecated in favor of the config keyword argument. Pass {'write_empty_chunks': <value>} to create instead of using this parameter. If True, all chunks will be stored regardless of their contents. If False, each chunk is compared to the array's fill value prior to storing. If a chunk is uniformly equal to the fill value, then that chunk is not be stored, and the store entry for that chunk's key is deleted.
zarr_format ((2, 3, None), default: 2 ) –

The Zarr format to use when creating an array. The default is None, which instructs Zarr to choose the default Zarr format value defined in the runtime configuration.
meta_array (array - like, default: None ) –

Not implemented.
attributes (dict[str, JSON], default: None ) –

A dictionary of user attributes to store with the array.
chunk_shape (ChunksLike, default: None ) –

The shape of the Array's chunks (default is None). Zarr format 3 only. Zarr format 2 arrays should use chunks instead.
chunk_key_encoding (ChunkKeyEncoding, default: None ) –

A specification of how the chunk keys are represented in storage. Zarr format 3 only. Zarr format 2 arrays should use dimension_separator instead. Default is ("default", "/").
codecs (Sequence of Codecs or dicts, default: None ) –

An iterable of Codec or dict serializations of Codecs. Zarr V3 only.

The elements of codecs specify the transformation from array values to stored bytes. Zarr format 3 only. Zarr format 2 arrays should use filters and compressor instead.

If no codecs are provided, default codecs will be used based on the data type of the array. For most data types, the default codecs are the tuple (BytesCodec(), ZstdCodec()); data types that require a special zarr.abc.codec.ArrayBytesCodec, like variable-length strings or bytes, will use the zarr.abc.codec.ArrayBytesCodec required for the data type instead of zarr.codecs.BytesCodec.
dimension_names (Iterable[str | None] | None = None, default: None ) –

An iterable of dimension names. Zarr format 3 only.
storage_options (dict, default: None ) –

If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.
config (ArrayConfigLike, default: None ) –

Runtime configuration of the array. If provided, will override the default values from zarr.config.array.
mode (('r', 'r+', 'a', 'w', 'w-'), default: 'r' ) –
Legacy way to control overwriting, kept for compatibility with Zarr-Python 2. Prefer overwrite. The access mode used to open store; the default, None, is 'a'.
- 'a' and 'r+' create the array and fail if a node exists at path, unless overwrite is True.
- 'w' replaces anything stored under path (the whole store if path is not set), even if overwrite is False. On a store that cannot delete keys, 'w' raises an error instead of replacing an existing node.
- 'w-' fails if anything is stored under path, even if overwrite is True.
- 'r' always fails.
If store is a StorePath, mode is not validated against it: 'w' still sets overwrite, and the other modes have no effect.
data (array - like, default: None ) –

Values written into the new array after it is created. Unlike the data parameter of create_array, it does not set the shape or data type of the array. To create an array from existing data, use create_array(data=...). A Zarr array is not supported as data.

Returns:

z ( array ) –

The array.

Source code in src/zarr/api/asynchronous.py

async def create(
    shape: tuple[int, ...] | int,
    *,  # Note: this is a change from v2
    chunks: ChunksLike | None = None,
    dtype: ZDTypeLike | None = None,
    compressor: CompressorLike = "auto",
    fill_value: Any | None = DEFAULT_FILL_VALUE,
    order: MemoryOrder | None = None,
    store: StoreLike | None = None,
    synchronizer: Any | None = None,
    overwrite: bool = False,
    path: PathLike | None = None,
    chunk_store: StoreLike | None = None,
    filters: Iterable[dict[str, JSON] | Numcodec] | None = None,
    cache_metadata: bool | None = None,
    cache_attrs: bool | None = None,
    read_only: bool | None = None,
    object_codec: Codec | None = None,  # TODO: type has changed
    dimension_separator: Literal[".", "/"] | None = None,
    write_empty_chunks: bool | None = None,
    zarr_format: ZarrFormat | None = None,
    meta_array: Any | None = None,  # TODO: need type
    attributes: dict[str, JSON] | None = None,
    # v3 only
    chunk_shape: ChunksLike | None = None,
    chunk_key_encoding: (
        ChunkKeyEncoding
        | tuple[Literal["default"], Literal[".", "/"]]
        | tuple[Literal["v2"], Literal[".", "/"]]
        | None
    ) = None,
    codecs: Iterable[Codec | dict[str, JSON]] | None = None,
    dimension_names: DimensionNamesLike = None,
    storage_options: dict[str, Any] | None = None,
    config: ArrayConfigLike | None = None,
    mode: AccessModeLiteral | None = None,
    data: npt.ArrayLike | None = None,
) -> AnyAsyncArray:
    """Create an array.

    Parameters
    ----------
    shape : int or tuple of ints
        Array shape.
    chunks : ChunksLike, optional
        Chunk shape. If None (the default), it is guessed from `shape` and `dtype`. If
        False, it is set to `shape`, i.e., a single chunk for the whole array. If an
        int, the chunk size in each dimension is given by the value of `chunks`.
        `True` is not a chunk shape and raises a `ValueError`.
    dtype : str or dtype, optional
        NumPy dtype.
    compressor : Codec, optional
        Primary compressor to compress chunk data.
        Zarr format 2 only. Zarr format 3 arrays should use `codecs` instead.

        If neither `compressor` nor `filters` are provided, the default compressor
        [`zarr.codecs.ZstdCodec`][] is used.

        If `compressor` is set to `None`, no compression is used.
    fill_value : Any, optional
        Fill value for the array.
    order : {'C', 'F'}, optional
        Deprecated in favor of the `config` keyword argument.
        Pass `{'order': <value>}` to `create` instead of using this parameter.
        Memory layout to be used within each chunk.
        If not specified, the `array.order` parameter in the global config will be used.
    store : StoreLike or None, default=None
        StoreLike object to open. See the
        [storage documentation in the user guide][user-guide-store-like]
        for a description of all valid StoreLike values.
    synchronizer : object, optional
        Array synchronizer.
    overwrite : bool, optional
        If True, delete all pre-existing data in `store` at `path` before
        creating the array.
    path : str, optional
        Path under which array is stored.
    chunk_store : StoreLike or None, default=None
        Separate storage for chunks. If not provided, `store` will be used
        for storage of both chunks and metadata.
    filters : Iterable[Codec] | Literal["auto"], optional
        Iterable of filters to apply to each chunk of the array, in order, before serializing that
        chunk to bytes.

        For Zarr format 3, a "filter" is a codec that takes an array and returns an array,
        and these values must be instances of [`zarr.abc.codec.ArrayArrayCodec`][], or a
        dict representations of [`zarr.abc.codec.ArrayArrayCodec`][].

        For Zarr format 2, a "filter" can be any numcodecs codec; you should ensure that the
        order of your filters is consistent with the behavior of each filter.

        The default value of `"auto"` instructs Zarr to use a default based on the data
        type of the array and the Zarr format specified. For all data types in Zarr V3, and most
        data types in Zarr V2, the default filters are empty. The only cases where default filters
        are not empty is when the Zarr format is 2, and the data type is a variable-length data type like
        [`zarr.dtype.VariableLengthUTF8`][] or [`zarr.dtype.VariableLengthBytes`][]. In these cases,
        the default filters contains a single element which is a codec specific to that particular data type.

        To create an array with no filters, provide an empty iterable or the value `None`.
    cache_metadata : bool, optional
        If True, array configuration metadata will be cached for the
        lifetime of the object. If False, array metadata will be reloaded
        prior to all data access and modification operations (may incur
        overhead depending on storage and data access pattern).
    cache_attrs : bool, optional
        If True (default), user attributes will be cached for attribute read
        operations. If False, user attributes are reloaded from the store prior
        to all attribute read operations.
    read_only : bool, optional
        True if array should be protected against modification.
    object_codec : Codec, optional
        A codec to encode object arrays, only needed if dtype=object.
    dimension_separator : {'.', '/'}, optional
        Separator placed between the dimensions of a chunk.
        Zarr format 2 only. Zarr format 3 arrays should use `chunk_key_encoding` instead.
    write_empty_chunks : bool, optional
        Deprecated in favor of the `config` keyword argument.
        Pass `{'write_empty_chunks': <value>}` to `create` instead of using this parameter.
        If True, all chunks will be stored regardless of their
        contents. If False, each chunk is compared to the array's fill value
        prior to storing. If a chunk is uniformly equal to the fill value, then
        that chunk is not be stored, and the store entry for that chunk's key
        is deleted.
    zarr_format : {2, 3, None}, optional
        The Zarr format to use when creating an array. The default is `None`,
        which instructs Zarr to choose the default Zarr format value defined in the
        runtime configuration.
    meta_array : array-like, optional
        Not implemented.
    attributes : dict[str, JSON], optional
        A dictionary of user attributes to store with the array.
    chunk_shape : ChunksLike, optional
        The shape of the Array's chunks (default is None).
        Zarr format 3 only. Zarr format 2 arrays should use `chunks` instead.
    chunk_key_encoding : ChunkKeyEncoding, optional
        A specification of how the chunk keys are represented in storage.
        Zarr format 3 only. Zarr format 2 arrays should use `dimension_separator` instead.
        Default is `("default", "/")`.
    codecs : Sequence of Codecs or dicts, optional
        An iterable of Codec or dict serializations of Codecs. Zarr V3 only.

        The elements of `codecs` specify the transformation from array values to stored bytes.
        Zarr format 3 only. Zarr format 2 arrays should use `filters` and `compressor` instead.

        If no codecs are provided, default codecs will be used based on the data type of the array.
        For most data types, the default codecs are the tuple `(BytesCodec(), ZstdCodec())`;
        data types that require a special [`zarr.abc.codec.ArrayBytesCodec`][], like variable-length strings or bytes,
        will use the [`zarr.abc.codec.ArrayBytesCodec`][] required for the data type instead of [`zarr.codecs.BytesCodec`][].
    dimension_names : Iterable[str | None] | None = None
        An iterable of dimension names. Zarr format 3 only.
    storage_options : dict
        If using an fsspec URL to create the store, these will be passed to
        the backend implementation. Ignored otherwise.
    config : ArrayConfigLike, optional
        Runtime configuration of the array. If provided, will override the
        default values from `zarr.config.array`.
    mode : {'r', 'r+', 'a', 'w', 'w-'}, optional
        Legacy way to control overwriting, kept for compatibility with Zarr-Python 2.
        Prefer `overwrite`. The access mode used to open `store`; the default, `None`,
        is `'a'`.

        - `'a'` and `'r+'` create the array and fail if a node exists at `path`,
          unless `overwrite` is `True`.
        - `'w'` replaces anything stored under `path` (the whole store if `path` is
          not set), even if `overwrite` is `False`. On a store that cannot delete
          keys, `'w'` raises an error instead of replacing an existing node.
        - `'w-'` fails if anything is stored under `path`, even if `overwrite` is
          `True`.
        - `'r'` always fails.

        If `store` is a `StorePath`, `mode` is not validated against it: `'w'` still
        sets `overwrite`, and the other modes have no effect.
    data : array-like, optional
        Values written into the new array after it is created. Unlike the `data`
        parameter of `create_array`, it does not set the shape or data type of the
        array. To create an array from existing data, use `create_array(data=...)`.
        A Zarr array is not supported as `data`.

    Returns
    -------
    z : array
        The array.
    """
    if zarr_format is None:
        zarr_format = _default_zarr_format()

    _warn_unimplemented_kwargs(
        {
            "synchronizer": synchronizer,
            "chunk_store": chunk_store,
            "cache_metadata": cache_metadata,
            "cache_attrs": cache_attrs,
            "object_codec": object_codec,
            "read_only": read_only,
            "meta_array": meta_array,
        }
    )

    if write_empty_chunks is not None:
        _warn_write_empty_chunks_kwarg()

    if mode is None:
        mode = "a"
    overwrite = overwrite or _infer_overwrite(mode)
    store_path = await make_store_path(store, path=path, mode=mode, storage_options=storage_options)

    config_parsed = parse_array_config(config)

    if write_empty_chunks is not None:
        if config is not None:
            msg = (
                "Both write_empty_chunks and config keyword arguments are set. "
                "This is redundant. When both are set, write_empty_chunks will be used instead "
                "of the value in config."
            )
            warnings.warn(ZarrUserWarning(msg), stacklevel=1)
        config_parsed = dataclasses.replace(config_parsed, write_empty_chunks=write_empty_chunks)

    return await AsyncArray._create(
        store_path,
        shape=shape,
        chunks=chunks,
        # Legacy v2 behavior: an unspecified dtype defaults to float64.
        dtype="float64" if dtype is None else dtype,
        compressor=compressor,
        fill_value=fill_value,
        overwrite=overwrite,
        filters=filters,
        dimension_separator=dimension_separator,
        order=order,
        zarr_format=zarr_format,
        chunk_shape=chunk_shape,
        chunk_key_encoding=chunk_key_encoding,
        codecs=codecs,
        dimension_names=dimension_names,
        attributes=attributes,
        config=config_parsed,
        data=data,
    )

create_array `async` ¶

create_array(
    store: StoreLike,
    *,
    name: str | None = None,
    shape: ShapeLike | None = None,
    dtype: ZDTypeLike | None = None,
    data: ndarray[Any, dtype[Any]] | None = None,
    chunks: ChunksLike | Literal["auto"] = "auto",
    shards: ShardsLike | None = None,
    filters: FiltersLike = "auto",
    compressors: CompressorsLike = "auto",
    serializer: SerializerLike = "auto",
    fill_value: Any | None = DEFAULT_FILL_VALUE,
    order: MemoryOrder | None = None,
    zarr_format: ZarrFormat | None = 3,
    attributes: dict[str, JSON] | None = None,
    chunk_key_encoding: ChunkKeyEncodingLike | None = None,
    dimension_names: DimensionNamesLike = None,
    storage_options: dict[str, Any] | None = None,
    overwrite: bool = False,
    config: ArrayConfigLike | None = None,
    write_data: bool = True,
) -> AnyAsyncArray

Create an array.

Parameters:

store (StoreLike) –

StoreLike object to open. See the storage documentation in the user guide for a description of all valid StoreLike values.
name (str or None, default: None ) –

The name of the array within the store. If name is None, the array will be located at the root of the store.
shape (ShapeLike, default: None ) –

Shape of the array. Must be None if data is provided.
dtype (ZDTypeLike | None, default: None ) –

Data type of the array. Must be None if data is provided.
data (ndarray, default: None ) –

Array-like data to use for initializing the array. If this parameter is provided, the shape and dtype parameters must be None.
chunks (tuple[int, ...] | Sequence[Sequence[int]] | Literal['auto'], default: "auto" ) –

Chunk shape of the array. If chunks is "auto", a chunk shape is guessed based on the shape of the array and the dtype. A nested list of per-dimension edge sizes creates a rectilinear grid. Rectilinear chunk grids are experimental and must be explicitly enabled with zarr.config.set({'array.rectilinear_chunks': True}) while the feature is stabilizing.
shards (tuple[int, ...], default: None ) –

Shard shape of the array. The default value of None results in no sharding at all.
filters (Iterable[Codec] | Literal['auto'], default: 'auto' ) –

Iterable of filters to apply to each chunk of the array, in order, before serializing that chunk to bytes.

For Zarr format 3, a "filter" is a codec that takes an array and returns an array, and these values must be instances of zarr.abc.codec.ArrayArrayCodec, or a dict representations of zarr.abc.codec.ArrayArrayCodec.

For Zarr format 2, a "filter" can be any numcodecs codec; you should ensure that the order of your filters is consistent with the behavior of each filter.

The default value of "auto" instructs Zarr to use a default based on the data type of the array and the Zarr format specified. For all data types in Zarr V3, and most data types in Zarr V2, the default filters are empty. The only cases where default filters are not empty is when the Zarr format is 2, and the data type is a variable-length data type like zarr.dtype.VariableLengthUTF8 or zarr.dtype.VariableLengthBytes. In these cases, the default filters contains a single element which is a codec specific to that particular data type.

To create an array with no filters, provide an empty iterable or the value None.
compressors (Iterable[Codec], default: 'auto' ) –

List of compressors to apply to the array. Compressors are applied in order, and after any filters are applied (if any are specified) and the data is serialized into bytes.

For Zarr format 3, a "compressor" is a codec that takes a bytestream, and returns another bytestream. Multiple compressors may be provided for Zarr format 3. If no compressors are provided, a default set of compressors will be used. These defaults can be changed by modifying the value of array.v3_default_compressors in zarr.config. Use None to omit default compressors.

For Zarr format 2, a "compressor" can be any numcodecs codec. Only a single compressor may be provided for Zarr format 2. If no compressor is provided, a default compressor will be used. This default can be changed by modifying the value of array.v2_default_compressor in zarr.config. Use None to omit the default compressor.
serializer (dict[str, JSON] | ArrayBytesCodec, default: 'auto' ) –

Array-to-bytes codec to use for encoding the array data. Zarr format 3 only. Zarr format 2 arrays use implicit array-to-bytes conversion. If no serializer is provided, a default serializer will be used. These defaults can be changed by modifying the value of array.v3_default_serializer in zarr.config.
fill_value (Any, default: DEFAULT_FILL_VALUE ) –

Fill value for the array.
order (('C', 'F'), default: "C" ) –

The memory order of the array (default is "C"). For Zarr format 2, this parameter sets the memory order of the array. For Zarr format 3, this parameter is deprecated, because memory order is a runtime parameter for Zarr format 3 arrays. The recommended way to specify the memory order for Zarr format 3 arrays is via the config parameter, e.g. {'config': 'C'}. If no order is provided, a default order will be used. This default can be changed by modifying the value of array.order in zarr.config.
zarr_format ((2, 3), default: 2 ) –

The zarr format to use when saving.
attributes (dict, default: None ) –

Attributes for the array.
chunk_key_encoding (ChunkKeyEncodingLike, default: None ) –

A specification of how the chunk keys are represented in storage. For Zarr format 3, the default is {"name": "default", "separator": "/"}. For Zarr format 2, the default is {"name": "v2", "separator": "."}.
dimension_names (Iterable[str], default: None ) –

The names of the dimensions (default is None). Zarr format 3 only. Zarr format 2 arrays should not use this parameter.
storage_options (dict, default: None ) –

If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.
overwrite (bool, default: False ) –

Whether to overwrite an array with the same name in the store, if one exists. If True, any existing keys under that path are deleted first.
config (ArrayConfigLike, default: None ) –

Runtime configuration for the array.
write_data (bool, default: True ) –

If a pre-existing array-like object was provided to this function via the data parameter then write_data determines whether the values in that array-like object should be written to the Zarr array created by this function. If write_data is False, then the array will be left empty.

Returns:

AsyncArray –

The array.

Examples:

>>> import asyncio
>>> import zarr
>>> asyncio.run(
...     zarr.api.asynchronous.create_array(
...         store={},
...         shape=(100,100),
...         chunks=(10,10),
...         dtype="i4",
...         fill_value=0
...     )
... )
<AsyncArray memory://... shape=(100, 100) dtype=int32>

Source code in src/zarr/core/array.py

async def create_array(
    store: StoreLike,
    *,
    name: str | None = None,
    shape: ShapeLike | None = None,
    dtype: ZDTypeLike | None = None,
    data: np.ndarray[Any, np.dtype[Any]] | None = None,
    chunks: ChunksLike | Literal["auto"] = "auto",
    shards: ShardsLike | None = None,
    filters: FiltersLike = "auto",
    compressors: CompressorsLike = "auto",
    serializer: SerializerLike = "auto",
    fill_value: Any | None = DEFAULT_FILL_VALUE,
    order: MemoryOrder | None = None,
    zarr_format: ZarrFormat | None = 3,
    attributes: dict[str, JSON] | None = None,
    chunk_key_encoding: ChunkKeyEncodingLike | None = None,
    dimension_names: DimensionNamesLike = None,
    storage_options: dict[str, Any] | None = None,
    overwrite: bool = False,
    config: ArrayConfigLike | None = None,
    write_data: bool = True,
) -> AnyAsyncArray:
    """Create an array.

    Parameters
    ----------
    store : StoreLike
        StoreLike object to open. See the
        [storage documentation in the user guide][user-guide-store-like]
        for a description of all valid StoreLike values.
    name : str or None, optional
        The name of the array within the store. If `name` is `None`, the array will be located
        at the root of the store.
    shape : ShapeLike, optional
        Shape of the array. Must be `None` if `data` is provided.
    dtype : ZDTypeLike | None
        Data type of the array. Must be `None` if `data` is provided.
    data : np.ndarray, optional
        Array-like data to use for initializing the array. If this parameter is provided, the
        `shape` and `dtype` parameters must be `None`.
    chunks : tuple[int, ...] | Sequence[Sequence[int]] | Literal["auto"], default="auto"
        Chunk shape of the array.
        If chunks is "auto", a chunk shape is guessed based on the shape of the array and the dtype.
        A nested list of per-dimension edge sizes creates a rectilinear grid.
        Rectilinear chunk grids are experimental and must be explicitly enabled
        with `zarr.config.set({'array.rectilinear_chunks': True})` while the
        feature is stabilizing.
    shards : tuple[int, ...], optional
        Shard shape of the array. The default value of `None` results in no sharding at all.
    filters : Iterable[Codec] | Literal["auto"], optional
        Iterable of filters to apply to each chunk of the array, in order, before serializing that
        chunk to bytes.

        For Zarr format 3, a "filter" is a codec that takes an array and returns an array,
        and these values must be instances of [`zarr.abc.codec.ArrayArrayCodec`][], or a
        dict representations of [`zarr.abc.codec.ArrayArrayCodec`][].

        For Zarr format 2, a "filter" can be any numcodecs codec; you should ensure that the
        order of your filters is consistent with the behavior of each filter.

        The default value of `"auto"` instructs Zarr to use a default based on the data
        type of the array and the Zarr format specified. For all data types in Zarr V3, and most
        data types in Zarr V2, the default filters are empty. The only cases where default filters
        are not empty is when the Zarr format is 2, and the data type is a variable-length data type like
        [`zarr.dtype.VariableLengthUTF8`][] or [`zarr.dtype.VariableLengthBytes`][]. In these cases,
        the default filters contains a single element which is a codec specific to that particular data type.

        To create an array with no filters, provide an empty iterable or the value `None`.
    compressors : Iterable[Codec], optional
        List of compressors to apply to the array. Compressors are applied in order, and after any
        filters are applied (if any are specified) and the data is serialized into bytes.

        For Zarr format 3, a "compressor" is a codec that takes a bytestream, and
        returns another bytestream. Multiple compressors may be provided for Zarr format 3.
        If no `compressors` are provided, a default set of compressors will be used.
        These defaults can be changed by modifying the value of `array.v3_default_compressors`
        in [`zarr.config`][zarr.config].
        Use `None` to omit default compressors.

        For Zarr format 2, a "compressor" can be any numcodecs codec. Only a single compressor may
        be provided for Zarr format 2.
        If no `compressor` is provided, a default compressor will be used.
        This default can be changed by modifying the value of `array.v2_default_compressor`
        in [`zarr.config`][zarr.config].
        Use `None` to omit the default compressor.
    serializer : dict[str, JSON] | ArrayBytesCodec, optional
        Array-to-bytes codec to use for encoding the array data.
        Zarr format 3 only. Zarr format 2 arrays use implicit array-to-bytes conversion.
        If no `serializer` is provided, a default serializer will be used.
        These defaults can be changed by modifying the value of `array.v3_default_serializer`
        in [`zarr.config`][zarr.config].
    fill_value : Any, optional
        Fill value for the array.
    order : {"C", "F"}, optional
        The memory order of the array (default is "C").
        For Zarr format 2, this parameter sets the memory order of the array.
        For Zarr format 3, this parameter is deprecated, because memory order
        is a runtime parameter for Zarr format 3 arrays. The recommended way to specify the memory
        order for Zarr format 3 arrays is via the `config` parameter, e.g. `{'config': 'C'}`.
        If no `order` is provided, a default order will be used.
        This default can be changed by modifying the value of `array.order` in [`zarr.config`][zarr.config].
    zarr_format : {2, 3}, optional
        The zarr format to use when saving.
    attributes : dict, optional
        Attributes for the array.
    chunk_key_encoding : ChunkKeyEncodingLike, optional
        A specification of how the chunk keys are represented in storage.
        For Zarr format 3, the default is `{"name": "default", "separator": "/"}`.
        For Zarr format 2, the default is `{"name": "v2", "separator": "."}`.
    dimension_names : Iterable[str], optional
        The names of the dimensions (default is None).
        Zarr format 3 only. Zarr format 2 arrays should not use this parameter.
    storage_options : dict, optional
        If using an fsspec URL to create the store, these will be passed to the backend implementation.
        Ignored otherwise.
    overwrite : bool, default False
        Whether to overwrite an array with the same name in the store, if one exists.
        If `True`, any existing keys under that path are deleted first.
    config : ArrayConfigLike, optional
        Runtime configuration for the array.
    write_data : bool
        If a pre-existing array-like object was provided to this function via the `data` parameter
        then `write_data` determines whether the values in that array-like object should be
        written to the Zarr array created by this function. If `write_data` is `False`, then the
        array will be left empty.

    Returns
    -------
    AsyncArray
        The array.

    Examples
    --------
    >>> import asyncio
    >>> import zarr
    >>> asyncio.run(
    ...     zarr.api.asynchronous.create_array(
    ...         store={},
    ...         shape=(100,100),
    ...         chunks=(10,10),
    ...         dtype="i4",
    ...         fill_value=0
    ...     )
    ... )
    <AsyncArray memory://... shape=(100, 100) dtype=int32>
    """
    data_parsed, shape_parsed, dtype_parsed = _parse_data_params(
        data=data, shape=shape, dtype=dtype
    )
    if data_parsed is not None:
        return await from_array(
            store,
            data=data_parsed,
            write_data=write_data,
            name=name,
            chunks=chunks,
            shards=shards,
            filters=filters,
            compressors=compressors,
            serializer=serializer,
            fill_value=fill_value,
            order=order,
            zarr_format=zarr_format,
            attributes=attributes,
            chunk_key_encoding=chunk_key_encoding,
            dimension_names=dimension_names,
            storage_options=storage_options,
            overwrite=overwrite,
            config=config,
        )
    else:
        mode: Literal["a"] = "a"

        store_path = await make_store_path(
            store, path=name, mode=mode, storage_options=storage_options
        )
        return await init_array(
            store_path=store_path,
            shape=shape_parsed,
            dtype=dtype_parsed,
            chunks=chunks,
            shards=shards,
            filters=filters,
            compressors=compressors,
            serializer=serializer,
            fill_value=fill_value,
            order=order,
            zarr_format=zarr_format,
            attributes=attributes,
            chunk_key_encoding=chunk_key_encoding,
            dimension_names=dimension_names,
            overwrite=overwrite,
            config=config,
        )

create_group `async` ¶

create_group(
    *,
    store: StoreLike,
    path: str | None = None,
    overwrite: bool = False,
    zarr_format: ZarrFormat | None = None,
    attributes: dict[str, Any] | None = None,
    storage_options: dict[str, Any] | None = None,
) -> AsyncGroup

Create a group.

Parameters:

store (StoreLike) –

StoreLike object to open. See the storage documentation in the user guide for a description of all valid StoreLike values.
path (str, default: None ) –

Group path within store.
overwrite (bool, default: False ) –

If True, pre-existing data at path will be deleted before creating the group.
zarr_format ((2, 3, None), default: 2 ) –

The zarr format to use when saving. If no zarr_format is provided, the default format will be used. This default can be changed by modifying the value of default_zarr_format in zarr.config.
storage_options (dict, default: None ) –

If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.

Returns:

AsyncGroup –

The new group.

Source code in src/zarr/api/asynchronous.py

async def create_group(
    *,
    store: StoreLike,
    path: str | None = None,
    overwrite: bool = False,
    zarr_format: ZarrFormat | None = None,
    attributes: dict[str, Any] | None = None,
    storage_options: dict[str, Any] | None = None,
) -> AsyncGroup:
    """Create a group.

    Parameters
    ----------
    store : StoreLike
        StoreLike object to open. See the
        [storage documentation in the user guide][user-guide-store-like]
        for a description of all valid StoreLike values.
    path : str, optional
        Group path within store.
    overwrite : bool, optional
        If True, pre-existing data at `path` will be deleted before
        creating the group.
    zarr_format : {2, 3, None}, optional
        The zarr format to use when saving.
        If no `zarr_format` is provided, the default format will be used.
        This default can be changed by modifying the value of `default_zarr_format`
        in [`zarr.config`][zarr.config].
    storage_options : dict
        If using an fsspec URL to create the store, these will be passed to
        the backend implementation. Ignored otherwise.

    Returns
    -------
    AsyncGroup
        The new group.
    """

    if zarr_format is None:
        zarr_format = _default_zarr_format()

    mode: Literal["a"] = "a"

    store_path = await make_store_path(store, path=path, mode=mode, storage_options=storage_options)

    return await AsyncGroup.from_store(
        store=store_path,
        zarr_format=zarr_format,
        overwrite=overwrite,
        attributes=attributes,
    )

create_hierarchy `async` ¶

create_hierarchy(
    *,
    store: Store,
    nodes: dict[
        str,
        GroupMetadata | ArrayV2Metadata | ArrayV3Metadata,
    ],
    overwrite: bool = False,
) -> AsyncIterator[tuple[str, AsyncGroup | AnyAsyncArray]]

Create a complete zarr hierarchy from a collection of metadata objects.

This function will parse its input to ensure that the hierarchy is complete. Any implicit groups will be inserted as needed. For example, an input like {'a/b': GroupMetadata} will be parsed to {'': GroupMetadata, 'a': GroupMetadata, 'b': Groupmetadata}

After input parsing, this function then creates all the nodes in the hierarchy concurrently.

Arrays and Groups are yielded in the order they are created. This order is not stable and should not be relied on.

Parameters

store : Store The storage backend to use. nodes : dict[str, GroupMetadata | ArrayV3Metadata | ArrayV2Metadata] A dictionary defining the hierarchy. The keys are the paths of the nodes in the hierarchy, relative to the root of the Store. The root of the store can be specified with the empty string ''. The values are instances of GroupMetadata or ArrayMetadata. Note that all values must have the same zarr_format -- it is an error to mix zarr versions in the same hierarchy.

Leading "/" characters from keys will be removed.

overwrite : bool Whether to overwrite existing nodes. Defaults to False, in which case an error is raised instead of overwriting an existing array or group.

This function will not erase an existing group unless that group is explicitly named in
``nodes``. If ``nodes`` defines implicit groups, e.g. ``{`'a/b/c': GroupMetadata}``, and a
group already exists at path ``a``, then this function will leave the group at ``a`` as-is.

Yields:

tuple[str, AsyncGroup | AsyncArray] –

Yields (path, node) pairs, in the order the nodes were created.

Examples:

>>> async def example():
...     from zarr.api.asynchronous import create_hierarchy
...     from zarr.core.group import GroupMetadata
...     from zarr.storage import MemoryStore
...
...     store = MemoryStore()
...     nodes = {'a': GroupMetadata(attributes={'name': 'leaf'})}
...     return sorted([x async for x in create_hierarchy(store=store, nodes=nodes)])

>>> import asyncio
>>> asyncio.run(example())
[('', <AsyncGroup memory://...>), ('a', <AsyncGroup memory://.../a>)]

Source code in src/zarr/core/group.py

async def create_hierarchy(
    *,
    store: Store,
    nodes: dict[str, GroupMetadata | ArrayV2Metadata | ArrayV3Metadata],
    overwrite: bool = False,
) -> AsyncIterator[tuple[str, AsyncGroup | AnyAsyncArray]]:
    """
    Create a complete zarr hierarchy from a collection of metadata objects.

    This function will parse its input to ensure that the hierarchy is complete. Any implicit groups
    will be inserted as needed. For example, an input like
    ```{'a/b': GroupMetadata}``` will be parsed to
    ```{'': GroupMetadata, 'a': GroupMetadata, 'b': Groupmetadata}```

    After input parsing, this function then creates all the nodes in the hierarchy concurrently.

    Arrays and Groups are yielded in the order they are created. This order is not stable and
    should not be relied on.

        Parameters
    ----------
    store : Store
        The storage backend to use.
    nodes : dict[str, GroupMetadata | ArrayV3Metadata | ArrayV2Metadata]
        A dictionary defining the hierarchy. The keys are the paths of the nodes in the hierarchy,
        relative to the root of the ``Store``. The root of the store can be specified with the empty
        string ``''``. The values are instances of ``GroupMetadata`` or ``ArrayMetadata``. Note that
        all values must have the same ``zarr_format`` -- it is an error to mix zarr versions in the
        same hierarchy.

        Leading "/" characters from keys will be removed.
    overwrite : bool
        Whether to overwrite existing nodes. Defaults to ``False``, in which case an error is
        raised instead of overwriting an existing array or group.

        This function will not erase an existing group unless that group is explicitly named in
        ``nodes``. If ``nodes`` defines implicit groups, e.g. ``{`'a/b/c': GroupMetadata}``, and a
        group already exists at path ``a``, then this function will leave the group at ``a`` as-is.

    Yields
    ------
    tuple[str, AsyncGroup | AsyncArray]
        Yields (path, node) pairs, in the order the nodes were created.

    Examples
    --------
    >>> async def example():
    ...     from zarr.api.asynchronous import create_hierarchy
    ...     from zarr.core.group import GroupMetadata
    ...     from zarr.storage import MemoryStore
    ...
    ...     store = MemoryStore()
    ...     nodes = {'a': GroupMetadata(attributes={'name': 'leaf'})}
    ...     return sorted([x async for x in create_hierarchy(store=store, nodes=nodes)])

    >>> import asyncio
    >>> asyncio.run(example())
    [('', <AsyncGroup memory://...>), ('a', <AsyncGroup memory://.../a>)]
    """

    # normalize the keys to be valid paths
    nodes_normed_keys = _normalize_path_keys(nodes)

    # ensure that all nodes have the same zarr_format, and add implicit groups as needed
    nodes_parsed = _parse_hierarchy_dict(data=nodes_normed_keys)
    redundant_implicit_groups = []
    to_delete_keys: list[str] = []

    # empty hierarchies should be a no-op
    if len(nodes_parsed) > 0:
        # figure out which zarr format we are using
        zarr_format = next(iter(nodes_parsed.values())).zarr_format

        # check which implicit groups will require materialization
        implicit_group_keys = tuple(
            filter(lambda k: isinstance(nodes_parsed[k], ImplicitGroupMarker), nodes_parsed)
        )
        # read potential group metadata for each implicit group
        maybe_extant_group_coros = (
            _read_group_metadata(store, k, zarr_format=zarr_format) for k in implicit_group_keys
        )
        maybe_extant_groups = await asyncio.gather(
            *maybe_extant_group_coros, return_exceptions=True
        )

        for key, value in zip(implicit_group_keys, maybe_extant_groups, strict=True):
            if isinstance(value, BaseException):
                if isinstance(value, FileNotFoundError):
                    # this is fine -- there was no group there, so we will create one
                    pass
                else:
                    raise value
            else:
                # a loop exists already at ``key``, so we can avoid creating anything there
                redundant_implicit_groups.append(key)

        if overwrite:
            # we will remove any nodes that collide with arrays and non-implicit groups defined in
            # nodes
            to_delete_keys = [k for k in nodes_parsed if k not in implicit_group_keys]
        else:
            # This type is long.
            coros: (
                Generator[Coroutine[Any, Any, ArrayV2Metadata | GroupMetadata], None, None]
                | Generator[Coroutine[Any, Any, ArrayV3Metadata | GroupMetadata], None, None]
            )
            if zarr_format == 2:
                coros = (_read_metadata_v2(store=store, path=key) for key in nodes_parsed)
            elif zarr_format == 3:
                coros = (_read_metadata_v3(store=store, path=key) for key in nodes_parsed)
            else:  # pragma: no cover
                raise ValueError(f"Invalid zarr_format: {zarr_format}")  # pragma: no cover

            extant_node_query = dict(
                zip(
                    nodes_parsed.keys(),
                    await asyncio.gather(*coros, return_exceptions=True),
                    strict=False,
                )
            )
            # iterate over the existing arrays / groups and figure out which of them conflict
            # with the arrays / groups we want to create
            for key, extant_node in extant_node_query.items():
                proposed_node = nodes_parsed[key]
                if isinstance(extant_node, BaseException):
                    if isinstance(extant_node, FileNotFoundError):
                        # ignore FileNotFoundError, because they represent nodes we can safely create
                        pass
                    else:
                        # Any other exception is a real error
                        raise extant_node
                else:
                    # this is a node that already exists, but a node with the same key was specified
                    #  in nodes_parsed.
                    if isinstance(extant_node, GroupMetadata):
                        # a group already exists where we want to create a group
                        if isinstance(proposed_node, ImplicitGroupMarker):
                            # we have proposed an implicit group, which is OK -- we will just skip
                            # creating this particular metadata document
                            redundant_implicit_groups.append(key)
                        else:
                            # we have proposed an explicit group, which is an error, given that a
                            # group already exists.
                            msg = f"A group exists in store {store!r} at path {key!r}."
                            raise ContainsGroupError(msg)
                    elif isinstance(extant_node, ArrayV2Metadata | ArrayV3Metadata):
                        # we are trying to overwrite an existing array. this is an error.
                        msg = f"An array exists in store {store!r} at path {key!r}."
                        raise ContainsArrayError(msg)

    nodes_explicit: dict[str, GroupMetadata | ArrayV2Metadata | ArrayV3Metadata] = {}

    for k, v in nodes_parsed.items():
        if k not in redundant_implicit_groups:
            if isinstance(v, ImplicitGroupMarker):
                nodes_explicit[k] = GroupMetadata(zarr_format=v.zarr_format)
            else:
                nodes_explicit[k] = v

    # Build and encode every node before deleting anything: a node that cannot be built
    # or whose metadata cannot be stored then fails with the store untouched.
    built, documents = _prepare_nodes(store, nodes_explicit)
    await asyncio.gather(*(store.delete_dir(key) for key in to_delete_keys))
    async for key, node in _store_nodes(store, nodes_explicit, built, documents):
        yield key, node

empty `async` ¶

empty(
    shape: tuple[int, ...], **kwargs: Any
) -> AnyAsyncArray

Create an empty array with the specified shape. The contents will be filled with the specified fill value or zeros if no fill value is provided.

Parameters:

shape (int or tuple of int) –

Shape of the empty array.
**kwargs (Any, default: {} ) –

Keyword arguments passed to create.

Notes

The contents of an empty Zarr array are not defined. On attempting to retrieve data from an empty Zarr array, any values may be returned, and these are not guaranteed to be stable from one access to the next.

Source code in src/zarr/api/asynchronous.py

async def empty(shape: tuple[int, ...], **kwargs: Any) -> AnyAsyncArray:
    """Create an empty array with the specified shape. The contents will be filled with the
    specified fill value or zeros if no fill value is provided.

    Parameters
    ----------
    shape : int or tuple of int
        Shape of the empty array.
    **kwargs
        Keyword arguments passed to [`create`][zarr.api.asynchronous.create].

    Notes
    -----
    The contents of an empty Zarr array are not defined. On attempting to
    retrieve data from an empty Zarr array, any values may be returned,
    and these are not guaranteed to be stable from one access to the next.
    """
    return await create(shape=shape, **kwargs)

empty_like `async` ¶

empty_like(
    a: ArrayLike,
    *,
    zarr_format: ZarrFormat | None = None,
    **kwargs: Any,
) -> AnyAsyncArray

Create an empty array like a. The contents will be filled with the array's fill value or zeros if no fill value is provided.

Parameters:

a (array - like) –

The array to create an empty array like.
zarr_format ((2, 3, None), default: 2 ) –

The zarr format of the new array. If None (default), the zarr format of a if it is a zarr array, otherwise the default zarr format.
**kwargs (Any, default: {} ) –

Keyword arguments passed to create.

Returns:

Array –

The new array.

Notes

The contents of an empty Zarr array are not defined. On attempting to retrieve data from an empty Zarr array, any values may be returned, and these are not guaranteed to be stable from one access to the next.

Source code in src/zarr/api/asynchronous.py

async def empty_like(
    a: ArrayLike, *, zarr_format: ZarrFormat | None = None, **kwargs: Any
) -> AnyAsyncArray:
    """Create an empty array like `a`. The contents will be filled with the
    array's fill value or zeros if no fill value is provided.

    Parameters
    ----------
    a : array-like
        The array to create an empty array like.
    zarr_format : {2, 3, None}, optional
        The zarr format of the new array. If `None` (default), the zarr format of `a` if it
        is a zarr array, otherwise the default zarr format.
    **kwargs
        Keyword arguments passed to [`create`][zarr.api.asynchronous.create].

    Returns
    -------
    Array
        The new array.

    Notes
    -----
    The contents of an empty Zarr array are not defined. On attempting to
    retrieve data from an empty Zarr array, any values may be returned,
    and these are not guaranteed to be stable from one access to the next.
    """
    like_kwargs = _like_args(a, zarr_format) | kwargs
    return await empty(**like_kwargs)  # type: ignore[arg-type]

from_array `async` ¶

from_array(
    store: StoreLike,
    *,
    data: AnyArray | ArrayLike,
    write_data: bool = True,
    name: str | None = None,
    chunks: ChunksLike | Literal["auto", "keep"] = "keep",
    shards: ShardsLike | Literal["keep"] | None = "keep",
    filters: FiltersLike | Literal["keep"] = "keep",
    compressors: CompressorsLike | Literal["keep"] = "keep",
    serializer: SerializerLike | Literal["keep"] = "keep",
    fill_value: Any | None = DEFAULT_FILL_VALUE,
    order: MemoryOrder | None = None,
    zarr_format: ZarrFormat | None = None,
    attributes: dict[str, JSON] | None = None,
    chunk_key_encoding: ChunkKeyEncodingLike | None = None,
    dimension_names: DimensionNamesLike = None,
    storage_options: dict[str, Any] | None = None,
    overwrite: bool = False,
    config: ArrayConfigLike | None = None,
) -> AnyAsyncArray

Create an array from an existing array or array-like.

Parameters:

store (StoreLike) –

StoreLike object to open. See the storage documentation in the user guide for a description of all valid StoreLike values.
data (Array | array - like) –

The array to copy.
write_data (bool, default: True ) –

Whether to copy the data from the input array to the new array. If write_data is False, the new array will be created with the same metadata as the input array, but without any data.
name (str or None, default: None ) –

The name of the array within the store. If name is None, the array will be located at the root of the store.
chunks (tuple[int, ...] or Sequence[Sequence[int]] or 'auto' or 'keep', default: 'keep' ) –
Chunk shape of the array. Following values are supported:
- "auto": Automatically determine the chunk shape based on the array's shape and dtype.
- "keep": Retain the chunk grid of the data array if it is a zarr Array.
- tuple[int, ...]: A tuple of integers representing the chunk shape (regular grid).
- Sequence[Sequence[int]]: Per-dimension chunk edge lists (rectilinear grid). Rectilinear chunk grids are experimental and must be explicitly enabled with zarr.config.set({'array.rectilinear_chunks': True}) while the feature is stabilizing.
If not specified, defaults to "keep" if data is a zarr Array, otherwise "auto".
shards (tuple[int, ...], default: 'keep' ) –
Shard shape of the array. Following values are supported:
- "auto": Automatically determine the shard shape based on the array's shape and chunk shape.
- "keep": Retain the shard shape of the data array if it is a zarr Array.
- tuple[int, ...]: A tuple of integers representing the shard shape.
- None: No sharding.
If not specified, defaults to "keep" if data is a zarr Array, otherwise None.
filters (Iterable[Codec] | Literal['auto', 'keep'], default: 'keep' ) –

Iterable of filters to apply to each chunk of the array, in order, before serializing that chunk to bytes.

For Zarr format 3, a "filter" is a codec that takes an array and returns an array, and these values must be instances of zarr.abc.codec.ArrayArrayCodec, or a dict representations of zarr.abc.codec.ArrayArrayCodec.

For Zarr format 2, a "filter" can be any numcodecs codec; you should ensure that the order of your filters is consistent with the behavior of each filter.

The default value of "keep" instructs Zarr to infer filters from data. If that inference is not possible, Zarr will fall back to the behavior specified by "auto", which is to choose default filters based on the data type of the array and the Zarr format specified. For all data types in Zarr V3, and most data types in Zarr V2, the default filters are the empty tuple (). The only cases where default filters are not empty is when the Zarr format is 2, and the data type is a variable-length data type like zarr.dtype.VariableLengthUTF8 or zarr.dtype.VariableLengthUTF8. In these cases, the default filters is a tuple with a single element which is a codec specific to that particular data type.

To create an array with no filters, provide an empty iterable or the value None.
compressors (Iterable[Codec] or 'auto' or 'keep', default: 'keep' ) –
List of compressors to apply to the array. Compressors are applied in order, and after any filters are applied (if any are specified) and the data is serialized into bytes.

For Zarr format 3, a "compressor" is a codec that takes a bytestream, and returns another bytestream. Multiple compressors may be provided for Zarr format 3.

For Zarr format 2, a "compressor" can be any numcodecs codec. Only a single compressor may be provided for Zarr format 2.

Following values are supported:
- Iterable[Codec]: List of compressors to apply to the array.
- "auto": Automatically determine the compressors based on the array's dtype.
- "keep": Retain the compressors of the input array if it is a zarr Array.
If no compressors are provided, defaults to "keep" if data is a zarr Array, otherwise "auto".
serializer (dict[str, JSON] | ArrayBytesCodec or 'auto' or 'keep', default: 'keep' ) –
Array-to-bytes codec to use for encoding the array data. Zarr format 3 only. Zarr format 2 arrays use implicit array-to-bytes conversion.

Following values are supported:
- dict[str, JSON]: A dict representation of an ArrayBytesCodec.
- ArrayBytesCodec: An instance of ArrayBytesCodec.
- "auto": a default serializer will be used. These defaults can be changed by modifying the value of array.v3_default_serializer in zarr.config.
- "keep": Retain the serializer of the input array if it is a zarr Array.
fill_value (Any, default: DEFAULT_FILL_VALUE ) –

Fill value for the array. If not specified, defaults to the fill value of the data array. Pass None explicitly to use the default scalar of the data type (Zarr format 3) or a null fill value (Zarr format 2) instead.
order (('C', 'F'), default: "C" ) –

The memory order of the array (default is "C"). For Zarr format 2, this parameter sets the memory order of the array. For Zarr format 3, this parameter is deprecated, because memory order is a runtime parameter for Zarr format 3 arrays. The recommended way to specify the memory order for Zarr format 3 arrays is via the config parameter, e.g. {'config': 'C'}. If not specified, defaults to the memory order of the data array.
zarr_format ((2, 3), default: 2 ) –

The zarr format to use when saving. If not specified, defaults to the zarr format of the data array.
attributes (dict, default: None ) –

Attributes for the array. If not specified, the source Zarr array's attributes are deep-copied so nested containers are independent. Deeply nested attributes can raise RecursionError during copying even if they can be stored and reopened; the threshold depends on Python's recursion limit and the current call stack. Pass an empty dict to create the array with no attributes.
chunk_key_encoding (ChunkKeyEncoding, default: None ) –

A specification of how the chunk keys are represented in storage. For Zarr format 3, the default is {"name": "default", "separator": "/"}. For Zarr format 2, the default is {"name": "v2", "separator": "."}. If not specified and the data array has the same zarr format as the target array, the chunk key encoding of the data array is used.
dimension_names (Iterable[str | None] | None, default: None ) –

The names of the dimensions (default is None). Zarr format 3 only. Zarr format 2 arrays should not use this parameter. If not specified, defaults to the dimension names of the data array.
storage_options (dict, default: None ) –

If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.
overwrite (bool, default: False ) –

Whether to overwrite an array with the same name in the store, if one exists.
config (ArrayConfig or ArrayConfigLike, default: None ) –

Runtime configuration for the array.

Returns:

AsyncArray –

The array.

Examples:

Create an array from an existing Array:

>>> import asyncio
>>> import zarr
>>> store = zarr.storage.LocalStore("example.zarr")
>>> arr = zarr.create_array(
...     store={},
...     shape=(100,100),
...     chunks=(10,10),
...     dtype="int32",
...     fill_value=0,
... )

>>> arr2 = asyncio.run(from_array(store, data=arr, overwrite=True))
>>> arr2
<AsyncArray file://example.zarr shape=(100, 100) dtype=int32>
>>> asyncio.run(store.clear())  # Remove files generated by test

Create an array from an existing NumPy array:

>>> arr3 = asyncio.run(
...     from_array({}, data=np.arange(10000, dtype="i4").reshape(100, 100))
... )
>>> arr3
<AsyncArray memory://... shape=(100, 100) dtype=int32>

Create an array from any array-like object:

>>> arr4 = asyncio.run(from_array({}, data=[[1, 2], [3, 4]]))
>>> arr4
<AsyncArray memory://... shape=(2, 2) dtype=int64>
>>> asyncio.run(arr4.getitem(...))
array([[1, 2],
       [3, 4]])

Create an array from an existing Array without copying the data:

>>> arr5 = asyncio.run(from_array({}, data=Array(arr4), write_data=False))
>>> arr5
<AsyncArray memory://... shape=(2, 2) dtype=int64>
>>> asyncio.run(arr5.getitem(...))
array([[0, 0],
       [0, 0]])

Source code in src/zarr/core/array.py

async def from_array(
    store: StoreLike,
    *,
    data: AnyArray | npt.ArrayLike,
    write_data: bool = True,
    name: str | None = None,
    chunks: ChunksLike | Literal["auto", "keep"] = "keep",
    shards: ShardsLike | Literal["keep"] | None = "keep",
    filters: FiltersLike | Literal["keep"] = "keep",
    compressors: CompressorsLike | Literal["keep"] = "keep",
    serializer: SerializerLike | Literal["keep"] = "keep",
    fill_value: Any | None = DEFAULT_FILL_VALUE,
    order: MemoryOrder | None = None,
    zarr_format: ZarrFormat | None = None,
    attributes: dict[str, JSON] | None = None,
    chunk_key_encoding: ChunkKeyEncodingLike | None = None,
    dimension_names: DimensionNamesLike = None,
    storage_options: dict[str, Any] | None = None,
    overwrite: bool = False,
    config: ArrayConfigLike | None = None,
) -> AnyAsyncArray:
    """Create an array from an existing array or array-like.

    Parameters
    ----------
    store : StoreLike
        StoreLike object to open. See the
        [storage documentation in the user guide][user-guide-store-like]
        for a description of all valid StoreLike values.
    data : Array | array-like
        The array to copy.
    write_data : bool, default True
        Whether to copy the data from the input array to the new array.
        If `write_data` is `False`, the new array will be created with the same metadata as the
        input array, but without any data.
    name : str or None, optional
        The name of the array within the store. If `name` is `None`, the array will be located
        at the root of the store.
    chunks : tuple[int, ...] or Sequence[Sequence[int]] or "auto" or "keep", optional
        Chunk shape of the array.
        Following values are supported:

        - "auto": Automatically determine the chunk shape based on the array's shape and dtype.
        - "keep": Retain the chunk grid of the data array if it is a zarr Array.
        - tuple[int, ...]: A tuple of integers representing the chunk shape (regular grid).
        - Sequence[Sequence[int]]: Per-dimension chunk edge lists (rectilinear grid).
          Rectilinear chunk grids are experimental and must be explicitly enabled
          with `zarr.config.set({'array.rectilinear_chunks': True})` while the
          feature is stabilizing.

        If not specified, defaults to "keep" if data is a zarr Array, otherwise "auto".
    shards : tuple[int, ...], optional
        Shard shape of the array.
        Following values are supported:

        - "auto": Automatically determine the shard shape based on the array's shape and chunk shape.
        - "keep": Retain the shard shape of the data array if it is a zarr Array.
        - tuple[int, ...]: A tuple of integers representing the shard shape.
        - None: No sharding.

        If not specified, defaults to "keep" if data is a zarr Array, otherwise None.
    filters : Iterable[Codec] | Literal["auto", "keep"], optional
        Iterable of filters to apply to each chunk of the array, in order, before serializing that
        chunk to bytes.

        For Zarr format 3, a "filter" is a codec that takes an array and returns an array,
        and these values must be instances of [`zarr.abc.codec.ArrayArrayCodec`][], or a
        dict representations of [`zarr.abc.codec.ArrayArrayCodec`][].

        For Zarr format 2, a "filter" can be any numcodecs codec; you should ensure that the
        order of your filters is consistent with the behavior of each filter.

        The default value of `"keep"` instructs Zarr to infer `filters` from `data`.
        If that inference is not possible, Zarr will fall back to the behavior specified by `"auto"`,
        which is to choose default filters based on the data type of the array and the Zarr format specified.
        For all data types in Zarr V3, and most data types in Zarr V2, the default filters are the empty tuple `()`.
        The only cases where default filters are not empty is when the Zarr format is 2, and the
        data type is a variable-length data type like [`zarr.dtype.VariableLengthUTF8`][] or
        [`zarr.dtype.VariableLengthUTF8`][]. In these cases, the default filters is a tuple with a
        single element which is a codec specific to that particular data type.

        To create an array with no filters, provide an empty iterable or the value `None`.
    compressors : Iterable[Codec] or "auto" or "keep", optional
        List of compressors to apply to the array. Compressors are applied in order, and after any
        filters are applied (if any are specified) and the data is serialized into bytes.

        For Zarr format 3, a "compressor" is a codec that takes a bytestream, and
        returns another bytestream. Multiple compressors may be provided for Zarr format 3.

        For Zarr format 2, a "compressor" can be any numcodecs codec. Only a single compressor may
        be provided for Zarr format 2.

        Following values are supported:

        - Iterable[Codec]: List of compressors to apply to the array.
        - "auto": Automatically determine the compressors based on the array's dtype.
        - "keep": Retain the compressors of the input array if it is a zarr Array.

        If no `compressors` are provided, defaults to "keep" if data is a zarr Array, otherwise "auto".
    serializer : dict[str, JSON] | ArrayBytesCodec or "auto" or "keep", optional
        Array-to-bytes codec to use for encoding the array data.
        Zarr format 3 only. Zarr format 2 arrays use implicit array-to-bytes conversion.

        Following values are supported:

        - dict[str, JSON]: A dict representation of an `ArrayBytesCodec`.
        - ArrayBytesCodec: An instance of `ArrayBytesCodec`.
        - "auto": a default serializer will be used. These defaults can be changed by modifying the value of
          `array.v3_default_serializer` in [`zarr.config`][zarr.config].
        - "keep": Retain the serializer of the input array if it is a zarr Array.

    fill_value : Any, optional
        Fill value for the array.
        If not specified, defaults to the fill value of the data array.
        Pass `None` explicitly to use the default scalar of the data type
        (Zarr format 3) or a null fill value (Zarr format 2) instead.
    order : {"C", "F"}, optional
        The memory order of the array (default is "C").
        For Zarr format 2, this parameter sets the memory order of the array.
        For Zarr format 3, this parameter is deprecated, because memory order
        is a runtime parameter for Zarr format 3 arrays. The recommended way to specify the memory
        order for Zarr format 3 arrays is via the `config` parameter, e.g. `{'config': 'C'}`.
        If not specified, defaults to the memory order of the data array.
    zarr_format : {2, 3}, optional
        The zarr format to use when saving.
        If not specified, defaults to the zarr format of the data array.
    attributes : dict, optional
        Attributes for the array.
        If not specified, the source Zarr array's attributes are deep-copied so
        nested containers are independent. Deeply nested attributes can raise
        `RecursionError` during copying even if they can be stored and reopened;
        the threshold depends on Python's recursion limit and the current call stack.
        Pass an empty dict to create the array with no attributes.
    chunk_key_encoding : ChunkKeyEncoding, optional
        A specification of how the chunk keys are represented in storage.
        For Zarr format 3, the default is `{"name": "default", "separator": "/"}`.
        For Zarr format 2, the default is `{"name": "v2", "separator": "."}`.
        If not specified and the data array has the same zarr format as the target array,
        the chunk key encoding of the data array is used.
    dimension_names : Iterable[str | None] | None
        The names of the dimensions (default is None).
        Zarr format 3 only. Zarr format 2 arrays should not use this parameter.
        If not specified, defaults to the dimension names of the data array.
    storage_options : dict, optional
        If using an fsspec URL to create the store, these will be passed to the backend implementation.
        Ignored otherwise.
    overwrite : bool, default False
        Whether to overwrite an array with the same name in the store, if one exists.
    config : ArrayConfig or ArrayConfigLike, optional
        Runtime configuration for the array.

    Returns
    -------
    AsyncArray
        The array.

    Examples
    --------
    Create an array from an existing Array:

        >>> import asyncio
        >>> import zarr
        >>> store = zarr.storage.LocalStore("example.zarr")
        >>> arr = zarr.create_array(
        ...     store={},
        ...     shape=(100,100),
        ...     chunks=(10,10),
        ...     dtype="int32",
        ...     fill_value=0,
        ... )

        >>> arr2 = asyncio.run(from_array(store, data=arr, overwrite=True))
        >>> arr2
        <AsyncArray file://example.zarr shape=(100, 100) dtype=int32>
        >>> asyncio.run(store.clear())  # Remove files generated by test

    Create an array from an existing NumPy array:

        >>> arr3 = asyncio.run(
        ...     from_array({}, data=np.arange(10000, dtype="i4").reshape(100, 100))
        ... )
        >>> arr3
        <AsyncArray memory://... shape=(100, 100) dtype=int32>

    Create an array from any array-like object:

        >>> arr4 = asyncio.run(from_array({}, data=[[1, 2], [3, 4]]))
        >>> arr4
        <AsyncArray memory://... shape=(2, 2) dtype=int64>
        >>> asyncio.run(arr4.getitem(...))
        array([[1, 2],
               [3, 4]])

    Create an array from an existing Array without copying the data:

        >>> arr5 = asyncio.run(from_array({}, data=Array(arr4), write_data=False))
        >>> arr5
        <AsyncArray memory://... shape=(2, 2) dtype=int64>
        >>> asyncio.run(arr5.getitem(...))
        array([[0, 0],
               [0, 0]])
    """
    mode: Literal["a"] = "a"
    config_parsed = parse_array_config(config)
    store_path = await make_store_path(store, path=name, mode=mode, storage_options=storage_options)

    (
        chunks,
        shards,
        filters,
        compressors,
        serializer,
        fill_value,
        order,
        zarr_format,
        chunk_key_encoding,
        dimension_names,
        attributes,
    ) = _parse_keep_array_attr(
        data=data,
        chunks=chunks,
        shards=shards,
        filters=filters,
        compressors=compressors,
        serializer=serializer,
        fill_value=fill_value,
        order=order,
        zarr_format=zarr_format,
        chunk_key_encoding=chunk_key_encoding,
        dimension_names=dimension_names,
        attributes=attributes,
    )
    if not hasattr(data, "dtype") or not hasattr(data, "shape"):
        data = np.array(data)

    # init_array deletes everything under the destination before the copy streams from the
    # source, so a destination that overlaps the source would copy only fill values.
    if (
        write_data
        and overwrite
        and isinstance(data, Array)
        and _stores_share_data(data.store_path.store, store_path.store)
    ):
        src_prefix = f"{data.store_path.path}/" if data.store_path.path else ""
        dest_prefix = f"{store_path.path}/" if store_path.path else ""
        if src_prefix.startswith(dest_prefix) or dest_prefix.startswith(src_prefix):
            raise ValueError(
                f"Cannot overwrite {store_path.path!r} with the array at "
                f"{data.store_path.path!r} because the paths overlap. Write to a different "
                "path, or pass data=array[...]."
            )

    result = await init_array(
        store_path=store_path,
        shape=data.shape,
        # A native object dtype cannot identify the source's Zarr data type.
        dtype=data._async_array._zdtype if isinstance(data, Array) else data.dtype,
        chunks=chunks,
        shards=shards,
        filters=filters,
        compressors=compressors,
        serializer=serializer,
        fill_value=fill_value,
        order=order,
        zarr_format=zarr_format,
        attributes=attributes,
        chunk_key_encoding=chunk_key_encoding,
        dimension_names=dimension_names,
        overwrite=overwrite,
        config=config_parsed,
    )

    if write_data:
        if isinstance(data, Array):

            async def _copy_array_region(
                chunk_coords: tuple[int, ...] | slice, _data: AnyArray
            ) -> None:
                arr = await _data.async_array.getitem(chunk_coords)
                await result.setitem(chunk_coords, arr)

            # Stream data from the source array to the new array
            await concurrent_map(
                [(region, data) for region in result._iter_shard_regions()],
                _copy_array_region,
                zarr.core.config.config.get("async.concurrency"),
            )
        else:

            async def _copy_arraylike_region(chunk_coords: slice, _data: NDArrayLike) -> None:
                await result.setitem(chunk_coords, _data[chunk_coords])

            # Stream data from the source array to the new array
            await concurrent_map(
                [(region, data) for region in result._iter_shard_regions()],
                _copy_arraylike_region,
                zarr.core.config.config.get("async.concurrency"),
            )
    return result

full `async` ¶

full(
    shape: tuple[int, ...], fill_value: Any, **kwargs: Any
) -> AnyAsyncArray

Create an array, with fill_value being used as the default value for uninitialized portions of the array.

Parameters:

shape (int or tuple of int) –

Shape of the empty array.
fill_value (scalar) –

Fill value.
**kwargs (Any, default: {} ) –

Keyword arguments passed to create.

Returns:

Array –

The new array.

Source code in src/zarr/api/asynchronous.py

async def full(shape: tuple[int, ...], fill_value: Any, **kwargs: Any) -> AnyAsyncArray:
    """Create an array, with `fill_value` being used as the default value for
    uninitialized portions of the array.

    Parameters
    ----------
    shape : int or tuple of int
        Shape of the empty array.
    fill_value : scalar
        Fill value.
    **kwargs
        Keyword arguments passed to [`create`][zarr.api.asynchronous.create].

    Returns
    -------
    Array
        The new array.
    """
    return await create(shape=shape, fill_value=fill_value, **kwargs)

full_like `async` ¶

full_like(
    a: ArrayLike,
    *,
    zarr_format: ZarrFormat | None = None,
    **kwargs: Any,
) -> AnyAsyncArray

Create a filled array like a.

Parameters:

a (array - like) –

The array to create an empty array like.
zarr_format ((2, 3, None), default: 2 ) –

The zarr format of the new array. If None (default), the zarr format of a if it is a zarr array, otherwise the default zarr format.
**kwargs (Any, default: {} ) –

Keyword arguments passed to zarr.api.asynchronous.create.

Returns:

Array –

The new array.

Source code in src/zarr/api/asynchronous.py

async def full_like(
    a: ArrayLike, *, zarr_format: ZarrFormat | None = None, **kwargs: Any
) -> AnyAsyncArray:
    """Create a filled array like `a`.

    Parameters
    ----------
    a : array-like
        The array to create an empty array like.
    zarr_format : {2, 3, None}, optional
        The zarr format of the new array. If `None` (default), the zarr format of `a` if it
        is a zarr array, otherwise the default zarr format.
    **kwargs
        Keyword arguments passed to [`zarr.api.asynchronous.create`][].

    Returns
    -------
    Array
        The new array.
    """
    like_kwargs = _like_args(a, zarr_format) | kwargs
    return await full(**like_kwargs)  # type: ignore[arg-type]

group `async` ¶

group(
    *,
    store: StoreLike | None = None,
    overwrite: bool = False,
    chunk_store: StoreLike | None = None,
    cache_attrs: bool | None = None,
    synchronizer: Any | None = None,
    path: str | None = None,
    zarr_format: ZarrFormat | None = None,
    meta_array: Any | None = None,
    attributes: dict[str, JSON] | None = None,
    storage_options: dict[str, Any] | None = None,
) -> AsyncGroup

Create a group.

Parameters:

store (StoreLike or None, default: None ) –

StoreLike object to open. See the storage documentation in the user guide for a description of all valid StoreLike values.
overwrite (bool, default: False ) –

If True, delete any pre-existing data in store at path before creating the group.
chunk_store (StoreLike or None, default: None ) –

Separate storage for chunks. Not implemented.
cache_attrs (bool, default: None ) –

If True (default), user attributes will be cached for attribute read operations. If False, user attributes are reloaded from the store prior to all attribute read operations.
synchronizer (object, default: None ) –

Array synchronizer.
path (str, default: None ) –

Group path within store.
meta_array (array - like, default: None ) –

An array instance to use for determining arrays to create and return to users. Use numpy.empty(()) by default.
zarr_format ((2, 3, None), default: 2 ) –

The zarr format to use when saving.
storage_options (dict, default: None ) –

If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.

Returns:

g ( group ) –

The new group.

Source code in src/zarr/api/asynchronous.py

async def group(
    *,  # Note: this is a change from v2
    store: StoreLike | None = None,
    overwrite: bool = False,
    chunk_store: StoreLike | None = None,  # not used
    cache_attrs: bool | None = None,  # not used, default changed
    synchronizer: Any | None = None,  # not used
    path: str | None = None,
    zarr_format: ZarrFormat | None = None,
    meta_array: Any | None = None,  # not used
    attributes: dict[str, JSON] | None = None,
    storage_options: dict[str, Any] | None = None,
) -> AsyncGroup:
    """Create a group.

    Parameters
    ----------
    store : StoreLike or None, default=None
        StoreLike object to open. See the
        [storage documentation in the user guide][user-guide-store-like]
        for a description of all valid StoreLike values.
    overwrite : bool, optional
        If True, delete any pre-existing data in `store` at `path` before
        creating the group.
    chunk_store : StoreLike or None, default=None
        Separate storage for chunks. Not implemented.
    cache_attrs : bool, optional
        If True (default), user attributes will be cached for attribute read
        operations. If False, user attributes are reloaded from the store prior
        to all attribute read operations.
    synchronizer : object, optional
        Array synchronizer.
    path : str, optional
        Group path within store.
    meta_array : array-like, optional
        An array instance to use for determining arrays to create and return
        to users. Use `numpy.empty(())` by default.
    zarr_format : {2, 3, None}, optional
        The zarr format to use when saving.
    storage_options : dict
        If using an fsspec URL to create the store, these will be passed to
        the backend implementation. Ignored otherwise.

    Returns
    -------
    g : group
        The new group.
    """
    mode: AccessModeLiteral
    if overwrite:
        mode = "w"
    else:
        mode = "a"
    return await open_group(
        store=store,
        mode=mode,
        chunk_store=chunk_store,
        cache_attrs=cache_attrs,
        synchronizer=synchronizer,
        path=path,
        zarr_format=zarr_format,
        meta_array=meta_array,
        attributes=attributes,
        storage_options=storage_options,
    )

load `async` ¶

load(
    *,
    store: StoreLike,
    path: str | None = None,
    zarr_format: ZarrFormat | None = None,
) -> NDArrayLikeOrScalar | dict[str, NDArrayLikeOrScalar]

Load data from an array or group into memory.

Parameters:

store (StoreLike) –

StoreLike object to open. See the storage documentation in the user guide for a description of all valid StoreLike values.
path (str or None, default: None ) –

The path within the store from which to load.

Returns:

out –

If the path contains an array, out will be a numpy array. If the path contains a group, out will be a dict-like object where keys are array names and values are numpy arrays.

ones `async` ¶

ones(
    shape: tuple[int, ...], **kwargs: Any
) -> AnyAsyncArray

Create an array, with one being used as the default value for uninitialized portions of the array.

Parameters:

shape (int or tuple of int) –

Shape of the empty array.
**kwargs (Any, default: {} ) –

Keyword arguments passed to zarr.api.asynchronous.create.

Returns:

Array –

The new array.

Source code in src/zarr/api/asynchronous.py

async def ones(shape: tuple[int, ...], **kwargs: Any) -> AnyAsyncArray:
    """Create an array, with one being used as the default value for
    uninitialized portions of the array.

    Parameters
    ----------
    shape : int or tuple of int
        Shape of the empty array.
    **kwargs
        Keyword arguments passed to [`zarr.api.asynchronous.create`][].

    Returns
    -------
    Array
        The new array.
    """
    return await create(shape=shape, fill_value=1, **kwargs)

ones_like `async` ¶

ones_like(
    a: ArrayLike,
    *,
    zarr_format: ZarrFormat | None = None,
    **kwargs: Any,
) -> AnyAsyncArray

Create an array of ones like a.

Parameters:

a (array - like) –

The array to create an empty array like.
zarr_format ((2, 3, None), default: 2 ) –

The zarr format of the new array. If None (default), the zarr format of a if it is a zarr array, otherwise the default zarr format.
**kwargs (Any, default: {} ) –

Keyword arguments passed to zarr.api.asynchronous.create.

Returns:

Array –

The new array.

Source code in src/zarr/api/asynchronous.py

async def ones_like(
    a: ArrayLike, *, zarr_format: ZarrFormat | None = None, **kwargs: Any
) -> AnyAsyncArray:
    """Create an array of ones like `a`.

    Parameters
    ----------
    a : array-like
        The array to create an empty array like.
    zarr_format : {2, 3, None}, optional
        The zarr format of the new array. If `None` (default), the zarr format of `a` if it
        is a zarr array, otherwise the default zarr format.
    **kwargs
        Keyword arguments passed to [`zarr.api.asynchronous.create`][].

    Returns
    -------
    Array
        The new array.
    """
    like_args = _like_args(a, zarr_format)
    # `ones` supplies its own fill_value, so drop any inherited from `a`.
    like_args.pop("fill_value", None)
    like_kwargs = like_args | kwargs
    return await ones(**like_kwargs)  # type: ignore[arg-type]

open `async` ¶

open(
    *,
    store: StoreLike | None = None,
    mode: AccessModeLiteral | None = None,
    zarr_format: ZarrFormat | None = None,
    path: str | None = None,
    storage_options: dict[str, Any] | None = None,
    **kwargs: Any,
) -> AnyAsyncArray | AsyncGroup

Convenience function to open a group or array using file-mode-like semantics.

Parameters:

store (StoreLike or None, default: None ) –

StoreLike object to open. See the storage documentation in the user guide for a description of all valid StoreLike values.
mode (('r', 'r+', 'a', 'w', 'w-'), default: 'r' ) –

Persistence mode: 'r' means read only (must exist); 'r+' means read/write (must exist); 'a' means read/write (create if doesn't exist); 'w' means create (overwrite if exists); 'w-' means create (fail if exists). On a store that cannot delete keys, 'w' raises an error instead of replacing an existing node. If the store is read-only, the default is 'r'; otherwise, it is 'a'.
zarr_format ((2, 3, None), default: 2 ) –

The zarr format to use when saving.
path (str or None, default: None ) –

The path within the store to open.
storage_options (dict, default: None ) –

If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.
**kwargs (Any, default: {} ) –

Additional parameters are passed through to zarr.open_array or zarr.open_group.

Returns:

z ( array or group ) –

Return type depends on what exists in the given store.

open_array `async` ¶

open_array(
    *,
    store: StoreLike | None = None,
    zarr_format: ZarrFormat | None = None,
    path: PathLike = "",
    storage_options: dict[str, Any] | None = None,
    **kwargs: Any,
) -> AnyAsyncArray

Open an array using file-mode-like semantics.

Parameters:

store (StoreLike, default: None ) –

StoreLike object to open. See the storage documentation in the user guide for a description of all valid StoreLike values.
zarr_format ((2, 3, None), default: 2 ) –

The zarr format to use when saving.
path (str, default: '' ) –

Path in store to array.
storage_options (dict, default: None ) –

If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.
**kwargs (Any, default: {} ) –

Any keyword arguments to pass to create.

Returns:

AsyncArray –

The opened array.

Source code in src/zarr/api/asynchronous.py

async def open_array(
    *,  # note: this is a change from v2
    store: StoreLike | None = None,
    zarr_format: ZarrFormat | None = None,
    path: PathLike = "",
    storage_options: dict[str, Any] | None = None,
    **kwargs: Any,  # TODO: type kwargs as valid args to save
) -> AnyAsyncArray:
    """Open an array using file-mode-like semantics.

    Parameters
    ----------
    store : StoreLike
        StoreLike object to open. See the
        [storage documentation in the user guide][user-guide-store-like]
        for a description of all valid StoreLike values.
    zarr_format : {2, 3, None}, optional
        The zarr format to use when saving.
    path : str, optional
        Path in store to array.
    storage_options : dict
        If using an fsspec URL to create the store, these will be passed to
        the backend implementation. Ignored otherwise.
    **kwargs
        Any keyword arguments to pass to [`create`][zarr.api.asynchronous.create].

    Returns
    -------
    AsyncArray
        The opened array.
    """

    mode = kwargs.pop("mode", None)
    store_path = await make_store_path(store, path=path, mode=mode, storage_options=storage_options)

    if "write_empty_chunks" in kwargs:
        _warn_write_empty_chunks_kwarg()

    # mode "w" replaces any existing array, so there is nothing to open
    if mode != "w":
        try:
            return await AsyncArray.open(store_path, zarr_format=zarr_format)
        except FileNotFoundError as err:
            if store_path.read_only or mode not in _CREATE_MODES:
                msg = f"No array found in store {store_path.store} at path {store_path.path}"
                raise ArrayNotFoundError(msg) from err
    return await create(
        store=store_path,
        zarr_format=zarr_format or _default_zarr_format(),
        overwrite=_infer_overwrite(mode),
        **kwargs,
    )

open_consolidated `async` ¶

open_consolidated(
    *args: Any,
    use_consolidated: Literal[True] = True,
    **kwargs: Any,
) -> AsyncGroup

Alias for open_group with use_consolidated=True.

Source code in src/zarr/api/asynchronous.py

async def open_consolidated(
    *args: Any, use_consolidated: Literal[True] = True, **kwargs: Any
) -> AsyncGroup:
    """
    Alias for [`open_group`][zarr.api.asynchronous.open_group] with `use_consolidated=True`.
    """
    if use_consolidated is not True:
        raise TypeError(
            "'use_consolidated' must be 'True' in 'open_consolidated'. Use 'open' with "
            "'use_consolidated=False' to bypass consolidated metadata."
        )
    return await open_group(*args, use_consolidated=use_consolidated, **kwargs)

open_group `async` ¶

open_group(
    store: StoreLike | None = None,
    *,
    mode: AccessModeLiteral = "a",
    cache_attrs: bool | None = None,
    synchronizer: Any = None,
    path: str | None = None,
    chunk_store: StoreLike | None = None,
    storage_options: dict[str, Any] | None = None,
    zarr_format: ZarrFormat | None = None,
    meta_array: Any | None = None,
    attributes: dict[str, JSON] | None = None,
    use_consolidated: bool | str | None = None,
) -> AsyncGroup

Open a group using file-mode-like semantics.

Parameters:

store (StoreLike or None, default: None ) –

StoreLike object to open. See the storage documentation in the user guide for a description of all valid StoreLike values.
mode (('r', 'r+', 'a', 'w', 'w-'), default: 'r' ) –

Persistence mode: 'r' means read only (must exist); 'r+' means read/write (must exist); 'a' means read/write (create if doesn't exist); 'w' means create (overwrite if exists); 'w-' means create (fail if exists). On a store that cannot delete keys, 'w' raises an error instead of replacing an existing node.
cache_attrs (bool, default: None ) –

If True (default), user attributes will be cached for attribute read operations. If False, user attributes are reloaded from the store prior to all attribute read operations.
synchronizer (object, default: None ) –

Array synchronizer.
path (str, default: None ) –

Group path within store.
chunk_store (StoreLike or None, default: None ) –

Separate storage for chunks. See the storage documentation in the user guide for a description of all valid StoreLike values.
storage_options (dict, default: None ) –

If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.
meta_array (array - like, default: None ) –

An array instance to use for determining arrays to create and return to users. Use numpy.empty(()) by default.
attributes (dict, default: None ) –

A dictionary of JSON-serializable values with user-defined attributes.
use_consolidated (bool or str, default: None ) –

Whether to use consolidated metadata.

By default, consolidated metadata is used if it's present in the store (in the zarr.json for Zarr format 3 and in the .zmetadata file for Zarr format 2).

To explicitly require consolidated metadata, set use_consolidated=True, which will raise an exception if consolidated metadata is not found.

To explicitly not use consolidated metadata, set use_consolidated=False, which will fall back to using the regular, non consolidated metadata.

Zarr format 2 allowed configuring the key storing the consolidated metadata (.zmetadata by default). Specify the custom key as use_consolidated to load consolidated metadata from a non-default key.

Returns:

g ( group ) –

The new group.

Source code in src/zarr/api/asynchronous.py

async def open_group(
    store: StoreLike | None = None,
    *,  # Note: this is a change from v2
    mode: AccessModeLiteral = "a",
    cache_attrs: bool | None = None,  # not used, default changed
    synchronizer: Any = None,  # not used
    path: str | None = None,
    chunk_store: StoreLike | None = None,  # not used
    storage_options: dict[str, Any] | None = None,
    zarr_format: ZarrFormat | None = None,
    meta_array: Any | None = None,  # not used
    attributes: dict[str, JSON] | None = None,
    use_consolidated: bool | str | None = None,
) -> AsyncGroup:
    """Open a group using file-mode-like semantics.

    Parameters
    ----------
    store : StoreLike or None, default=None
        StoreLike object to open. See the
        [storage documentation in the user guide][user-guide-store-like]
        for a description of all valid StoreLike values.
    mode : {'r', 'r+', 'a', 'w', 'w-'}, optional
        Persistence mode: 'r' means read only (must exist); 'r+' means
        read/write (must exist); 'a' means read/write (create if doesn't
        exist); 'w' means create (overwrite if exists); 'w-' means create
        (fail if exists). On a store that cannot delete keys, 'w' raises an
        error instead of replacing an existing node.
    cache_attrs : bool, optional
        If True (default), user attributes will be cached for attribute read
        operations. If False, user attributes are reloaded from the store prior
        to all attribute read operations.
    synchronizer : object, optional
        Array synchronizer.
    path : str, optional
        Group path within store.
    chunk_store : StoreLike or None, default=None
        Separate storage for chunks. See the
        [storage documentation in the user guide][user-guide-store-like]
        for a description of all valid StoreLike values.
    storage_options : dict
        If using an fsspec URL to create the store, these will be passed to
        the backend implementation. Ignored otherwise.
    meta_array : array-like, optional
        An array instance to use for determining arrays to create and return
        to users. Use `numpy.empty(())` by default.
    attributes : dict
        A dictionary of JSON-serializable values with user-defined attributes.
    use_consolidated : bool or str, default None
        Whether to use consolidated metadata.

        By default, consolidated metadata is used if it's present in the
        store (in the `zarr.json` for Zarr format 3 and in the `.zmetadata` file
        for Zarr format 2).

        To explicitly require consolidated metadata, set `use_consolidated=True`,
        which will raise an exception if consolidated metadata is not found.

        To explicitly *not* use consolidated metadata, set `use_consolidated=False`,
        which will fall back to using the regular, non consolidated metadata.

        Zarr format 2 allowed configuring the key storing the consolidated metadata
        (`.zmetadata` by default). Specify the custom key as `use_consolidated`
        to load consolidated metadata from a non-default key.

    Returns
    -------
    g : group
        The new group.
    """

    _warn_unimplemented_kwargs(
        {
            "cache_attrs": cache_attrs,
            "synchronizer": synchronizer,
            "meta_array": meta_array,
            "chunk_store": chunk_store,
        }
    )

    store_path = await make_store_path(store, mode=mode, storage_options=storage_options, path=path)
    if attributes is None:
        attributes = {}

    try:
        if mode in _READ_MODES:
            return await AsyncGroup.open(
                store_path, zarr_format=zarr_format, use_consolidated=use_consolidated
            )
    except (KeyError, FileNotFoundError):
        pass
    if mode in _CREATE_MODES:
        overwrite = _infer_overwrite(mode)
        _zarr_format = zarr_format or _default_zarr_format()
        return await AsyncGroup.from_store(
            store_path,
            zarr_format=_zarr_format,
            overwrite=overwrite,
            attributes=attributes,
        )
    msg = f"No group found in store {store!r} at path {store_path.path!r}"
    raise GroupNotFoundError(msg)

open_like `async` ¶

open_like(
    a: ArrayLike,
    path: str,
    *,
    zarr_format: ZarrFormat | None = None,
    **kwargs: Any,
) -> AnyAsyncArray

Open a persistent array like a.

Parameters:

a (Array) –

The shape and data-type of a define these same attributes of the returned array.
path (str) –

The path to the new array.
zarr_format ((2, 3, None), default: 2 ) –

The zarr format of the array to open or create. If None (default), an existing array of either format is opened, and a missing one is created in the default zarr format. The zarr format of a is not inherited.
**kwargs (Any, default: {} ) –

Additional keyword arguments passed to open_array. If mode is omitted or None, it defaults to "a". Pass mode="r" when opening an existing array from a read-only store.

Returns:

AsyncArray –

The opened array.

Source code in src/zarr/api/asynchronous.py

async def open_like(
    a: ArrayLike, path: str, *, zarr_format: ZarrFormat | None = None, **kwargs: Any
) -> AnyAsyncArray:
    """Open a persistent array like `a`.

    Parameters
    ----------
    a : Array
        The shape and data-type of a define these same attributes of the returned array.
    path : str
        The path to the new array.
    zarr_format : {2, 3, None}, optional
        The zarr format of the array to open or create. If `None` (default), an existing
        array of either format is opened, and a missing one is created in the default zarr
        format. The zarr format of `a` is not inherited.
    **kwargs
        Additional keyword arguments passed to `open_array`.
        If `mode` is omitted or `None`, it defaults to `"a"`. Pass `mode="r"` when
        opening an existing array from a read-only store.

    Returns
    -------
    AsyncArray
        The opened array.
    """
    # The zarr format of `a` is not inherited: `open_array` would then look for an existing
    # array in only that format.
    like_args = _like_args(a, zarr_format or _default_zarr_format())
    like_args.pop("zarr_format")
    like_kwargs = like_args | kwargs
    if like_kwargs.get("mode") is None:
        like_kwargs["mode"] = "a"
    return await open_array(path=path, zarr_format=zarr_format, **like_kwargs)  # type: ignore[arg-type]

save `async` ¶

save(
    store: StoreLike,
    *args: NDArrayLike,
    zarr_format: ZarrFormat | None = None,
    path: str | None = None,
    storage_options: dict[str, Any] | None = None,
    **kwargs: Any,
) -> None

Convenience function to save an array or group of arrays to the local file system.

Parameters:

store (StoreLike) –

StoreLike object to open. See the storage documentation in the user guide for a description of all valid StoreLike values.
*args (ndarray, default: () ) –

NumPy arrays with data to save.
zarr_format ((2, 3, None), default: 2 ) –

The zarr format to use when saving.
path (str or None, default: None ) –

The path within the group where the arrays will be saved.
storage_options (dict, default: None ) –

If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.
**kwargs (Any, default: {} ) –

NumPy arrays with data to save.

Source code in src/zarr/api/asynchronous.py

async def save(
    store: StoreLike,
    *args: NDArrayLike,
    zarr_format: ZarrFormat | None = None,
    path: str | None = None,
    storage_options: dict[str, Any] | None = None,
    **kwargs: Any,  # TODO: type kwargs as valid args to save
) -> None:
    """Convenience function to save an array or group of arrays to the local file system.

    Parameters
    ----------
    store : StoreLike
        StoreLike object to open. See the
        [storage documentation in the user guide][user-guide-store-like]
        for a description of all valid StoreLike values.
    *args : ndarray
        NumPy arrays with data to save.
    zarr_format : {2, 3, None}, optional
        The zarr format to use when saving.
    path : str or None, optional
        The path within the group where the arrays will be saved.
    storage_options : dict
        If using an fsspec URL to create the store, these will be passed to
        the backend implementation. Ignored otherwise.
    **kwargs
        NumPy arrays with data to save.
    """

    if len(args) == 0 and len(kwargs) == 0:
        raise ValueError("at least one array must be provided")
    if len(args) == 1 and len(kwargs) == 0:
        await save_array(
            store, args[0], zarr_format=zarr_format, path=path, storage_options=storage_options
        )
    else:
        await save_group(
            store,
            *args,
            zarr_format=zarr_format,
            path=path,
            storage_options=storage_options,
            **kwargs,
        )

save_array `async` ¶

save_array(
    store: StoreLike,
    arr: NDArrayLike,
    *,
    zarr_format: ZarrFormat | None = None,
    path: str | None = None,
    storage_options: dict[str, Any] | None = None,
    **kwargs: Any,
) -> None

Convenience function to save a NumPy array to the local file system, following a similar API to the NumPy save() function.

Parameters:

store (StoreLike) –

StoreLike object to open. See the storage documentation in the user guide for a description of all valid StoreLike values.
arr (ndarray) –

NumPy array with data to save.
zarr_format ((2, 3, None), default: 2 ) –

The zarr format to use when saving. The default is None, which will use the default Zarr format defined in the global configuration object.
path (str or None, default: None ) –

The path within the store where the array will be saved.
storage_options (dict, default: None ) –

If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.
**kwargs (Any, default: {} ) –

Passed through to create, e.g., compressor.

Source code in src/zarr/api/asynchronous.py

async def save_array(
    store: StoreLike,
    arr: NDArrayLike,
    *,
    zarr_format: ZarrFormat | None = None,
    path: str | None = None,
    storage_options: dict[str, Any] | None = None,
    **kwargs: Any,  # TODO: type kwargs as valid args to create
) -> None:
    """Convenience function to save a NumPy array to the local file system, following a
    similar API to the NumPy save() function.

    Parameters
    ----------
    store : StoreLike
        StoreLike object to open. See the
        [storage documentation in the user guide][user-guide-store-like]
        for a description of all valid StoreLike values.
    arr : ndarray
        NumPy array with data to save.
    zarr_format : {2, 3, None}, optional
        The zarr format to use when saving. The default is `None`, which will
        use the default Zarr format defined in the global configuration object.
    path : str or None, optional
        The path within the store where the array will be saved.
    storage_options : dict
        If using an fsspec URL to create the store, these will be passed to
        the backend implementation. Ignored otherwise.
    **kwargs
        Passed through to [`create`][zarr.api.asynchronous.create], e.g., compressor.
    """
    if zarr_format is None:
        zarr_format = _default_zarr_format()
    if not isinstance(arr, NDArrayLike):
        raise TypeError("arr argument must be numpy or other NDArrayLike array")

    mode = kwargs.pop("mode", "a")
    store_path = await make_store_path(store, path=path, mode=mode, storage_options=storage_options)
    if np.isscalar(arr):
        arr = np.array(arr)
    shape = arr.shape
    chunks = getattr(arr, "chunks", None)  # for array-likes with chunks attribute
    overwrite = kwargs.pop("overwrite", None) or _infer_overwrite(mode)
    zarr_dtype = get_data_type_from_native_dtype(arr.dtype)
    new = await AsyncArray._create(
        store_path,
        zarr_format=zarr_format,
        shape=shape,
        dtype=zarr_dtype,
        chunks=chunks,
        overwrite=overwrite,
        **kwargs,
    )
    await new.setitem(Ellipsis, arr)

save_group `async` ¶

save_group(
    store: StoreLike,
    *args: NDArrayLike,
    zarr_format: ZarrFormat | None = None,
    path: str | None = None,
    storage_options: dict[str, Any] | None = None,
    **kwargs: NDArrayLike,
) -> None

Convenience function to save several NumPy arrays to the local file system, following a similar API to the NumPy savez()/savez_compressed() functions.

Parameters:

store (StoreLike) –

StoreLike object to open. See the storage documentation in the user guide for a description of all valid StoreLike values.
*args (ndarray, default: () ) –

NumPy arrays with data to save.
zarr_format ((2, 3, None), default: 2 ) –

The zarr format to use when saving.
path (str or None, default: None ) –

Path within the store where the group will be saved.
storage_options (dict, default: None ) –

If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.
**kwargs (NDArrayLike, default: {} ) –

NumPy arrays with data to save.

Source code in src/zarr/api/asynchronous.py

async def save_group(
    store: StoreLike,
    *args: NDArrayLike,
    zarr_format: ZarrFormat | None = None,
    path: str | None = None,
    storage_options: dict[str, Any] | None = None,
    **kwargs: NDArrayLike,
) -> None:
    """Convenience function to save several NumPy arrays to the local file system, following a
    similar API to the NumPy savez()/savez_compressed() functions.

    Parameters
    ----------
    store : StoreLike
        StoreLike object to open. See the
        [storage documentation in the user guide][user-guide-store-like]
        for a description of all valid StoreLike values.
    *args : ndarray
        NumPy arrays with data to save.
    zarr_format : {2, 3, None}, optional
        The zarr format to use when saving.
    path : str or None, optional
        Path within the store where the group will be saved.
    storage_options : dict
        If using an fsspec URL to create the store, these will be passed to
        the backend implementation. Ignored otherwise.
    **kwargs
        NumPy arrays with data to save.
    """

    if zarr_format is None:
        zarr_format = _default_zarr_format()

    for arg in args:
        if not isinstance(arg, NDArrayLike):
            raise TypeError(
                "All arguments must be numpy or other NDArrayLike arrays (except store, path, storage_options, and zarr_format)"
            )
    for k, v in kwargs.items():
        if not isinstance(v, NDArrayLike):
            raise TypeError(f"Keyword argument '{k}' must be a numpy or other NDArrayLike array")

    if len(args) == 0 and len(kwargs) == 0:
        raise ValueError("at least one array must be provided")

    # Resolve every data type before anything is deleted, so an array that Zarr cannot
    # store raises while the existing node is still intact.
    for arr in (*args, *kwargs.values()):
        get_data_type_from_native_dtype(arr.dtype)

    store_path = await make_store_path(store, path=path, mode="w", storage_options=storage_options)
    # The group replaces whatever is stored under the path, now that the arguments are known
    # to be valid.
    await AsyncGroup.from_store(store_path, zarr_format=zarr_format, overwrite=True)
    aws = []
    # `store_path` already consumed `storage_options`, so passing them on again would
    # make `make_store_path` reject them as unused.
    for i, arr in enumerate(args):
        aws.append(save_array(store_path, arr, zarr_format=zarr_format, path=f"arr_{i}"))
    for k, arr in kwargs.items():
        aws.append(save_array(store_path, arr, zarr_format=zarr_format, path=k))
    await asyncio.gather(*aws)

tree `async` ¶

tree(
    grp: AsyncGroup,
    expand: bool | None = None,
    level: int | None = None,
) -> Any

Provide a rich display of the hierarchy.

Deprecated

zarr.tree() is deprecated since v3.0.0 and will be removed in a future release. Use group.tree() instead.

Parameters:

grp (Group) –

Zarr or h5py group.
expand (bool, default: None ) –

Only relevant for HTML representation. If True, tree will be fully expanded.
level (int, default: None ) –

Maximum depth to descend into hierarchy.

Returns:

TreeRepr –

A pretty-printable object displaying the hierarchy.

Source code in src/zarr/api/asynchronous.py

@deprecated("Use AsyncGroup.tree instead.", category=ZarrDeprecationWarning)
async def tree(grp: AsyncGroup, expand: bool | None = None, level: int | None = None) -> Any:
    """Provide a rich display of the hierarchy.

    !!! warning "Deprecated"
        `zarr.tree()` is deprecated since v3.0.0 and will be removed in a future release.
        Use `group.tree()` instead.

    Parameters
    ----------
    grp : Group
        Zarr or h5py group.
    expand : bool, optional
        Only relevant for HTML representation. If True, tree will be fully expanded.
    level : int, optional
        Maximum depth to descend into hierarchy.

    Returns
    -------
    TreeRepr
        A pretty-printable object displaying the hierarchy.
    """
    return await grp.tree(expand=expand, level=level)

zeros `async` ¶

zeros(
    shape: tuple[int, ...], **kwargs: Any
) -> AnyAsyncArray

Create an array, with zero being used as the default value for uninitialized portions of the array.

Parameters:

shape (int or tuple of int) –

Shape of the empty array.
**kwargs (Any, default: {} ) –

Keyword arguments passed to zarr.api.asynchronous.create.

Returns:

Array –

The new array.

Source code in src/zarr/api/asynchronous.py

async def zeros(shape: tuple[int, ...], **kwargs: Any) -> AnyAsyncArray:
    """Create an array, with zero being used as the default value for
    uninitialized portions of the array.

    Parameters
    ----------
    shape : int or tuple of int
        Shape of the empty array.
    **kwargs
        Keyword arguments passed to [`zarr.api.asynchronous.create`][].

    Returns
    -------
    Array
        The new array.
    """
    return await create(shape=shape, fill_value=0, **kwargs)

zeros_like `async` ¶

zeros_like(
    a: ArrayLike,
    *,
    zarr_format: ZarrFormat | None = None,
    **kwargs: Any,
) -> AnyAsyncArray

Create an array of zeros like a.

Parameters:

a (array - like) –

The array to create an empty array like.
zarr_format ((2, 3, None), default: 2 ) –

The zarr format of the new array. If None (default), the zarr format of a if it is a zarr array, otherwise the default zarr format.
**kwargs (Any, default: {} ) –

Keyword arguments passed to create.

Returns:

Array –

The new array.

Source code in src/zarr/api/asynchronous.py

async def zeros_like(
    a: ArrayLike, *, zarr_format: ZarrFormat | None = None, **kwargs: Any
) -> AnyAsyncArray:
    """Create an array of zeros like `a`.

    Parameters
    ----------
    a : array-like
        The array to create an empty array like.
    zarr_format : {2, 3, None}, optional
        The zarr format of the new array. If `None` (default), the zarr format of `a` if it
        is a zarr array, otherwise the default zarr format.
    **kwargs
        Keyword arguments passed to [`create`][zarr.api.asynchronous.create].

    Returns
    -------
    Array
        The new array.
    """
    like_args = _like_args(a, zarr_format)
    # `zeros` supplies its own fill_value, so drop any inherited from `a`.
    like_args.pop("fill_value", None)
    like_kwargs = like_args | kwargs
    return await zeros(**like_kwargs)  # type: ignore[arg-type]

zarr.api.asynchronous