zarr.api.asynchronous
=====================

.. py:module:: zarr.api.asynchronous


Functions
---------

.. autoapisummary::

   zarr.api.asynchronous.array
   zarr.api.asynchronous.consolidate_metadata
   zarr.api.asynchronous.copy
   zarr.api.asynchronous.copy_all
   zarr.api.asynchronous.copy_store
   zarr.api.asynchronous.create
   zarr.api.asynchronous.create_array
   zarr.api.asynchronous.create_hierarchy
   zarr.api.asynchronous.empty
   zarr.api.asynchronous.empty_like
   zarr.api.asynchronous.from_array
   zarr.api.asynchronous.full
   zarr.api.asynchronous.full_like
   zarr.api.asynchronous.group
   zarr.api.asynchronous.load
   zarr.api.asynchronous.ones
   zarr.api.asynchronous.ones_like
   zarr.api.asynchronous.open
   zarr.api.asynchronous.open_array
   zarr.api.asynchronous.open_consolidated
   zarr.api.asynchronous.open_group
   zarr.api.asynchronous.open_like
   zarr.api.asynchronous.save
   zarr.api.asynchronous.save_array
   zarr.api.asynchronous.save_group
   zarr.api.asynchronous.tree
   zarr.api.asynchronous.zeros
   zarr.api.asynchronous.zeros_like


Module Contents
---------------

.. py:function:: array(data: numpy.typing.ArrayLike | zarr.core.array.Array, **kwargs: Any) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]
   :async:


   
   Create an array filled with `data`.


   :Parameters:

       **data** : array_like
           The data to fill the array with.

       **\*\*kwargs**
           Passed through to :func:`create`.



   :Returns:

       **array** : array
           The new array.











   ..
       !! processed by numpydoc !!

.. py:function:: consolidate_metadata(store: zarr.storage.StoreLike, path: str | None = None, zarr_format: zarr.core.common.ZarrFormat | None = None) -> zarr.core.group.AsyncGroup
   :async:


   
   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.

       **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``.











   ..
       !! processed by numpydoc !!

.. py:function:: copy(*args: Any, **kwargs: Any) -> tuple[int, int, int]
   :async:


   
   Not implemented.
















   ..
       !! processed by numpydoc !!

.. py:function:: copy_all(*args: Any, **kwargs: Any) -> tuple[int, int, int]
   :async:


   
   Not implemented.
















   ..
       !! processed by numpydoc !!

.. py:function:: copy_store(*args: Any, **kwargs: Any) -> tuple[int, int, int]
   :async:


   
   Not implemented.
















   ..
       !! processed by numpydoc !!

.. py:function:: create(shape: tuple[int, Ellipsis] | int, *, chunks: tuple[int, Ellipsis] | int | bool | None = None, dtype: zarr.core.dtype.ZDTypeLike | None = None, compressor: zarr.core.array.CompressorLike = 'auto', fill_value: Any | None = DEFAULT_FILL_VALUE, order: zarr.core.common.MemoryOrder | None = None, store: zarr.storage.StoreLike | None = None, synchronizer: Any | None = None, overwrite: bool = False, path: PathLike | None = None, chunk_store: zarr.storage.StoreLike | None = None, filters: collections.abc.Iterable[dict[str, zarr.core.common.JSON] | zarr.abc.numcodec.Numcodec] | None = None, cache_metadata: bool | None = None, cache_attrs: bool | None = None, read_only: bool | None = None, object_codec: zarr.abc.codec.Codec | None = None, dimension_separator: Literal['.', '/'] | None = None, write_empty_chunks: bool | None = None, zarr_version: zarr.core.common.ZarrFormat | None = None, zarr_format: zarr.core.common.ZarrFormat | None = None, meta_array: Any | None = None, attributes: dict[str, zarr.core.common.JSON] | None = None, chunk_shape: tuple[int, Ellipsis] | int | None = None, chunk_key_encoding: zarr.core.chunk_key_encodings.ChunkKeyEncoding | tuple[Literal['default'], Literal['.', '/']] | tuple[Literal['v2'], Literal['.', '/']] | None = None, codecs: collections.abc.Iterable[zarr.abc.codec.Codec | dict[str, zarr.core.common.JSON]] | None = None, dimension_names: zarr.core.common.DimensionNames = None, storage_options: dict[str, Any] | None = None, config: zarr.core.array_spec.ArrayConfigLike | None = None, **kwargs: Any) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]
   :async:


   
   Create an array.


   :Parameters:

       **shape** : int or tuple of ints
           Array shape.

       **chunks** : int or tuple of ints, optional
           Chunk shape. If True, will be guessed from ``shape`` and ``dtype``. If
           False, will be set to ``shape``, i.e., single chunk for the whole array.
           If an int, the chunk size in each dimension will be given by the value
           of ``chunks``. Default is True.

       **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
           :class:`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
           Store or path to directory in file system or name of zip file.

       **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 :class:`zarr.abc.codec.ArrayArrayCodec`, or a
           dict representations of :class:`zarr.abc.codec.ArrayArrayCodec`.
           
           For Zarr format 2, a "filter" can be any numcodecs codec; you should ensure that the
           the order if your filters is consistent with the behavior of each filter.
           
           The default value of ``"auto"`` instructs Zarr to use a default used 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
           :class:`zarr.dtype.VariableLengthUTF8` or :class:`zarr.dtype.VariableLengthUTF8`. 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** : int or tuple of ints, 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 :class:`zarr.abc.codec.ArrayBytesCodec`, like variable-length strings or bytes,
           will use the :class:`zarr.abc.codec.ArrayBytesCodec` required for the data type instead of :class:`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`.



   :Returns:

       **z** : array
           The array.











   ..
       !! processed by numpydoc !!

.. py:function:: create_array(store: zarr.storage.StoreLike, *, name: str | None = None, shape: zarr.core.common.ShapeLike | None = None, dtype: zarr.core.dtype.ZDTypeLike | None = None, data: numpy.ndarray[Any, numpy.dtype[Any]] | None = None, chunks: tuple[int, Ellipsis] | Literal['auto'] = 'auto', shards: ShardsLike | None = None, filters: FiltersLike = 'auto', compressors: CompressorsLike = 'auto', serializer: SerializerLike = 'auto', fill_value: Any | None = DEFAULT_FILL_VALUE, order: zarr.core.common.MemoryOrder | None = None, zarr_format: zarr.core.common.ZarrFormat | None = 3, attributes: dict[str, zarr.core.common.JSON] | None = None, chunk_key_encoding: zarr.core.chunk_key_encodings.ChunkKeyEncodingLike | None = None, dimension_names: zarr.core.common.DimensionNames = None, storage_options: dict[str, Any] | None = None, overwrite: bool = False, config: zarr.core.array_spec.ArrayConfigLike | None = None, write_data: bool = True) -> AsyncArray[zarr.core.metadata.ArrayV2Metadata] | AsyncArray[zarr.core.metadata.ArrayV3Metadata]
   :async:


   
   Create an array.


   :Parameters:

       **store** : StoreLike
           Store or path to directory in file system or name of zip file.

       **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, ...] | 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.

       **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 :class:`zarr.abc.codec.ArrayArrayCodec`, or a
           dict representations of :class:`zarr.abc.codec.ArrayArrayCodec`.
           
           For Zarr format 2, a "filter" can be any numcodecs codec; you should ensure that the
           the order if your filters is consistent with the behavior of each filter.
           
           The default value of ``"auto"`` instructs Zarr to use a default used 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
           :class:`zarr.dtype.VariableLengthUTF8` or :class:`zarr.dtype.VariableLengthUTF8`. 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 my 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 :mod:`zarr.core.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.
           in :mod:`zarr.core.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 :mod:`zarr.core.config`.

       **fill_value** : Any, optional
           Fill value for the array.

       **order** : {"C", "F"}, optional
           The memory 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 :mod:`zarr.core.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``, all existing paths in the store will be deleted.

       **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.










   .. rubric:: Examples

   >>> import zarr
   >>> store = zarr.storage.MemoryStore(mode='w')
   >>> async_arr = await zarr.api.asynchronous.create_array(
   >>>     store=store,
   >>>     shape=(100,100),
   >>>     chunks=(10,10),
   >>>     dtype='i4',
   >>>     fill_value=0)
   <AsyncArray memory://140349042942400 shape=(100, 100) dtype=int32>

   ..
       !! processed by numpydoc !!

.. py:function:: create_hierarchy(*, store: zarr.abc.store.Store, nodes: dict[str, GroupMetadata | zarr.core.metadata.ArrayV2Metadata | zarr.core.metadata.ArrayV3Metadata], overwrite: bool = False) -> collections.abc.AsyncIterator[tuple[str, AsyncGroup | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]]]
   :async:


   
   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]
           This function yields (path, node) pairs, in the order the nodes were created.









   .. rubric:: Examples

   >>> from zarr.api.asynchronous import create_hierarchy
   >>> from zarr.storage import MemoryStore
   >>> from zarr.core.group import GroupMetadata
   >>> import asyncio
   >>> store = MemoryStore()
   >>> nodes = {'a': GroupMetadata(attributes={'name': 'leaf'})}
   >>> async def run():
       ... print(dict([x async for x in create_hierarchy(store=store, nodes=nodes)]))
   >>> asyncio.run(run())
   # {'a': <AsyncGroup memory://140345143770112/a>, '': <AsyncGroup memory://140345143770112>}

   ..
       !! processed by numpydoc !!

.. py:function:: empty(shape: tuple[int, Ellipsis], **kwargs: Any) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]
   :async:


   
   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 :func:`zarr.api.asynchronous.create`.











   .. rubric:: 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.



   ..
       !! processed by numpydoc !!

.. py:function:: empty_like(a: ArrayLike, **kwargs: Any) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]
   :async:


   
   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.

       **\*\*kwargs**
           Keyword arguments passed to :func:`zarr.api.asynchronous.create`.



   :Returns:

       Array
           The new array.








   .. rubric:: 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.



   ..
       !! processed by numpydoc !!

.. py:function:: from_array(store: zarr.storage.StoreLike, *, data: Array | numpy.typing.ArrayLike, write_data: bool = True, name: str | None = None, chunks: Literal['auto', 'keep'] | tuple[int, Ellipsis] = 'keep', shards: ShardsLike | None | Literal['keep'] = 'keep', filters: FiltersLike | Literal['keep'] = 'keep', compressors: CompressorsLike | Literal['keep'] = 'keep', serializer: SerializerLike | Literal['keep'] = 'keep', fill_value: Any | None = DEFAULT_FILL_VALUE, order: zarr.core.common.MemoryOrder | None = None, zarr_format: zarr.core.common.ZarrFormat | None = None, attributes: dict[str, zarr.core.common.JSON] | None = None, chunk_key_encoding: zarr.core.chunk_key_encodings.ChunkKeyEncodingLike | None = None, dimension_names: zarr.core.common.DimensionNames = None, storage_options: dict[str, Any] | None = None, overwrite: bool = False, config: zarr.core.array_spec.ArrayConfigLike | None = None) -> AsyncArray[zarr.core.metadata.ArrayV2Metadata] | AsyncArray[zarr.core.metadata.ArrayV3Metadata]
   :async:


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


   :Parameters:

       **store** : StoreLike
           Store or path to directory in file system or name of zip file.

       **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 "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 shape of the data array if it is a zarr Array.
           - tuple[int, ...]: A tuple of integers representing the chunk shape.
           
           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 :class:`zarr.abc.codec.ArrayArrayCodec`, or a
           dict representations of :class:`zarr.abc.codec.ArrayArrayCodec`.
           
           For Zarr format 2, a "filter" can be any numcodecs codec; you should ensure that the
           the order if 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 :class:`zarr.dtype.VariableLengthUTF8` or
           :class:`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 my 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 :mod:`zarr.core.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.

       **order** : {"C", "F"}, optional
           The memory 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, defaults to the attributes of the data array.

       **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.










   .. rubric:: Examples

   Create an array from an existing Array::

       >>> import zarr
       >>> store = zarr.storage.MemoryStore()
       >>> store2 = zarr.storage.LocalStore('example.zarr')
       >>> arr = zarr.create_array(
       >>>     store=store,
       >>>     shape=(100,100),
       >>>     chunks=(10,10),
       >>>     dtype='int32',
       >>>     fill_value=0)
       >>> arr2 = await zarr.api.asynchronous.from_array(store2, data=arr)
       <AsyncArray file://example.zarr shape=(100, 100) dtype=int32>

   Create an array from an existing NumPy array::

       >>> arr3 = await zarr.api.asynchronous.from_array(
       >>>     zarr.storage.MemoryStore(),
       >>>     data=np.arange(10000, dtype='i4').reshape(100, 100),
       >>> )
       <AsyncArray memory://123286956732800 shape=(100, 100) dtype=int32>

   Create an array from any array-like object::

       >>> arr4 = await zarr.api.asynchronous.from_array(
       >>>     zarr.storage.MemoryStore(),
       >>>     data=[[1, 2], [3, 4]],
       >>> )
       <AsyncArray memory://123286959761024 shape=(2, 2) dtype=int64>
       >>> await arr4.getitem(...)
       array([[1, 2],[3, 4]])

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

       >>> arr5 = await zarr.api.asynchronous.from_array(
       >>>     zarr.storage.MemoryStore(),
       >>>     data=Array(arr4),
       >>>     write_data=False,
       >>> )
       <AsyncArray memory://140678602965568 shape=(2, 2) dtype=int64>
       >>> await arr5.getitem(...)
       array([[0, 0],[0, 0]])

   ..
       !! processed by numpydoc !!

.. py:function:: full(shape: tuple[int, Ellipsis], fill_value: Any, **kwargs: Any) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]
   :async:


   
   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 :func:`zarr.api.asynchronous.create`.



   :Returns:

       Array
           The new array.











   ..
       !! processed by numpydoc !!

.. py:function:: full_like(a: ArrayLike, **kwargs: Any) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]
   :async:


   
   Create a filled array like `a`.


   :Parameters:

       **a** : array-like
           The array to create an empty array like.

       **\*\*kwargs**
           Keyword arguments passed to :func:`zarr.api.asynchronous.create`.



   :Returns:

       Array
           The new array.











   ..
       !! processed by numpydoc !!

.. py:function:: group(*, store: zarr.storage.StoreLike | None = None, overwrite: bool = False, chunk_store: zarr.storage.StoreLike | None = None, cache_attrs: bool | None = None, synchronizer: Any | None = None, path: str | None = None, zarr_version: zarr.core.common.ZarrFormat | None = None, zarr_format: zarr.core.common.ZarrFormat | None = None, meta_array: Any | None = None, attributes: dict[str, zarr.core.common.JSON] | None = None, storage_options: dict[str, Any] | None = None) -> zarr.core.group.AsyncGroup
   :async:


   
   Create a group.


   :Parameters:

       **store** : StoreLike or None, default=None
           Store or path to directory in file system or name of zip file.

       **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.











   ..
       !! processed by numpydoc !!

.. py:function:: load(*, store: zarr.storage.StoreLike, path: str | None = None, zarr_format: zarr.core.common.ZarrFormat | None = None, zarr_version: zarr.core.common.ZarrFormat | None = None) -> zarr.core.buffer.NDArrayLikeOrScalar | dict[str, zarr.core.buffer.NDArrayLikeOrScalar]
   :async:


   
   Load data from an array or group into memory.


   :Parameters:

       **store** : StoreLike
           Store or path to directory in file system or name of zip file.

       **path** : str or None, optional
           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.







   .. seealso::

       
       :obj:`save`, :obj:`savez`
           ..
       
   .. rubric:: Notes

   If loading data from a group of arrays, data will not be immediately loaded into
   memory. Rather, arrays will be loaded into memory as they are requested.



   ..
       !! processed by numpydoc !!

.. py:function:: ones(shape: tuple[int, Ellipsis], **kwargs: Any) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]
   :async:


   
   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 :func:`zarr.api.asynchronous.create`.



   :Returns:

       Array
           The new array.











   ..
       !! processed by numpydoc !!

.. py:function:: ones_like(a: ArrayLike, **kwargs: Any) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]
   :async:


   
   Create an array of ones like `a`.


   :Parameters:

       **a** : array-like
           The array to create an empty array like.

       **\*\*kwargs**
           Keyword arguments passed to :func:`zarr.api.asynchronous.create`.



   :Returns:

       Array
           The new array.











   ..
       !! processed by numpydoc !!

.. py:function:: open(*, store: zarr.storage.StoreLike | None = None, mode: zarr.core.common.AccessModeLiteral | None = None, zarr_version: zarr.core.common.ZarrFormat | None = None, zarr_format: zarr.core.common.ZarrFormat | None = None, path: str | None = None, storage_options: dict[str, Any] | None = None, **kwargs: Any) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata] | zarr.core.group.AsyncGroup
   :async:


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


   :Parameters:

       **store** : StoreLike or None, default=None
           Store or path to directory in file system or name of zip file.

       **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).
           If the store is read-only, the default is 'r'; otherwise, it is 'a'.

       **zarr_format** : {2, 3, None}, optional
           The zarr format to use when saving.

       **path** : str or None, optional
           The path within the store to open.

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

       **\*\*kwargs**
           Additional parameters are passed through to :func:`zarr.creation.open_array` or
           :func:`zarr.hierarchy.open_group`.



   :Returns:

       **z** : array or group
           Return type depends on what exists in the given store.











   ..
       !! processed by numpydoc !!

.. py:function:: open_array(*, store: zarr.storage.StoreLike | None = None, zarr_version: zarr.core.common.ZarrFormat | None = None, zarr_format: zarr.core.common.ZarrFormat | None = None, path: PathLike = '', storage_options: dict[str, Any] | None = None, **kwargs: Any) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]
   :async:


   
   Open an array using file-mode-like semantics.


   :Parameters:

       **store** : StoreLike
           Store or path to directory in file system or name of zip file.

       **zarr_version** : {2, 3, None}, optional
           The zarr format to use when saving. Deprecated in favor of zarr_format.

       **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 :func:`create`.



   :Returns:

       AsyncArray
           The opened array.











   ..
       !! processed by numpydoc !!

.. py:function:: open_consolidated(*args: Any, use_consolidated: Literal[True] = True, **kwargs: Any) -> zarr.core.group.AsyncGroup
   :async:


   
   Alias for :func:`open_group` with ``use_consolidated=True``.
















   ..
       !! processed by numpydoc !!

.. py:function:: open_group(store: zarr.storage.StoreLike | None = None, *, mode: zarr.core.common.AccessModeLiteral = 'a', cache_attrs: bool | None = None, synchronizer: Any = None, path: str | None = None, chunk_store: zarr.storage.StoreLike | None = None, storage_options: dict[str, Any] | None = None, zarr_version: zarr.core.common.ZarrFormat | None = None, zarr_format: zarr.core.common.ZarrFormat | None = None, meta_array: Any | None = None, attributes: dict[str, zarr.core.common.JSON] | None = None, use_consolidated: bool | str | None = None) -> zarr.core.group.AsyncGroup
   :async:


   
   Open a group using file-mode-like semantics.


   :Parameters:

       **store** : StoreLike or None, default=None
           Store or path to directory in file system or name of zip file.
           
           Strings are interpreted as paths on the local file system
           and used as the ``root`` argument to :class:`zarr.storage.LocalStore`.
           
           Dictionaries are used as the ``store_dict`` argument in
           :class:`zarr.storage.MemoryStore``.
           
           By default (``store=None``) a new :class:`zarr.storage.MemoryStore`
           is created.

       **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).

       **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
           Store or path to directory in file system or name of zip file.

       **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.











   ..
       !! processed by numpydoc !!

.. py:function:: open_like(a: ArrayLike, path: str, **kwargs: Any) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata]
   :async:


   
   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.

       **\*\*kwargs**
           Any keyword arguments to pass to the array constructor.



   :Returns:

       AsyncArray
           The opened array.











   ..
       !! processed by numpydoc !!

.. py:function:: save(store: zarr.storage.StoreLike, *args: zarr.core.buffer.NDArrayLike, zarr_version: zarr.core.common.ZarrFormat | None = None, zarr_format: zarr.core.common.ZarrFormat | None = None, path: str | None = None, **kwargs: Any) -> None
   :async:


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


   :Parameters:

       **store** : StoreLike
           Store or path to directory in file system or name of zip file.

       **\*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.

       **\*\*kwargs**
           NumPy arrays with data to save.














   ..
       !! processed by numpydoc !!

.. py:function:: save_array(store: zarr.storage.StoreLike, arr: zarr.core.buffer.NDArrayLike, *, zarr_version: zarr.core.common.ZarrFormat | None = None, zarr_format: zarr.core.common.ZarrFormat | None = None, path: str | None = None, storage_options: dict[str, Any] | None = None, **kwargs: Any) -> None
   :async:


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


   :Parameters:

       **store** : StoreLike
           Store or path to directory in file system or name of zip file.

       **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 :func:`create`, e.g., compressor.














   ..
       !! processed by numpydoc !!

.. py:function:: save_group(store: zarr.storage.StoreLike, *args: zarr.core.buffer.NDArrayLike, zarr_version: zarr.core.common.ZarrFormat | None = None, zarr_format: zarr.core.common.ZarrFormat | None = None, path: str | None = None, storage_options: dict[str, Any] | None = None, **kwargs: zarr.core.buffer.NDArrayLike) -> None
   :async:


   
   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
           Store or path to directory in file system or name of zip file.

       **\*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.














   ..
       !! processed by numpydoc !!

.. py:function:: tree(grp: zarr.core.group.AsyncGroup, expand: bool | None = None, level: int | None = None) -> Any
   :async:


   
   Provide a rich display of the hierarchy.

   .. deprecated:: 3.0.0
       `zarr.tree()` is deprecated 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.











   ..
       !! processed by numpydoc !!

.. py:function:: zeros(shape: tuple[int, Ellipsis], **kwargs: Any) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]
   :async:


   
   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 :func:`zarr.api.asynchronous.create`.



   :Returns:

       Array
           The new array.











   ..
       !! processed by numpydoc !!

.. py:function:: zeros_like(a: ArrayLike, **kwargs: Any) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]
   :async:


   
   Create an array of zeros like `a`.


   :Parameters:

       **a** : array-like
           The array to create an empty array like.

       **\*\*kwargs**
           Keyword arguments passed to :func:`zarr.api.asynchronous.create`.



   :Returns:

       Array
           The new array.











   ..
       !! processed by numpydoc !!

