Group

zarr.Group dataclass

Bases: SyncMixin

A Zarr group.

Source code in zarr/core/group.py

@dataclass(frozen=True)
class Group(SyncMixin):
    """
    A Zarr group.
    """

    _async_group: AsyncGroup

    @classmethod
    def from_store(
        cls,
        store: StoreLike,
        *,
        attributes: dict[str, Any] | None = None,
        zarr_format: ZarrFormat = 3,
        overwrite: bool = False,
    ) -> Group:
        """Instantiate a group from an initialized store.

        Parameters
        ----------
        store : StoreLike
            StoreLike containing the Group.
        attributes : dict, optional
            A dictionary of JSON-serializable values with user-defined attributes.
        zarr_format : {2, 3}, optional
            Zarr storage format version.
        overwrite : bool, optional
            If True, do not raise an error if the group already exists.

        Returns
        -------
        Group
            Group instantiated from the store.

        Raises
        ------
        ContainsArrayError, ContainsGroupError, ContainsArrayAndGroupError
        """
        attributes = attributes or {}
        obj = sync(
            AsyncGroup.from_store(
                store,
                attributes=attributes,
                overwrite=overwrite,
                zarr_format=zarr_format,
            ),
        )

        return cls(obj)

    @classmethod
    def open(
        cls,
        store: StoreLike,
        zarr_format: ZarrFormat | None = 3,
    ) -> Group:
        """Open a group from an initialized store.

        Parameters
        ----------
        store : StoreLike
            Store containing the Group.
        zarr_format : {2, 3, None}, optional
            Zarr storage format version.

        Returns
        -------
        Group
            Group instantiated from the store.
        """
        obj = sync(AsyncGroup.open(store, zarr_format=zarr_format))
        return cls(obj)

    def __getitem__(self, path: str) -> Array | Group:
        """Obtain a group member.

        Parameters
        ----------
        path : str
            Group member name.

        Returns
        -------
        Array | Group
            Group member (Array or Group) at the specified key

        Examples
        --------
        >>> import zarr
        >>> group = Group.from_store(zarr.storage.MemoryStore()
        >>> group.create_array(name="subarray", shape=(10,), chunks=(10,))
        >>> group.create_group(name="subgroup").create_array(name="subarray", shape=(10,), chunks=(10,))
        >>> group["subarray"]
        <Array memory://132270269438272/subarray shape=(10,) dtype=float64>
        >>> group["subgroup"]
        <Group memory://132270269438272/subgroup>
        >>> group["subgroup"]["subarray"]
        <Array memory://132270269438272/subgroup/subarray shape=(10,) dtype=float64>

        """
        obj = self._sync(self._async_group.getitem(path))
        if isinstance(obj, AsyncArray):
            return Array(obj)
        else:
            return Group(obj)

    def get(self, path: str, default: DefaultT | None = None) -> Array | Group | DefaultT | None:
        """Obtain a group member, returning default if not found.

        Parameters
        ----------
        path : str
            Group member name.
        default : object
            Default value to return if key is not found (default: None).

        Returns
        -------
        object
            Group member (Array or Group) or default if not found.

        Examples
        --------
        >>> import zarr
        >>> group = Group.from_store(zarr.storage.MemoryStore()
        >>> group.create_array(name="subarray", shape=(10,), chunks=(10,))
        >>> group.create_group(name="subgroup")
        >>> group.get("subarray")
        <Array memory://132270269438272/subarray shape=(10,) dtype=float64>
        >>> group.get("subgroup")
        <Group memory://132270269438272/subgroup>
        >>> group.get("nonexistent", None)

        """
        try:
            return self[path]
        except KeyError:
            return default

    def __delitem__(self, key: str) -> None:
        """Delete a group member.

        Parameters
        ----------
        key : str
            Group member name.

        Examples
        --------
        >>> import zarr
        >>> group = Group.from_store(zarr.storage.MemoryStore()
        >>> group.create_array(name="subarray", shape=(10,), chunks=(10,))
        >>> del group["subarray"]
        >>> "subarray" in group
        False
        """
        self._sync(self._async_group.delitem(key))

    def __iter__(self) -> Iterator[str]:
        """Return an iterator over group member names.
        Examples
        --------
        >>> import zarr
        >>> g1 = zarr.group()
        >>> g2 = g1.create_group('foo')
        >>> g3 = g1.create_group('bar')
        >>> d1 = g1.create_array('baz', shape=(10,), chunks=(10,))
        >>> d2 = g1.create_array('quux', shape=(10,), chunks=(10,))
        >>> for name in g1:
        ...     print(name)
        baz
        bar
        foo
        quux
        """
        yield from self.keys()

    def __len__(self) -> int:
        """Number of members."""
        return self.nmembers()

    def __setitem__(self, key: str, value: Any) -> None:
        """Fastpath for creating a new array.

        New arrays will be created using default settings for the array type.
        If you need to create an array with custom settings, use the `create_array` method.

        Parameters
        ----------
        key : str
            Array name.
        value : Any
            Array data.

        Examples
        --------
        >>> import zarr
        >>> group = zarr.group()
        >>> group["foo"] = zarr.zeros((10,))
        >>> group["foo"]
        <Array memory://132270269438272/foo shape=(10,) dtype=float64>
        """
        self._sync(self._async_group.setitem(key, value))

    def __repr__(self) -> str:
        return f"<Group {self.store_path}>"

    async def update_attributes_async(self, new_attributes: dict[str, Any]) -> Group:
        """Update the attributes of this group.

        Examples
        --------
        >>> import zarr
        >>> group = zarr.group()
        >>> await group.update_attributes_async({"foo": "bar"})
        >>> group.attrs.asdict()
        {'foo': 'bar'}
        """
        new_metadata = replace(self.metadata, attributes=new_attributes)

        # Write new metadata
        to_save = new_metadata.to_buffer_dict(default_buffer_prototype())
        awaitables = [set_or_delete(self.store_path / key, value) for key, value in to_save.items()]
        await asyncio.gather(*awaitables)

        async_group = replace(self._async_group, metadata=new_metadata)
        return replace(self, _async_group=async_group)

    @property
    def store_path(self) -> StorePath:
        """Path-like interface for the Store."""
        return self._async_group.store_path

    @property
    def metadata(self) -> GroupMetadata:
        """Group metadata."""
        return self._async_group.metadata

    @property
    def path(self) -> str:
        """Storage path."""
        return self._async_group.path

    @property
    def name(self) -> str:
        """Group name following h5py convention."""
        return self._async_group.name

    @property
    def basename(self) -> str:
        """Final component of name."""
        return self._async_group.basename

    @property
    def attrs(self) -> Attributes:
        """Attributes of this Group"""
        return Attributes(self)

    @property
    def info(self) -> Any:
        """
        Return the statically known information for a group.

        Returns
        -------
        GroupInfo

        Related
        -------
        [zarr.Group.info_complete][]
            All information about a group, including dynamic information
            like the children members.
        """
        return self._async_group.info

    def info_complete(self) -> Any:
        """
        Return information for a group.

        If this group doesn't contain consolidated metadata then
        this will need to read from the backing Store.

        Returns
        -------
        GroupInfo

        Related
        -------
        [zarr.Group.info][]
        """
        return self._sync(self._async_group.info_complete())

    @property
    def store(self) -> Store:
        # Backwards compatibility for 2.x
        return self._async_group.store

    @property
    def read_only(self) -> bool:
        # Backwards compatibility for 2.x
        return self._async_group.read_only

    @property
    def synchronizer(self) -> None:
        # Backwards compatibility for 2.x
        # Not implemented in 3.x yet.
        return self._async_group.synchronizer

    def update_attributes(self, new_attributes: dict[str, Any]) -> Group:
        """Update the attributes of this group.

        Examples
        --------
        >>> import zarr
        >>> group = zarr.group()
        >>> group.update_attributes({"foo": "bar"})
        >>> group.attrs.asdict()
        {'foo': 'bar'}
        """
        self._sync(self._async_group.update_attributes(new_attributes))
        return self

    def nmembers(self, max_depth: int | None = 0) -> int:
        """Count the number of members in this group.

        Parameters
        ----------
        max_depth : int, default 0
            The maximum number of levels of the hierarchy to include. By
            default, (``max_depth=0``) only immediate children are included. Set
            ``max_depth=None`` to include all nodes, and some positive integer
            to consider children within that many levels of the root Group.

        Returns
        -------
        count : int
        """

        return self._sync(self._async_group.nmembers(max_depth=max_depth))

    def members(
        self, max_depth: int | None = 0, *, use_consolidated_for_children: bool = True
    ) -> tuple[tuple[str, Array | Group], ...]:
        """
        Returns an AsyncGenerator over the arrays and groups contained in this group.
        This method requires that `store_path.store` supports directory listing.

        The results are not guaranteed to be ordered.

        Parameters
        ----------
        max_depth : int, default 0
            The maximum number of levels of the hierarchy to include. By
            default, (``max_depth=0``) only immediate children are included. Set
            ``max_depth=None`` to include all nodes, and some positive integer
            to consider children within that many levels of the root Group.
        use_consolidated_for_children : bool, default True
            Whether to use the consolidated metadata of child groups loaded
            from the store. Note that this only affects groups loaded from the
            store. If the current Group already has consolidated metadata, it
            will always be used.

        Returns
        -------
        path:
            A string giving the path to the target, relative to the Group ``self``.
        value: AsyncArray or AsyncGroup
            The AsyncArray or AsyncGroup that is a child of ``self``.
        """
        _members = self._sync_iter(self._async_group.members(max_depth=max_depth))

        return tuple((kv[0], _parse_async_node(kv[1])) for kv in _members)

    def create_hierarchy(
        self,
        nodes: dict[str, ArrayV2Metadata | ArrayV3Metadata | GroupMetadata],
        *,
        overwrite: bool = False,
    ) -> Iterator[tuple[str, Group | Array]]:
        """
        Create a hierarchy of arrays or groups rooted at this group.

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

        Explicitly specifying a root group, e.g. with ``nodes = {'': GroupMetadata()}`` is an error
        because this group instance is the root group.

        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
        ----------
        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 path of the group. The values are instances of ``GroupMetadata`` or ``ArrayMetadata``. Note that
            all values must have the same ``zarr_format`` as the parent group -- 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, Array | Group].

        Examples
        --------
        >>> import zarr
        >>> from zarr.core.group import GroupMetadata
        >>> root = zarr.create_group(store={})
        >>> for key, val in root.create_hierarchy({'a/b/c': GroupMetadata()}):
        ...   print(key, val)
        ...
        <AsyncGroup memory://123209880766144/a>
        <AsyncGroup memory://123209880766144/a/b/c>
        <AsyncGroup memory://123209880766144/a/b>
        """
        for key, node in self._sync_iter(
            self._async_group.create_hierarchy(nodes, overwrite=overwrite)
        ):
            yield (key, _parse_async_node(node))

    def keys(self) -> Generator[str, None]:
        """Return an iterator over group member names.

        Examples
        --------
        >>> import zarr
        >>> g1 = zarr.group()
        >>> g2 = g1.create_group('foo')
        >>> g3 = g1.create_group('bar')
        >>> d1 = g1.create_array('baz', shape=(10,), chunks=(10,))
        >>> d2 = g1.create_array('quux', shape=(10,), chunks=(10,))
        >>> for name in g1.keys():
        ...     print(name)
        baz
        bar
        foo
        quux
        """
        yield from self._sync_iter(self._async_group.keys())

    def __contains__(self, member: str) -> bool:
        """Test for group membership.

        Examples
        --------
        >>> import zarr
        >>> g1 = zarr.group()
        >>> g2 = g1.create_group('foo')
        >>> d1 = g1.create_array('bar', shape=(10,), chunks=(10,))
        >>> 'foo' in g1
        True
        >>> 'bar' in g1
        True
        >>> 'baz' in g1
        False

        """
        return self._sync(self._async_group.contains(member))

    def groups(self) -> Generator[tuple[str, Group], None]:
        """Return the sub-groups of this group as a generator of (name, group) pairs.

        Examples
        --------
        >>> import zarr
        >>> group = zarr.group()
        >>> group.create_group("subgroup")
        >>> for name, subgroup in group.groups():
        ...     print(name, subgroup)
        subgroup <Group memory://132270269438272/subgroup>
        """
        for name, async_group in self._sync_iter(self._async_group.groups()):
            yield name, Group(async_group)

    def group_keys(self) -> Generator[str, None]:
        """Return an iterator over group member names.

        Examples
        --------
        >>> import zarr
        >>> group = zarr.group()
        >>> group.create_group("subgroup")
        >>> for name in group.group_keys():
        ...     print(name)
        subgroup
        """
        for name, _ in self.groups():
            yield name

    def group_values(self) -> Generator[Group, None]:
        """Return an iterator over group members.

        Examples
        --------
        >>> import zarr
        >>> group = zarr.group()
        >>> group.create_group("subgroup")
        >>> for subgroup in group.group_values():
        ...     print(subgroup)
        <Group memory://132270269438272/subgroup>
        """
        for _, group in self.groups():
            yield group

    def arrays(self) -> Generator[tuple[str, Array], None]:
        """Return the sub-arrays of this group as a generator of (name, array) pairs

        Examples
        --------
        >>> import zarr
        >>> group = zarr.group()
        >>> group.create_array("subarray", shape=(10,), chunks=(10,))
        >>> for name, subarray in group.arrays():
        ...     print(name, subarray)
        subarray <Array memory://140198565357056/subarray shape=(10,) dtype=float64>
        """
        for name, async_array in self._sync_iter(self._async_group.arrays()):
            yield name, Array(async_array)

    def array_keys(self) -> Generator[str, None]:
        """Return an iterator over group member names.

        Examples
        --------
        >>> import zarr
        >>> group = zarr.group()
        >>> group.create_array("subarray", shape=(10,), chunks=(10,))
        >>> for name in group.array_keys():
        ...     print(name)
        subarray
        """

        for name, _ in self.arrays():
            yield name

    def array_values(self) -> Generator[Array, None]:
        """Return an iterator over group members.

        Examples
        --------
        >>> import zarr
        >>> group = zarr.group()
        >>> group.create_array("subarray", shape=(10,), chunks=(10,))
        >>> for subarray in group.array_values():
        ...     print(subarray)
        <Array memory://140198565357056/subarray shape=(10,) dtype=float64>
        """
        for _, array in self.arrays():
            yield array

    def tree(self, expand: bool | None = None, level: int | None = None) -> Any:
        """
        Return a tree-like representation of a hierarchy.

        This requires the optional ``rich`` dependency.

        Parameters
        ----------
        expand : bool, optional
            This keyword is not yet supported. A NotImplementedError is raised if
            it's used.
        level : int, optional
            The maximum depth below this Group to display in the tree.

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

    def create_group(self, name: str, **kwargs: Any) -> Group:
        """Create a sub-group.

        Parameters
        ----------
        name : str
            Name of the new subgroup.

        Returns
        -------
        Group

        Examples
        --------
        >>> import zarr
        >>> group = zarr.group()
        >>> subgroup = group.create_group("subgroup")
        >>> subgroup
        <Group memory://132270269438272/subgroup>
        """
        return Group(self._sync(self._async_group.create_group(name, **kwargs)))

    def require_group(self, name: str, **kwargs: Any) -> Group:
        """Obtain a sub-group, creating one if it doesn't exist.

        Parameters
        ----------
        name : str
            Group name.

        Returns
        -------
        g : Group
        """
        return Group(self._sync(self._async_group.require_group(name, **kwargs)))

    def require_groups(self, *names: str) -> tuple[Group, ...]:
        """Convenience method to require multiple groups in a single call.

        Parameters
        ----------
        *names : str
            Group names.

        Returns
        -------
        groups : tuple of Groups
        """
        return tuple(map(Group, self._sync(self._async_group.require_groups(*names))))

    def create(
        self,
        name: str,
        *,
        shape: ShapeLike | None = None,
        dtype: ZDTypeLike | None = None,
        data: np.ndarray[Any, np.dtype[Any]] | None = None,
        chunks: tuple[int, ...] | Literal["auto"] = "auto",
        shards: ShardsLike | None = None,
        filters: FiltersLike = "auto",
        compressors: CompressorsLike = "auto",
        compressor: CompressorLike = "auto",
        serializer: SerializerLike = "auto",
        fill_value: Any | None = DEFAULT_FILL_VALUE,
        order: MemoryOrder | None = None,
        attributes: dict[str, JSON] | None = None,
        chunk_key_encoding: ChunkKeyEncodingLike | None = None,
        dimension_names: DimensionNames = None,
        storage_options: dict[str, Any] | None = None,
        overwrite: bool = False,
        config: ArrayConfigLike | None = None,
        write_data: bool = True,
    ) -> Array:
        """Create an array within this group.

        This method lightly wraps [`zarr.core.array.create_array`][].

        Parameters
        ----------
        name : str
            The name of the array relative to the group. If ``path`` 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 : npt.DTypeLike | None
            Data type of the array. Must be ``None`` if ``data`` is provided.
        data : 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, ...], optional
            Chunk shape of the array.
            If not specified, default are guessed based on the shape and 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 [`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
            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
            [`zarr.dtype.VariableLengthUTF8`][] or [`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 [`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.
            in [`zarr.config`][].
            Use ``None`` to omit the default compressor.
        compressor : Codec, optional
            Deprecated in favor of ``compressors``.
        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`][].
        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 [`zarr.config`][].
        attributes : dict, optional
            Attributes for the 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": "."}}``.
        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.
        config : ArrayConfig or 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
        """
        return self.create_array(
            name,
            shape=shape,
            dtype=dtype,
            data=data,
            chunks=chunks,
            shards=shards,
            filters=filters,
            compressors=compressors,
            compressor=compressor,
            serializer=serializer,
            fill_value=fill_value,
            order=order,
            attributes=attributes,
            chunk_key_encoding=chunk_key_encoding,
            dimension_names=dimension_names,
            storage_options=storage_options,
            overwrite=overwrite,
            config=config,
            write_data=write_data,
        )

    def create_array(
        self,
        name: str,
        *,
        shape: ShapeLike | None = None,
        dtype: ZDTypeLike | None = None,
        data: np.ndarray[Any, np.dtype[Any]] | None = None,
        chunks: tuple[int, ...] | Literal["auto"] = "auto",
        shards: ShardsLike | None = None,
        filters: FiltersLike = "auto",
        compressors: CompressorsLike = "auto",
        compressor: CompressorLike = "auto",
        serializer: SerializerLike = "auto",
        fill_value: Any | None = DEFAULT_FILL_VALUE,
        order: MemoryOrder | None = None,
        attributes: dict[str, JSON] | None = None,
        chunk_key_encoding: ChunkKeyEncodingLike | None = None,
        dimension_names: DimensionNames = None,
        storage_options: dict[str, Any] | None = None,
        overwrite: bool = False,
        config: ArrayConfigLike | None = None,
        write_data: bool = True,
    ) -> Array:
        """Create an array within this group.

        This method lightly wraps [zarr.core.array.create_array][].

        Parameters
        ----------
        name : str
            The name of the array relative to the group. If ``path`` 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 : npt.DTypeLike | None
            Data type of the array. Must be ``None`` if ``data`` is provided.
        data : 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, ...], optional
            Chunk shape of the array.
            If not specified, default are guessed based on the shape and 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 [`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
            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
            [`zarr.dtype.VariableLengthUTF8`][] or [`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 [`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.
            in [`zarr.config`][zarr.config].
            Use ``None`` to omit the default compressor.
        compressor : Codec, optional
            Deprecated in favor of ``compressors``.
        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 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].
        attributes : dict, optional
            Attributes for the 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": "."}}``.
        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.
        config : ArrayConfig or 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
        """
        compressors = _parse_deprecated_compressor(
            compressor, compressors, zarr_format=self.metadata.zarr_format
        )
        return Array(
            self._sync(
                self._async_group.create_array(
                    name=name,
                    shape=shape,
                    dtype=dtype,
                    data=data,
                    chunks=chunks,
                    shards=shards,
                    fill_value=fill_value,
                    attributes=attributes,
                    chunk_key_encoding=chunk_key_encoding,
                    compressors=compressors,
                    serializer=serializer,
                    dimension_names=dimension_names,
                    order=order,
                    filters=filters,
                    overwrite=overwrite,
                    storage_options=storage_options,
                    config=config,
                    write_data=write_data,
                )
            )
        )

    @deprecated("Use Group.create_array instead.", category=ZarrDeprecationWarning)
    def create_dataset(self, name: str, **kwargs: Any) -> Array:
        """Create an array.

        !!! warning "Deprecated"
            `Group.create_dataset()` is deprecated since v3.0.0 and will be removed in v3.1.0.
            Use `Group.create_array` instead.


        Arrays are known as "datasets" in HDF5 terminology. For compatibility
        with h5py, Zarr groups also implement the [zarr.Group.require_dataset][] method.

        Parameters
        ----------
        name : str
            Array name.
        **kwargs : dict
            Additional arguments passed to [zarr.Group.create_array][]

        Returns
        -------
        a : Array
        """
        return Array(self._sync(self._async_group.create_dataset(name, **kwargs)))

    @deprecated("Use Group.require_array instead.", category=ZarrDeprecationWarning)
    def require_dataset(self, name: str, *, shape: ShapeLike, **kwargs: Any) -> Array:
        """Obtain an array, creating if it doesn't exist.

        !!! warning "Deprecated"
            `Group.require_dataset()` is deprecated since v3.0.0 and will be removed in v3.1.0.
            Use `Group.require_array` instead.

        Arrays are known as "datasets" in HDF5 terminology. For compatibility
        with h5py, Zarr groups also implement the [zarr.Group.create_dataset][] method.

        Other `kwargs` are as per [zarr.Group.create_dataset][].

        Parameters
        ----------
        name : str
            Array name.
        **kwargs :
            See [zarr.Group.create_dataset][].

        Returns
        -------
        a : Array
        """
        return Array(self._sync(self._async_group.require_array(name, shape=shape, **kwargs)))

    def require_array(self, name: str, *, shape: ShapeLike, **kwargs: Any) -> Array:
        """Obtain an array, creating if it doesn't exist.

        Other `kwargs` are as per [zarr.Group.create_array][].

        Parameters
        ----------
        name : str
            Array name.
        **kwargs :
            See [zarr.Group.create_array][].

        Returns
        -------
        a : Array
        """
        return Array(self._sync(self._async_group.require_array(name, shape=shape, **kwargs)))

    def empty(self, *, name: str, shape: tuple[int, ...], **kwargs: Any) -> Array:
        """Create an empty array with the specified shape in this Group. The contents will be filled with
        the array's fill value or zeros if no fill value is provided.

        Parameters
        ----------
        name : str
            Name of the array.
        shape : int or tuple of int
            Shape of the empty array.
        **kwargs
            Keyword arguments passed to [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 Array(self._sync(self._async_group.empty(name=name, shape=shape, **kwargs)))

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

        Parameters
        ----------
        name : str
            Name of the array.
        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 Array(self._sync(self._async_group.zeros(name=name, shape=shape, **kwargs)))

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

        Parameters
        ----------
        name : str
            Name of the array.
        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 Array(self._sync(self._async_group.ones(name=name, shape=shape, **kwargs)))

    def full(
        self, *, name: str, shape: tuple[int, ...], fill_value: Any | None, **kwargs: Any
    ) -> Array:
        """Create an array, with "fill_value" being used as the default value for uninitialized portions of the array.

        Parameters
        ----------
        name : str
            Name of the array.
        shape : int or tuple of int
            Shape of the empty array.
        fill_value : scalar
            Value to fill the array with.
        **kwargs
            Keyword arguments passed to [zarr.api.asynchronous.create][].

        Returns
        -------
        Array
            The new array.
        """
        return Array(
            self._sync(
                self._async_group.full(name=name, shape=shape, fill_value=fill_value, **kwargs)
            )
        )

    def empty_like(self, *, name: str, data: async_api.ArrayLike, **kwargs: Any) -> Array:
        """Create an empty sub-array like `data`. The contents will be filled
        with the array's fill value or zeros if no fill value is provided.

        Parameters
        ----------
        name : str
            Name of the array.
        data : array-like
            The array to create an empty array like.
        **kwargs
            Keyword arguments passed to [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.
        """
        return Array(self._sync(self._async_group.empty_like(name=name, data=data, **kwargs)))

    def zeros_like(self, *, name: str, data: async_api.ArrayLike, **kwargs: Any) -> Array:
        """Create a sub-array of zeros like `data`.

        Parameters
        ----------
        name : str
            Name of the array.
        data : array-like
            The array to create the new array like.
        **kwargs
            Keyword arguments passed to [zarr.api.asynchronous.create][].

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

        return Array(self._sync(self._async_group.zeros_like(name=name, data=data, **kwargs)))

    def ones_like(self, *, name: str, data: async_api.ArrayLike, **kwargs: Any) -> Array:
        """Create a sub-array of ones like `data`.

        Parameters
        ----------
        name : str
            Name of the array.
        data : array-like
            The array to create the new array like.
        **kwargs
            Keyword arguments passed to [zarr.api.asynchronous.create][].

        Returns
        -------
        Array
            The new array.
        """
        return Array(self._sync(self._async_group.ones_like(name=name, data=data, **kwargs)))

    def full_like(self, *, name: str, data: async_api.ArrayLike, **kwargs: Any) -> Array:
        """Create a sub-array like `data` filled with the `fill_value` of `data` .

        Parameters
        ----------
        name : str
            Name of the array.
        data : array-like
            The array to create the new array like.
        **kwargs
            Keyword arguments passed to [zarr.api.asynchronous.create][].

        Returns
        -------
        Array
            The new array.
        """
        return Array(self._sync(self._async_group.full_like(name=name, data=data, **kwargs)))

    def move(self, source: str, dest: str) -> None:
        """Move a sub-group or sub-array from one path to another.

        Notes
        -----
        Not implemented
        """
        return self._sync(self._async_group.move(source, dest))

    @deprecated("Use Group.create_array instead.", category=ZarrDeprecationWarning)
    def array(
        self,
        name: str,
        *,
        shape: ShapeLike,
        dtype: npt.DTypeLike,
        chunks: tuple[int, ...] | Literal["auto"] = "auto",
        shards: tuple[int, ...] | Literal["auto"] | None = None,
        filters: FiltersLike = "auto",
        compressors: CompressorsLike = "auto",
        compressor: CompressorLike = None,
        serializer: SerializerLike = "auto",
        fill_value: Any | None = DEFAULT_FILL_VALUE,
        order: MemoryOrder | None = None,
        attributes: dict[str, JSON] | None = None,
        chunk_key_encoding: ChunkKeyEncodingLike | None = None,
        dimension_names: DimensionNames = None,
        storage_options: dict[str, Any] | None = None,
        overwrite: bool = False,
        config: ArrayConfigLike | None = None,
        data: npt.ArrayLike | None = None,
    ) -> Array:
        """Create an array within this group.

        !!! warning "Deprecated"
            `Group.array()` is deprecated since v3.0.0 and will be removed in a future release.
            Use `Group.create_array` instead.

        This method lightly wraps [zarr.core.array.create_array][].

        Parameters
        ----------
        name : str
            The name of the array relative to the group. If ``path`` is ``None``, the array will be located
            at the root of the store.
        shape : tuple[int, ...]
            Shape of the array.
        dtype : npt.DTypeLike
            Data type of the array.
        chunks : tuple[int, ...], optional
            Chunk shape of the array.
            If not specified, default are guessed based on the shape and 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 [`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
            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
            [`zarr.dtype.VariableLengthUTF8`][] or [`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 [`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.
            in [`zarr.config`][zarr.config].
            Use ``None`` to omit the default compressor.
        compressor : Codec, optional
            Deprecated in favor of ``compressors``.
        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 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].
        attributes : dict, optional
            Attributes for the 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": "."}}``.
        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.
        config : ArrayConfig or ArrayConfigLike, optional
            Runtime configuration for the array.
        data : array_like
            The data to fill the array with.

        Returns
        -------
        AsyncArray
        """
        compressors = _parse_deprecated_compressor(compressor, compressors)
        return Array(
            self._sync(
                self._async_group.create_dataset(
                    name=name,
                    shape=shape,
                    dtype=dtype,
                    chunks=chunks,
                    shards=shards,
                    fill_value=fill_value,
                    attributes=attributes,
                    chunk_key_encoding=chunk_key_encoding,
                    compressors=compressors,
                    serializer=serializer,
                    dimension_names=dimension_names,
                    order=order,
                    filters=filters,
                    overwrite=overwrite,
                    storage_options=storage_options,
                    config=config,
                    data=data,
                )
            )
        )

attrs property

attrs: Attributes

Attributes of this Group

basename property

basename: str

Final component of name.

info property

info: Any

Return the statically known information for a group.

Returns:

• GroupInfo –

Related

zarr.Group.info_complete All information about a group, including dynamic information like the children members.

metadata property

metadata: GroupMetadata

Group metadata.

name property

name: str

Group name following h5py convention.

path property

path: str

Storage path.

store_path property

store_path: StorePath

Path-like interface for the Store.

__contains__

__contains__(member: str) -> bool

Test for group membership.

Examples:

>>> import zarr
>>> g1 = zarr.group()
>>> g2 = g1.create_group('foo')
>>> d1 = g1.create_array('bar', shape=(10,), chunks=(10,))
>>> 'foo' in g1
True
>>> 'bar' in g1
True
>>> 'baz' in g1
False

Source code in zarr/core/group.py

def __contains__(self, member: str) -> bool:
    """Test for group membership.

    Examples
    --------
    >>> import zarr
    >>> g1 = zarr.group()
    >>> g2 = g1.create_group('foo')
    >>> d1 = g1.create_array('bar', shape=(10,), chunks=(10,))
    >>> 'foo' in g1
    True
    >>> 'bar' in g1
    True
    >>> 'baz' in g1
    False

    """
    return self._sync(self._async_group.contains(member))

__delitem__

__delitem__(key: str) -> None

Delete a group member.

Parameters:

• key (str) –

  Group member name.

Examples:

>>> import zarr
>>> group = Group.from_store(zarr.storage.MemoryStore()
>>> group.create_array(name="subarray", shape=(10,), chunks=(10,))
>>> del group["subarray"]
>>> "subarray" in group
False

Source code in zarr/core/group.py

def __delitem__(self, key: str) -> None:
    """Delete a group member.

    Parameters
    ----------
    key : str
        Group member name.

    Examples
    --------
    >>> import zarr
    >>> group = Group.from_store(zarr.storage.MemoryStore()
    >>> group.create_array(name="subarray", shape=(10,), chunks=(10,))
    >>> del group["subarray"]
    >>> "subarray" in group
    False
    """
    self._sync(self._async_group.delitem(key))

__getitem__

__getitem__(path: str) -> Array | Group

Obtain a group member.

Parameters:

• path (str) –

  Group member name.

Returns:

• Array | Group –

  Group member (Array or Group) at the specified key

Examples:

>>> import zarr
>>> group = Group.from_store(zarr.storage.MemoryStore()
>>> group.create_array(name="subarray", shape=(10,), chunks=(10,))
>>> group.create_group(name="subgroup").create_array(name="subarray", shape=(10,), chunks=(10,))
>>> group["subarray"]
<Array memory://132270269438272/subarray shape=(10,) dtype=float64>
>>> group["subgroup"]
<Group memory://132270269438272/subgroup>
>>> group["subgroup"]["subarray"]
<Array memory://132270269438272/subgroup/subarray shape=(10,) dtype=float64>

Source code in zarr/core/group.py

def __getitem__(self, path: str) -> Array | Group:
    """Obtain a group member.

    Parameters
    ----------
    path : str
        Group member name.

    Returns
    -------
    Array | Group
        Group member (Array or Group) at the specified key

    Examples
    --------
    >>> import zarr
    >>> group = Group.from_store(zarr.storage.MemoryStore()
    >>> group.create_array(name="subarray", shape=(10,), chunks=(10,))
    >>> group.create_group(name="subgroup").create_array(name="subarray", shape=(10,), chunks=(10,))
    >>> group["subarray"]
    <Array memory://132270269438272/subarray shape=(10,) dtype=float64>
    >>> group["subgroup"]
    <Group memory://132270269438272/subgroup>
    >>> group["subgroup"]["subarray"]
    <Array memory://132270269438272/subgroup/subarray shape=(10,) dtype=float64>

    """
    obj = self._sync(self._async_group.getitem(path))
    if isinstance(obj, AsyncArray):
        return Array(obj)
    else:
        return Group(obj)

__iter__

__iter__() -> Iterator[str]

Return an iterator over group member names.

Examples:

>>> import zarr
>>> g1 = zarr.group()
>>> g2 = g1.create_group('foo')
>>> g3 = g1.create_group('bar')
>>> d1 = g1.create_array('baz', shape=(10,), chunks=(10,))
>>> d2 = g1.create_array('quux', shape=(10,), chunks=(10,))
>>> for name in g1:
...     print(name)
baz
bar
foo
quux

Source code in zarr/core/group.py

def __iter__(self) -> Iterator[str]:
    """Return an iterator over group member names.
    Examples
    --------
    >>> import zarr
    >>> g1 = zarr.group()
    >>> g2 = g1.create_group('foo')
    >>> g3 = g1.create_group('bar')
    >>> d1 = g1.create_array('baz', shape=(10,), chunks=(10,))
    >>> d2 = g1.create_array('quux', shape=(10,), chunks=(10,))
    >>> for name in g1:
    ...     print(name)
    baz
    bar
    foo
    quux
    """
    yield from self.keys()

__len__

__len__() -> int

Number of members.

Source code in zarr/core/group.py

def __len__(self) -> int:
    """Number of members."""
    return self.nmembers()

__setitem__

__setitem__(key: str, value: Any) -> None

Fastpath for creating a new array.

New arrays will be created using default settings for the array type. If you need to create an array with custom settings, use the create_array method.

Parameters:

• key (str) –

  Array name.

• value (Any) –

  Array data.

Examples:

>>> import zarr
>>> group = zarr.group()
>>> group["foo"] = zarr.zeros((10,))
>>> group["foo"]
<Array memory://132270269438272/foo shape=(10,) dtype=float64>

Source code in zarr/core/group.py

def __setitem__(self, key: str, value: Any) -> None:
    """Fastpath for creating a new array.

    New arrays will be created using default settings for the array type.
    If you need to create an array with custom settings, use the `create_array` method.

    Parameters
    ----------
    key : str
        Array name.
    value : Any
        Array data.

    Examples
    --------
    >>> import zarr
    >>> group = zarr.group()
    >>> group["foo"] = zarr.zeros((10,))
    >>> group["foo"]
    <Array memory://132270269438272/foo shape=(10,) dtype=float64>
    """
    self._sync(self._async_group.setitem(key, value))

array

array(
    name: str,
    *,
    shape: ShapeLike,
    dtype: DTypeLike,
    chunks: tuple[int, ...] | Literal["auto"] = "auto",
    shards: tuple[int, ...] | Literal["auto"] | None = None,
    filters: FiltersLike = "auto",
    compressors: CompressorsLike = "auto",
    compressor: CompressorLike = None,
    serializer: SerializerLike = "auto",
    fill_value: Any | None = DEFAULT_FILL_VALUE,
    order: MemoryOrder | None = None,
    attributes: dict[str, JSON] | None = None,
    chunk_key_encoding: ChunkKeyEncodingLike | None = None,
    dimension_names: DimensionNames = None,
    storage_options: dict[str, Any] | None = None,
    overwrite: bool = False,
    config: ArrayConfigLike | None = None,
    data: ArrayLike | None = None,
) -> Array

Create an array within this group.

Deprecated

Group.array() is deprecated since v3.0.0 and will be removed in a future release. Use Group.create_array instead.

This method lightly wraps zarr.core.array.create_array.

Parameters:

• name (str) –

  The name of the array relative to the group. If path is None, the array will be located at the root of the store.

• shape (tuple[int, ...]) –

  Shape of the array.

• dtype (DTypeLike) –

  Data type of the array.

• chunks (tuple[int, ...], default: 'auto' ) –

  Chunk shape of the array. If not specified, default are guessed based on the shape and dtype.

• 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 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 zarr.dtype.VariableLengthUTF8 or 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], 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 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 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. in zarr.config. Use None to omit the default compressor.

• compressor (Codec, default: None ) –

  Deprecated in favor of compressors.

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

• attributes (dict, default: None ) –

  Attributes for the array.

• 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": "."}}.

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

• config (ArrayConfig or ArrayConfigLike, default: None ) –

  Runtime configuration for the array.

• data (array_like, default: None ) –

  The data to fill the array with.

Returns:

• AsyncArray –

Source code in zarr/core/group.py

@deprecated("Use Group.create_array instead.", category=ZarrDeprecationWarning)
def array(
    self,
    name: str,
    *,
    shape: ShapeLike,
    dtype: npt.DTypeLike,
    chunks: tuple[int, ...] | Literal["auto"] = "auto",
    shards: tuple[int, ...] | Literal["auto"] | None = None,
    filters: FiltersLike = "auto",
    compressors: CompressorsLike = "auto",
    compressor: CompressorLike = None,
    serializer: SerializerLike = "auto",
    fill_value: Any | None = DEFAULT_FILL_VALUE,
    order: MemoryOrder | None = None,
    attributes: dict[str, JSON] | None = None,
    chunk_key_encoding: ChunkKeyEncodingLike | None = None,
    dimension_names: DimensionNames = None,
    storage_options: dict[str, Any] | None = None,
    overwrite: bool = False,
    config: ArrayConfigLike | None = None,
    data: npt.ArrayLike | None = None,
) -> Array:
    """Create an array within this group.

    !!! warning "Deprecated"
        `Group.array()` is deprecated since v3.0.0 and will be removed in a future release.
        Use `Group.create_array` instead.

    This method lightly wraps [zarr.core.array.create_array][].

    Parameters
    ----------
    name : str
        The name of the array relative to the group. If ``path`` is ``None``, the array will be located
        at the root of the store.
    shape : tuple[int, ...]
        Shape of the array.
    dtype : npt.DTypeLike
        Data type of the array.
    chunks : tuple[int, ...], optional
        Chunk shape of the array.
        If not specified, default are guessed based on the shape and 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 [`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
        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
        [`zarr.dtype.VariableLengthUTF8`][] or [`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 [`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.
        in [`zarr.config`][zarr.config].
        Use ``None`` to omit the default compressor.
    compressor : Codec, optional
        Deprecated in favor of ``compressors``.
    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 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].
    attributes : dict, optional
        Attributes for the 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": "."}}``.
    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.
    config : ArrayConfig or ArrayConfigLike, optional
        Runtime configuration for the array.
    data : array_like
        The data to fill the array with.

    Returns
    -------
    AsyncArray
    """
    compressors = _parse_deprecated_compressor(compressor, compressors)
    return Array(
        self._sync(
            self._async_group.create_dataset(
                name=name,
                shape=shape,
                dtype=dtype,
                chunks=chunks,
                shards=shards,
                fill_value=fill_value,
                attributes=attributes,
                chunk_key_encoding=chunk_key_encoding,
                compressors=compressors,
                serializer=serializer,
                dimension_names=dimension_names,
                order=order,
                filters=filters,
                overwrite=overwrite,
                storage_options=storage_options,
                config=config,
                data=data,
            )
        )
    )

array_keys

array_keys() -> Generator[str, None]

Return an iterator over group member names.

Examples:

>>> import zarr
>>> group = zarr.group()
>>> group.create_array("subarray", shape=(10,), chunks=(10,))
>>> for name in group.array_keys():
...     print(name)
subarray

Source code in zarr/core/group.py

def array_keys(self) -> Generator[str, None]:
    """Return an iterator over group member names.

    Examples
    --------
    >>> import zarr
    >>> group = zarr.group()
    >>> group.create_array("subarray", shape=(10,), chunks=(10,))
    >>> for name in group.array_keys():
    ...     print(name)
    subarray
    """

    for name, _ in self.arrays():
        yield name

array_values

array_values() -> Generator[Array, None]

Return an iterator over group members.

Examples:

>>> import zarr
>>> group = zarr.group()
>>> group.create_array("subarray", shape=(10,), chunks=(10,))
>>> for subarray in group.array_values():
...     print(subarray)
<Array memory://140198565357056/subarray shape=(10,) dtype=float64>

Source code in zarr/core/group.py

def array_values(self) -> Generator[Array, None]:
    """Return an iterator over group members.

    Examples
    --------
    >>> import zarr
    >>> group = zarr.group()
    >>> group.create_array("subarray", shape=(10,), chunks=(10,))
    >>> for subarray in group.array_values():
    ...     print(subarray)
    <Array memory://140198565357056/subarray shape=(10,) dtype=float64>
    """
    for _, array in self.arrays():
        yield array

arrays

arrays() -> Generator[tuple[str, Array], None]

Return the sub-arrays of this group as a generator of (name, array) pairs

Examples:

>>> import zarr
>>> group = zarr.group()
>>> group.create_array("subarray", shape=(10,), chunks=(10,))
>>> for name, subarray in group.arrays():
...     print(name, subarray)
subarray <Array memory://140198565357056/subarray shape=(10,) dtype=float64>

Source code in zarr/core/group.py

def arrays(self) -> Generator[tuple[str, Array], None]:
    """Return the sub-arrays of this group as a generator of (name, array) pairs

    Examples
    --------
    >>> import zarr
    >>> group = zarr.group()
    >>> group.create_array("subarray", shape=(10,), chunks=(10,))
    >>> for name, subarray in group.arrays():
    ...     print(name, subarray)
    subarray <Array memory://140198565357056/subarray shape=(10,) dtype=float64>
    """
    for name, async_array in self._sync_iter(self._async_group.arrays()):
        yield name, Array(async_array)

create

create(
    name: str,
    *,
    shape: ShapeLike | None = None,
    dtype: ZDTypeLike | None = None,
    data: ndarray[Any, dtype[Any]] | None = None,
    chunks: tuple[int, ...] | Literal["auto"] = "auto",
    shards: ShardsLike | None = None,
    filters: FiltersLike = "auto",
    compressors: CompressorsLike = "auto",
    compressor: CompressorLike = "auto",
    serializer: SerializerLike = "auto",
    fill_value: Any | None = DEFAULT_FILL_VALUE,
    order: MemoryOrder | None = None,
    attributes: dict[str, JSON] | None = None,
    chunk_key_encoding: ChunkKeyEncodingLike | None = None,
    dimension_names: DimensionNames = None,
    storage_options: dict[str, Any] | None = None,
    overwrite: bool = False,
    config: ArrayConfigLike | None = None,
    write_data: bool = True,
) -> Array

Create an array within this group.

This method lightly wraps zarr.core.array.create_array.

Parameters:

• name (str) –

  The name of the array relative to the group. If path 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 (DTypeLike | None, default: None ) –

  Data type of the array. Must be None if data is provided.

• data (Array-like data to use for initializing the array. If this parameter is provided, the, default: None ) –

  shape and dtype parameters must be None.

• chunks (tuple[int, ...], default: 'auto' ) –

  Chunk shape of the array. If not specified, default are guessed based on the shape and dtype.

• 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 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 zarr.dtype.VariableLengthUTF8 or 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], 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 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 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. in zarr.config. Use None to omit the default compressor.

• compressor (Codec, default: 'auto' ) –

  Deprecated in favor of compressors.

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

• attributes (dict, default: None ) –

  Attributes for the array.

• 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": "."}}.

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

• config (ArrayConfig or 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 –

Source code in zarr/core/group.py

def create(
    self,
    name: str,
    *,
    shape: ShapeLike | None = None,
    dtype: ZDTypeLike | None = None,
    data: np.ndarray[Any, np.dtype[Any]] | None = None,
    chunks: tuple[int, ...] | Literal["auto"] = "auto",
    shards: ShardsLike | None = None,
    filters: FiltersLike = "auto",
    compressors: CompressorsLike = "auto",
    compressor: CompressorLike = "auto",
    serializer: SerializerLike = "auto",
    fill_value: Any | None = DEFAULT_FILL_VALUE,
    order: MemoryOrder | None = None,
    attributes: dict[str, JSON] | None = None,
    chunk_key_encoding: ChunkKeyEncodingLike | None = None,
    dimension_names: DimensionNames = None,
    storage_options: dict[str, Any] | None = None,
    overwrite: bool = False,
    config: ArrayConfigLike | None = None,
    write_data: bool = True,
) -> Array:
    """Create an array within this group.

    This method lightly wraps [`zarr.core.array.create_array`][].

    Parameters
    ----------
    name : str
        The name of the array relative to the group. If ``path`` 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 : npt.DTypeLike | None
        Data type of the array. Must be ``None`` if ``data`` is provided.
    data : 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, ...], optional
        Chunk shape of the array.
        If not specified, default are guessed based on the shape and 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 [`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
        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
        [`zarr.dtype.VariableLengthUTF8`][] or [`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 [`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.
        in [`zarr.config`][].
        Use ``None`` to omit the default compressor.
    compressor : Codec, optional
        Deprecated in favor of ``compressors``.
    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`][].
    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 [`zarr.config`][].
    attributes : dict, optional
        Attributes for the 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": "."}}``.
    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.
    config : ArrayConfig or 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
    """
    return self.create_array(
        name,
        shape=shape,
        dtype=dtype,
        data=data,
        chunks=chunks,
        shards=shards,
        filters=filters,
        compressors=compressors,
        compressor=compressor,
        serializer=serializer,
        fill_value=fill_value,
        order=order,
        attributes=attributes,
        chunk_key_encoding=chunk_key_encoding,
        dimension_names=dimension_names,
        storage_options=storage_options,
        overwrite=overwrite,
        config=config,
        write_data=write_data,
    )

create_array

create_array(
    name: str,
    *,
    shape: ShapeLike | None = None,
    dtype: ZDTypeLike | None = None,
    data: ndarray[Any, dtype[Any]] | None = None,
    chunks: tuple[int, ...] | Literal["auto"] = "auto",
    shards: ShardsLike | None = None,
    filters: FiltersLike = "auto",
    compressors: CompressorsLike = "auto",
    compressor: CompressorLike = "auto",
    serializer: SerializerLike = "auto",
    fill_value: Any | None = DEFAULT_FILL_VALUE,
    order: MemoryOrder | None = None,
    attributes: dict[str, JSON] | None = None,
    chunk_key_encoding: ChunkKeyEncodingLike | None = None,
    dimension_names: DimensionNames = None,
    storage_options: dict[str, Any] | None = None,
    overwrite: bool = False,
    config: ArrayConfigLike | None = None,
    write_data: bool = True,
) -> Array

Create an array within this group.

This method lightly wraps zarr.core.array.create_array.

Parameters:

• name (str) –

  The name of the array relative to the group. If path 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 (DTypeLike | None, default: None ) –

  Data type of the array. Must be None if data is provided.

• data (Array-like data to use for initializing the array. If this parameter is provided, the, default: None ) –

  shape and dtype parameters must be None.

• chunks (tuple[int, ...], default: 'auto' ) –

  Chunk shape of the array. If not specified, default are guessed based on the shape and dtype.

• 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 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 zarr.dtype.VariableLengthUTF8 or 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], 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 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 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. in zarr.config. Use None to omit the default compressor.

• compressor (Codec, default: 'auto' ) –

  Deprecated in favor of compressors.

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

• attributes (dict, default: None ) –

  Attributes for the array.

• 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": "."}}.

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

• config (ArrayConfig or 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 –

Source code in zarr/core/group.py

def create_array(
    self,
    name: str,
    *,
    shape: ShapeLike | None = None,
    dtype: ZDTypeLike | None = None,
    data: np.ndarray[Any, np.dtype[Any]] | None = None,
    chunks: tuple[int, ...] | Literal["auto"] = "auto",
    shards: ShardsLike | None = None,
    filters: FiltersLike = "auto",
    compressors: CompressorsLike = "auto",
    compressor: CompressorLike = "auto",
    serializer: SerializerLike = "auto",
    fill_value: Any | None = DEFAULT_FILL_VALUE,
    order: MemoryOrder | None = None,
    attributes: dict[str, JSON] | None = None,
    chunk_key_encoding: ChunkKeyEncodingLike | None = None,
    dimension_names: DimensionNames = None,
    storage_options: dict[str, Any] | None = None,
    overwrite: bool = False,
    config: ArrayConfigLike | None = None,
    write_data: bool = True,
) -> Array:
    """Create an array within this group.

    This method lightly wraps [zarr.core.array.create_array][].

    Parameters
    ----------
    name : str
        The name of the array relative to the group. If ``path`` 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 : npt.DTypeLike | None
        Data type of the array. Must be ``None`` if ``data`` is provided.
    data : 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, ...], optional
        Chunk shape of the array.
        If not specified, default are guessed based on the shape and 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 [`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
        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
        [`zarr.dtype.VariableLengthUTF8`][] or [`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 [`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.
        in [`zarr.config`][zarr.config].
        Use ``None`` to omit the default compressor.
    compressor : Codec, optional
        Deprecated in favor of ``compressors``.
    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 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].
    attributes : dict, optional
        Attributes for the 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": "."}}``.
    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.
    config : ArrayConfig or 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
    """
    compressors = _parse_deprecated_compressor(
        compressor, compressors, zarr_format=self.metadata.zarr_format
    )
    return Array(
        self._sync(
            self._async_group.create_array(
                name=name,
                shape=shape,
                dtype=dtype,
                data=data,
                chunks=chunks,
                shards=shards,
                fill_value=fill_value,
                attributes=attributes,
                chunk_key_encoding=chunk_key_encoding,
                compressors=compressors,
                serializer=serializer,
                dimension_names=dimension_names,
                order=order,
                filters=filters,
                overwrite=overwrite,
                storage_options=storage_options,
                config=config,
                write_data=write_data,
            )
        )
    )

create_dataset

create_dataset(name: str, **kwargs: Any) -> Array

Create an array.

Deprecated

Group.create_dataset() is deprecated since v3.0.0 and will be removed in v3.1.0. Use Group.create_array instead.

Arrays are known as "datasets" in HDF5 terminology. For compatibility with h5py, Zarr groups also implement the zarr.Group.require_dataset method.

Parameters:

• name (str) –

  Array name.

• **kwargs (dict, default: {} ) –

  Additional arguments passed to zarr.Group.create_array

Returns:

• a ( Array ) –

Source code in zarr/core/group.py

@deprecated("Use Group.create_array instead.", category=ZarrDeprecationWarning)
def create_dataset(self, name: str, **kwargs: Any) -> Array:
    """Create an array.

    !!! warning "Deprecated"
        `Group.create_dataset()` is deprecated since v3.0.0 and will be removed in v3.1.0.
        Use `Group.create_array` instead.


    Arrays are known as "datasets" in HDF5 terminology. For compatibility
    with h5py, Zarr groups also implement the [zarr.Group.require_dataset][] method.

    Parameters
    ----------
    name : str
        Array name.
    **kwargs : dict
        Additional arguments passed to [zarr.Group.create_array][]

    Returns
    -------
    a : Array
    """
    return Array(self._sync(self._async_group.create_dataset(name, **kwargs)))

create_group

create_group(name: str, **kwargs: Any) -> Group

Create a sub-group.

Parameters:

• name (str) –

  Name of the new subgroup.

Returns:

• Group –

Examples:

>>> import zarr
>>> group = zarr.group()
>>> subgroup = group.create_group("subgroup")
>>> subgroup
<Group memory://132270269438272/subgroup>

Source code in zarr/core/group.py

def create_group(self, name: str, **kwargs: Any) -> Group:
    """Create a sub-group.

    Parameters
    ----------
    name : str
        Name of the new subgroup.

    Returns
    -------
    Group

    Examples
    --------
    >>> import zarr
    >>> group = zarr.group()
    >>> subgroup = group.create_group("subgroup")
    >>> subgroup
    <Group memory://132270269438272/subgroup>
    """
    return Group(self._sync(self._async_group.create_group(name, **kwargs)))

create_hierarchy

create_hierarchy(
    nodes: dict[
        str,
        ArrayV2Metadata | ArrayV3Metadata | GroupMetadata,
    ],
    *,
    overwrite: bool = False,
) -> Iterator[tuple[str, Group | Array]]

Create a hierarchy of arrays or groups rooted at this group.

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

Explicitly specifying a root group, e.g. with nodes = {'': GroupMetadata()} is an error because this group instance is the root group.

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:

• 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 path of the group. The values are instances of GroupMetadata or ArrayMetadata. Note that all values must have the same zarr_format as the parent group -- it is an error to mix zarr versions in the same hierarchy.

  Leading "/" characters from keys will be removed.

• overwrite (bool, default: False ) –

  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, Array | Group]. –

Examples:

>>> import zarr
>>> from zarr.core.group import GroupMetadata
>>> root = zarr.create_group(store={})
>>> for key, val in root.create_hierarchy({'a/b/c': GroupMetadata()}):
...   print(key, val)
...
<AsyncGroup memory://123209880766144/a>
<AsyncGroup memory://123209880766144/a/b/c>
<AsyncGroup memory://123209880766144/a/b>

Source code in zarr/core/group.py

def create_hierarchy(
    self,
    nodes: dict[str, ArrayV2Metadata | ArrayV3Metadata | GroupMetadata],
    *,
    overwrite: bool = False,
) -> Iterator[tuple[str, Group | Array]]:
    """
    Create a hierarchy of arrays or groups rooted at this group.

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

    Explicitly specifying a root group, e.g. with ``nodes = {'': GroupMetadata()}`` is an error
    because this group instance is the root group.

    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
    ----------
    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 path of the group. The values are instances of ``GroupMetadata`` or ``ArrayMetadata``. Note that
        all values must have the same ``zarr_format`` as the parent group -- 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, Array | Group].

    Examples
    --------
    >>> import zarr
    >>> from zarr.core.group import GroupMetadata
    >>> root = zarr.create_group(store={})
    >>> for key, val in root.create_hierarchy({'a/b/c': GroupMetadata()}):
    ...   print(key, val)
    ...
    <AsyncGroup memory://123209880766144/a>
    <AsyncGroup memory://123209880766144/a/b/c>
    <AsyncGroup memory://123209880766144/a/b>
    """
    for key, node in self._sync_iter(
        self._async_group.create_hierarchy(nodes, overwrite=overwrite)
    ):
        yield (key, _parse_async_node(node))

empty

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

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

Parameters:

• name (str) –

  Name of the array.

• shape (int or tuple of int) –

  Shape of the empty array.

• **kwargs (Any, default: {} ) –

  Keyword arguments passed to 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.

Source code in zarr/core/group.py

def empty(self, *, name: str, shape: tuple[int, ...], **kwargs: Any) -> Array:
    """Create an empty array with the specified shape in this Group. The contents will be filled with
    the array's fill value or zeros if no fill value is provided.

    Parameters
    ----------
    name : str
        Name of the array.
    shape : int or tuple of int
        Shape of the empty array.
    **kwargs
        Keyword arguments passed to [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 Array(self._sync(self._async_group.empty(name=name, shape=shape, **kwargs)))

empty_like

empty_like(
    *, name: str, data: ArrayLike, **kwargs: Any
) -> Array

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

Parameters:

• name (str) –

  Name of the array.

• data (array - like) –

  The array to create an empty array like.

• **kwargs (Any, default: {} ) –

  Keyword arguments passed to 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.

Source code in zarr/core/group.py

def empty_like(self, *, name: str, data: async_api.ArrayLike, **kwargs: Any) -> Array:
    """Create an empty sub-array like `data`. The contents will be filled
    with the array's fill value or zeros if no fill value is provided.

    Parameters
    ----------
    name : str
        Name of the array.
    data : array-like
        The array to create an empty array like.
    **kwargs
        Keyword arguments passed to [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.
    """
    return Array(self._sync(self._async_group.empty_like(name=name, data=data, **kwargs)))

from_store classmethod

from_store(
    store: StoreLike,
    *,
    attributes: dict[str, Any] | None = None,
    zarr_format: ZarrFormat = 3,
    overwrite: bool = False,
) -> Group

Instantiate a group from an initialized store.

Parameters:

• store (StoreLike) –

  StoreLike containing the Group.

• attributes (dict, default: None ) –

  A dictionary of JSON-serializable values with user-defined attributes.

• zarr_format ((2, 3), default: 2 ) –

  Zarr storage format version.

• overwrite (bool, default: False ) –

  If True, do not raise an error if the group already exists.

Returns:

• Group –

  Group instantiated from the store.

Raises:

• (ContainsArrayError, ContainsGroupError, ContainsArrayAndGroupError) –

Source code in zarr/core/group.py

@classmethod
def from_store(
    cls,
    store: StoreLike,
    *,
    attributes: dict[str, Any] | None = None,
    zarr_format: ZarrFormat = 3,
    overwrite: bool = False,
) -> Group:
    """Instantiate a group from an initialized store.

    Parameters
    ----------
    store : StoreLike
        StoreLike containing the Group.
    attributes : dict, optional
        A dictionary of JSON-serializable values with user-defined attributes.
    zarr_format : {2, 3}, optional
        Zarr storage format version.
    overwrite : bool, optional
        If True, do not raise an error if the group already exists.

    Returns
    -------
    Group
        Group instantiated from the store.

    Raises
    ------
    ContainsArrayError, ContainsGroupError, ContainsArrayAndGroupError
    """
    attributes = attributes or {}
    obj = sync(
        AsyncGroup.from_store(
            store,
            attributes=attributes,
            overwrite=overwrite,
            zarr_format=zarr_format,
        ),
    )

    return cls(obj)

full

full(
    *,
    name: str,
    shape: tuple[int, ...],
    fill_value: Any | None,
    **kwargs: Any,
) -> Array

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

Parameters:

• name (str) –

  Name of the array.

• shape (int or tuple of int) –

  Shape of the empty array.

• fill_value (scalar) –

  Value to fill the array with.

• **kwargs (Any, default: {} ) –

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

Returns:

• Array –

  The new array.

Source code in zarr/core/group.py

def full(
    self, *, name: str, shape: tuple[int, ...], fill_value: Any | None, **kwargs: Any
) -> Array:
    """Create an array, with "fill_value" being used as the default value for uninitialized portions of the array.

    Parameters
    ----------
    name : str
        Name of the array.
    shape : int or tuple of int
        Shape of the empty array.
    fill_value : scalar
        Value to fill the array with.
    **kwargs
        Keyword arguments passed to [zarr.api.asynchronous.create][].

    Returns
    -------
    Array
        The new array.
    """
    return Array(
        self._sync(
            self._async_group.full(name=name, shape=shape, fill_value=fill_value, **kwargs)
        )
    )

full_like

full_like(
    *, name: str, data: ArrayLike, **kwargs: Any
) -> Array

Create a sub-array like data filled with the fill_value of data .

Parameters:

• name (str) –

  Name of the array.

• data (array - like) –

  The array to create the new array like.

• **kwargs (Any, default: {} ) –

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

Returns:

• Array –

  The new array.

Source code in zarr/core/group.py

def full_like(self, *, name: str, data: async_api.ArrayLike, **kwargs: Any) -> Array:
    """Create a sub-array like `data` filled with the `fill_value` of `data` .

    Parameters
    ----------
    name : str
        Name of the array.
    data : array-like
        The array to create the new array like.
    **kwargs
        Keyword arguments passed to [zarr.api.asynchronous.create][].

    Returns
    -------
    Array
        The new array.
    """
    return Array(self._sync(self._async_group.full_like(name=name, data=data, **kwargs)))

get

get(
    path: str, default: DefaultT | None = None
) -> Array | Group | DefaultT | None

Obtain a group member, returning default if not found.

Parameters:

• path (str) –

  Group member name.

• default (object, default: None ) –

  Default value to return if key is not found (default: None).

Returns:

• object –

  Group member (Array or Group) or default if not found.

Examples:

>>> import zarr
>>> group = Group.from_store(zarr.storage.MemoryStore()
>>> group.create_array(name="subarray", shape=(10,), chunks=(10,))
>>> group.create_group(name="subgroup")
>>> group.get("subarray")
<Array memory://132270269438272/subarray shape=(10,) dtype=float64>
>>> group.get("subgroup")
<Group memory://132270269438272/subgroup>
>>> group.get("nonexistent", None)

Source code in zarr/core/group.py

def get(self, path: str, default: DefaultT | None = None) -> Array | Group | DefaultT | None:
    """Obtain a group member, returning default if not found.

    Parameters
    ----------
    path : str
        Group member name.
    default : object
        Default value to return if key is not found (default: None).

    Returns
    -------
    object
        Group member (Array or Group) or default if not found.

    Examples
    --------
    >>> import zarr
    >>> group = Group.from_store(zarr.storage.MemoryStore()
    >>> group.create_array(name="subarray", shape=(10,), chunks=(10,))
    >>> group.create_group(name="subgroup")
    >>> group.get("subarray")
    <Array memory://132270269438272/subarray shape=(10,) dtype=float64>
    >>> group.get("subgroup")
    <Group memory://132270269438272/subgroup>
    >>> group.get("nonexistent", None)

    """
    try:
        return self[path]
    except KeyError:
        return default

group_keys

group_keys() -> Generator[str, None]

Return an iterator over group member names.

Examples:

>>> import zarr
>>> group = zarr.group()
>>> group.create_group("subgroup")
>>> for name in group.group_keys():
...     print(name)
subgroup

Source code in zarr/core/group.py

def group_keys(self) -> Generator[str, None]:
    """Return an iterator over group member names.

    Examples
    --------
    >>> import zarr
    >>> group = zarr.group()
    >>> group.create_group("subgroup")
    >>> for name in group.group_keys():
    ...     print(name)
    subgroup
    """
    for name, _ in self.groups():
        yield name

group_values

group_values() -> Generator[Group, None]

Return an iterator over group members.

Examples:

>>> import zarr
>>> group = zarr.group()
>>> group.create_group("subgroup")
>>> for subgroup in group.group_values():
...     print(subgroup)
<Group memory://132270269438272/subgroup>

Source code in zarr/core/group.py

def group_values(self) -> Generator[Group, None]:
    """Return an iterator over group members.

    Examples
    --------
    >>> import zarr
    >>> group = zarr.group()
    >>> group.create_group("subgroup")
    >>> for subgroup in group.group_values():
    ...     print(subgroup)
    <Group memory://132270269438272/subgroup>
    """
    for _, group in self.groups():
        yield group

groups

groups() -> Generator[tuple[str, Group], None]

Return the sub-groups of this group as a generator of (name, group) pairs.

Examples:

>>> import zarr
>>> group = zarr.group()
>>> group.create_group("subgroup")
>>> for name, subgroup in group.groups():
...     print(name, subgroup)
subgroup <Group memory://132270269438272/subgroup>

Source code in zarr/core/group.py

def groups(self) -> Generator[tuple[str, Group], None]:
    """Return the sub-groups of this group as a generator of (name, group) pairs.

    Examples
    --------
    >>> import zarr
    >>> group = zarr.group()
    >>> group.create_group("subgroup")
    >>> for name, subgroup in group.groups():
    ...     print(name, subgroup)
    subgroup <Group memory://132270269438272/subgroup>
    """
    for name, async_group in self._sync_iter(self._async_group.groups()):
        yield name, Group(async_group)

info_complete

info_complete() -> Any

Return information for a group.

If this group doesn't contain consolidated metadata then this will need to read from the backing Store.

Returns:

• GroupInfo –

Related

zarr.Group.info

Source code in zarr/core/group.py

def info_complete(self) -> Any:
    """
    Return information for a group.

    If this group doesn't contain consolidated metadata then
    this will need to read from the backing Store.

    Returns
    -------
    GroupInfo

    Related
    -------
    [zarr.Group.info][]
    """
    return self._sync(self._async_group.info_complete())

keys

keys() -> Generator[str, None]

Return an iterator over group member names.

Examples:

>>> import zarr
>>> g1 = zarr.group()
>>> g2 = g1.create_group('foo')
>>> g3 = g1.create_group('bar')
>>> d1 = g1.create_array('baz', shape=(10,), chunks=(10,))
>>> d2 = g1.create_array('quux', shape=(10,), chunks=(10,))
>>> for name in g1.keys():
...     print(name)
baz
bar
foo
quux

Source code in zarr/core/group.py

def keys(self) -> Generator[str, None]:
    """Return an iterator over group member names.

    Examples
    --------
    >>> import zarr
    >>> g1 = zarr.group()
    >>> g2 = g1.create_group('foo')
    >>> g3 = g1.create_group('bar')
    >>> d1 = g1.create_array('baz', shape=(10,), chunks=(10,))
    >>> d2 = g1.create_array('quux', shape=(10,), chunks=(10,))
    >>> for name in g1.keys():
    ...     print(name)
    baz
    bar
    foo
    quux
    """
    yield from self._sync_iter(self._async_group.keys())

members

members(
    max_depth: int | None = 0,
    *,
    use_consolidated_for_children: bool = True,
) -> tuple[tuple[str, Array | Group], ...]

Returns an AsyncGenerator over the arrays and groups contained in this group. This method requires that store_path.store supports directory listing.

The results are not guaranteed to be ordered.

Parameters:

• max_depth (int, default: 0 ) –

  The maximum number of levels of the hierarchy to include. By default, (max_depth=0) only immediate children are included. Set max_depth=None to include all nodes, and some positive integer to consider children within that many levels of the root Group.

• use_consolidated_for_children (bool, default: True ) –

  Whether to use the consolidated metadata of child groups loaded from the store. Note that this only affects groups loaded from the store. If the current Group already has consolidated metadata, it will always be used.

Returns:

• path ( tuple[str, Array | Group] ) –

  A string giving the path to the target, relative to the Group self.

• value ( AsyncArray or AsyncGroup ) –

  The AsyncArray or AsyncGroup that is a child of self.

Source code in zarr/core/group.py

def members(
    self, max_depth: int | None = 0, *, use_consolidated_for_children: bool = True
) -> tuple[tuple[str, Array | Group], ...]:
    """
    Returns an AsyncGenerator over the arrays and groups contained in this group.
    This method requires that `store_path.store` supports directory listing.

    The results are not guaranteed to be ordered.

    Parameters
    ----------
    max_depth : int, default 0
        The maximum number of levels of the hierarchy to include. By
        default, (``max_depth=0``) only immediate children are included. Set
        ``max_depth=None`` to include all nodes, and some positive integer
        to consider children within that many levels of the root Group.
    use_consolidated_for_children : bool, default True
        Whether to use the consolidated metadata of child groups loaded
        from the store. Note that this only affects groups loaded from the
        store. If the current Group already has consolidated metadata, it
        will always be used.

    Returns
    -------
    path:
        A string giving the path to the target, relative to the Group ``self``.
    value: AsyncArray or AsyncGroup
        The AsyncArray or AsyncGroup that is a child of ``self``.
    """
    _members = self._sync_iter(self._async_group.members(max_depth=max_depth))

    return tuple((kv[0], _parse_async_node(kv[1])) for kv in _members)

move

move(source: str, dest: str) -> None

Move a sub-group or sub-array from one path to another.

Notes

Not implemented

Source code in zarr/core/group.py

def move(self, source: str, dest: str) -> None:
    """Move a sub-group or sub-array from one path to another.

    Notes
    -----
    Not implemented
    """
    return self._sync(self._async_group.move(source, dest))

nmembers

nmembers(max_depth: int | None = 0) -> int

Count the number of members in this group.

Parameters:

• max_depth (int, default: 0 ) –

  The maximum number of levels of the hierarchy to include. By default, (max_depth=0) only immediate children are included. Set max_depth=None to include all nodes, and some positive integer to consider children within that many levels of the root Group.

Returns:

• count ( int ) –

Source code in zarr/core/group.py

def nmembers(self, max_depth: int | None = 0) -> int:
    """Count the number of members in this group.

    Parameters
    ----------
    max_depth : int, default 0
        The maximum number of levels of the hierarchy to include. By
        default, (``max_depth=0``) only immediate children are included. Set
        ``max_depth=None`` to include all nodes, and some positive integer
        to consider children within that many levels of the root Group.

    Returns
    -------
    count : int
    """

    return self._sync(self._async_group.nmembers(max_depth=max_depth))

ones

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

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

Parameters:

• name (str) –

  Name of the array.

• 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 zarr/core/group.py

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

    Parameters
    ----------
    name : str
        Name of the array.
    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 Array(self._sync(self._async_group.ones(name=name, shape=shape, **kwargs)))

ones_like

ones_like(
    *, name: str, data: ArrayLike, **kwargs: Any
) -> Array

Create a sub-array of ones like data.

Parameters:

• name (str) –

  Name of the array.

• data (array - like) –

  The array to create the new array like.

• **kwargs (Any, default: {} ) –

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

Returns:

• Array –

  The new array.

Source code in zarr/core/group.py

def ones_like(self, *, name: str, data: async_api.ArrayLike, **kwargs: Any) -> Array:
    """Create a sub-array of ones like `data`.

    Parameters
    ----------
    name : str
        Name of the array.
    data : array-like
        The array to create the new array like.
    **kwargs
        Keyword arguments passed to [zarr.api.asynchronous.create][].

    Returns
    -------
    Array
        The new array.
    """
    return Array(self._sync(self._async_group.ones_like(name=name, data=data, **kwargs)))

open classmethod

open(
    store: StoreLike, zarr_format: ZarrFormat | None = 3
) -> Group

Open a group from an initialized store.

Parameters:

• store (StoreLike) –

  Store containing the Group.

• zarr_format ((2, 3, None), default: 2 ) –

  Zarr storage format version.

Returns:

• Group –

  Group instantiated from the store.

Source code in zarr/core/group.py

@classmethod
def open(
    cls,
    store: StoreLike,
    zarr_format: ZarrFormat | None = 3,
) -> Group:
    """Open a group from an initialized store.

    Parameters
    ----------
    store : StoreLike
        Store containing the Group.
    zarr_format : {2, 3, None}, optional
        Zarr storage format version.

    Returns
    -------
    Group
        Group instantiated from the store.
    """
    obj = sync(AsyncGroup.open(store, zarr_format=zarr_format))
    return cls(obj)

require_array

require_array(
    name: str, *, shape: ShapeLike, **kwargs: Any
) -> Array

Obtain an array, creating if it doesn't exist.

Other kwargs are as per zarr.Group.create_array.

Parameters:

• name (str) –

  Array name.

• **kwargs (Any, default: {} ) –

  See zarr.Group.create_array.

Returns:

• a ( Array ) –

Source code in zarr/core/group.py

def require_array(self, name: str, *, shape: ShapeLike, **kwargs: Any) -> Array:
    """Obtain an array, creating if it doesn't exist.

    Other `kwargs` are as per [zarr.Group.create_array][].

    Parameters
    ----------
    name : str
        Array name.
    **kwargs :
        See [zarr.Group.create_array][].

    Returns
    -------
    a : Array
    """
    return Array(self._sync(self._async_group.require_array(name, shape=shape, **kwargs)))

require_dataset

require_dataset(
    name: str, *, shape: ShapeLike, **kwargs: Any
) -> Array

Obtain an array, creating if it doesn't exist.

Deprecated

Group.require_dataset() is deprecated since v3.0.0 and will be removed in v3.1.0. Use Group.require_array instead.

Arrays are known as "datasets" in HDF5 terminology. For compatibility with h5py, Zarr groups also implement the zarr.Group.create_dataset method.

Other kwargs are as per zarr.Group.create_dataset.

Parameters:

• name (str) –

  Array name.

• **kwargs (Any, default: {} ) –

  See zarr.Group.create_dataset.

Returns:

• a ( Array ) –

Source code in zarr/core/group.py

@deprecated("Use Group.require_array instead.", category=ZarrDeprecationWarning)
def require_dataset(self, name: str, *, shape: ShapeLike, **kwargs: Any) -> Array:
    """Obtain an array, creating if it doesn't exist.

    !!! warning "Deprecated"
        `Group.require_dataset()` is deprecated since v3.0.0 and will be removed in v3.1.0.
        Use `Group.require_array` instead.

    Arrays are known as "datasets" in HDF5 terminology. For compatibility
    with h5py, Zarr groups also implement the [zarr.Group.create_dataset][] method.

    Other `kwargs` are as per [zarr.Group.create_dataset][].

    Parameters
    ----------
    name : str
        Array name.
    **kwargs :
        See [zarr.Group.create_dataset][].

    Returns
    -------
    a : Array
    """
    return Array(self._sync(self._async_group.require_array(name, shape=shape, **kwargs)))

require_group

require_group(name: str, **kwargs: Any) -> Group

Obtain a sub-group, creating one if it doesn't exist.

Parameters:

• name (str) –

  Group name.

Returns:

• g ( Group ) –

Source code in zarr/core/group.py

def require_group(self, name: str, **kwargs: Any) -> Group:
    """Obtain a sub-group, creating one if it doesn't exist.

    Parameters
    ----------
    name : str
        Group name.

    Returns
    -------
    g : Group
    """
    return Group(self._sync(self._async_group.require_group(name, **kwargs)))

require_groups

require_groups(*names: str) -> tuple[Group, ...]

Convenience method to require multiple groups in a single call.

Parameters:

• *names (str, default: () ) –

  Group names.

Returns:

• groups ( tuple of Groups ) –

Source code in zarr/core/group.py

def require_groups(self, *names: str) -> tuple[Group, ...]:
    """Convenience method to require multiple groups in a single call.

    Parameters
    ----------
    *names : str
        Group names.

    Returns
    -------
    groups : tuple of Groups
    """
    return tuple(map(Group, self._sync(self._async_group.require_groups(*names))))

tree

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

Return a tree-like representation of a hierarchy.

This requires the optional rich dependency.

Parameters:

• expand (bool, default: None ) –

  This keyword is not yet supported. A NotImplementedError is raised if it's used.

• level (int, default: None ) –

  The maximum depth below this Group to display in the tree.

Returns:

• TreeRepr –

  A pretty-printable object displaying the hierarchy.

Source code in zarr/core/group.py

def tree(self, expand: bool | None = None, level: int | None = None) -> Any:
    """
    Return a tree-like representation of a hierarchy.

    This requires the optional ``rich`` dependency.

    Parameters
    ----------
    expand : bool, optional
        This keyword is not yet supported. A NotImplementedError is raised if
        it's used.
    level : int, optional
        The maximum depth below this Group to display in the tree.

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

update_attributes

update_attributes(new_attributes: dict[str, Any]) -> Group

Update the attributes of this group.

Examples:

>>> import zarr
>>> group = zarr.group()
>>> group.update_attributes({"foo": "bar"})
>>> group.attrs.asdict()
{'foo': 'bar'}

Source code in zarr/core/group.py

def update_attributes(self, new_attributes: dict[str, Any]) -> Group:
    """Update the attributes of this group.

    Examples
    --------
    >>> import zarr
    >>> group = zarr.group()
    >>> group.update_attributes({"foo": "bar"})
    >>> group.attrs.asdict()
    {'foo': 'bar'}
    """
    self._sync(self._async_group.update_attributes(new_attributes))
    return self

update_attributes_async async

update_attributes_async(
    new_attributes: dict[str, Any],
) -> Group

Update the attributes of this group.

Examples:

>>> import zarr
>>> group = zarr.group()
>>> await group.update_attributes_async({"foo": "bar"})
>>> group.attrs.asdict()
{'foo': 'bar'}

Source code in zarr/core/group.py

async def update_attributes_async(self, new_attributes: dict[str, Any]) -> Group:
    """Update the attributes of this group.

    Examples
    --------
    >>> import zarr
    >>> group = zarr.group()
    >>> await group.update_attributes_async({"foo": "bar"})
    >>> group.attrs.asdict()
    {'foo': 'bar'}
    """
    new_metadata = replace(self.metadata, attributes=new_attributes)

    # Write new metadata
    to_save = new_metadata.to_buffer_dict(default_buffer_prototype())
    awaitables = [set_or_delete(self.store_path / key, value) for key, value in to_save.items()]
    await asyncio.gather(*awaitables)

    async_group = replace(self._async_group, metadata=new_metadata)
    return replace(self, _async_group=async_group)

zeros

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

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

Parameters:

• name (str) –

  Name of the array.

• 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 zarr/core/group.py

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

    Parameters
    ----------
    name : str
        Name of the array.
    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 Array(self._sync(self._async_group.zeros(name=name, shape=shape, **kwargs)))

zeros_like

zeros_like(
    *, name: str, data: ArrayLike, **kwargs: Any
) -> Array

Create a sub-array of zeros like data.

Parameters:

• name (str) –

  Name of the array.

• data (array - like) –

  The array to create the new array like.

• **kwargs (Any, default: {} ) –

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

Returns:

• Array –

  The new array.

Source code in zarr/core/group.py

def zeros_like(self, *, name: str, data: async_api.ArrayLike, **kwargs: Any) -> Array:
    """Create a sub-array of zeros like `data`.

    Parameters
    ----------
    name : str
        Name of the array.
    data : array-like
        The array to create the new array like.
    **kwargs
        Keyword arguments passed to [zarr.api.asynchronous.create][].

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

    return Array(self._sync(self._async_group.zeros_like(name=name, data=data, **kwargs)))

zarr.AsyncGroup dataclass

Asynchronous Group object.

Source code in zarr/core/group.py

@dataclass(frozen=True)
class AsyncGroup:
    """
    Asynchronous Group object.
    """

    metadata: GroupMetadata
    store_path: StorePath

    # TODO: make this correct and work
    # TODO: ensure that this can be bound properly to subclass of AsyncGroup

    @classmethod
    async def from_store(
        cls,
        store: StoreLike,
        *,
        attributes: dict[str, Any] | None = None,
        overwrite: bool = False,
        zarr_format: ZarrFormat = 3,
    ) -> AsyncGroup:
        store_path = await make_store_path(store)

        if overwrite:
            if store_path.store.supports_deletes:
                await store_path.delete_dir()
            else:
                await ensure_no_existing_node(store_path, zarr_format=zarr_format)
        else:
            await ensure_no_existing_node(store_path, zarr_format=zarr_format)
        attributes = attributes or {}
        group = cls(
            metadata=GroupMetadata(attributes=attributes, zarr_format=zarr_format),
            store_path=store_path,
        )
        await group._save_metadata(ensure_parents=True)
        return group

    @classmethod
    async def open(
        cls,
        store: StoreLike,
        zarr_format: ZarrFormat | None = 3,
        use_consolidated: bool | str | None = None,
    ) -> AsyncGroup:
        """Open a new AsyncGroup

        Parameters
        ----------
        store : StoreLike
        zarr_format : {2, 3}, optional
        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) and the Store supports it.

            To explicitly require consolidated metadata, set ``use_consolidated=True``.
            In this case, if the Store doesn't support consolidation or consolidated metadata is
            not found, a ``ValueError`` exception is raised.

            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.
        """
        store_path = await make_store_path(store)
        if not store_path.store.supports_consolidated_metadata:
            # Fail if consolidated metadata was requested but the Store doesn't support it
            if use_consolidated:
                store_name = type(store_path.store).__name__
                raise ValueError(
                    f"The Zarr store in use ({store_name}) doesn't support consolidated metadata."
                )

            # if use_consolidated was None (optional), the Store dictates it doesn't want consolidation
            use_consolidated = False

        consolidated_key = ZMETADATA_V2_JSON

        if (zarr_format == 2 or zarr_format is None) and isinstance(use_consolidated, str):
            consolidated_key = use_consolidated

        if zarr_format == 2:
            paths = [store_path / ZGROUP_JSON, store_path / ZATTRS_JSON]
            if use_consolidated or use_consolidated is None:
                paths.append(store_path / consolidated_key)

            zgroup_bytes, zattrs_bytes, *rest = await asyncio.gather(
                *[path.get() for path in paths]
            )
            if zgroup_bytes is None:
                raise FileNotFoundError(store_path)

            if use_consolidated or use_consolidated is None:
                maybe_consolidated_metadata_bytes = rest[0]

            else:
                maybe_consolidated_metadata_bytes = None

        elif zarr_format == 3:
            zarr_json_bytes = await (store_path / ZARR_JSON).get()
            if zarr_json_bytes is None:
                raise FileNotFoundError(store_path)
        elif zarr_format is None:
            (
                zarr_json_bytes,
                zgroup_bytes,
                zattrs_bytes,
                maybe_consolidated_metadata_bytes,
            ) = await asyncio.gather(
                (store_path / ZARR_JSON).get(),
                (store_path / ZGROUP_JSON).get(),
                (store_path / ZATTRS_JSON).get(),
                (store_path / str(consolidated_key)).get(),
            )
            if zarr_json_bytes is not None and zgroup_bytes is not None:
                # warn and favor v3
                msg = f"Both zarr.json (Zarr format 3) and .zgroup (Zarr format 2) metadata objects exist at {store_path}. Zarr format 3 will be used."
                warnings.warn(msg, category=ZarrUserWarning, stacklevel=1)
            if zarr_json_bytes is None and zgroup_bytes is None:
                raise FileNotFoundError(
                    f"could not find zarr.json or .zgroup objects in {store_path}"
                )
            # set zarr_format based on which keys were found
            if zarr_json_bytes is not None:
                zarr_format = 3
            else:
                zarr_format = 2
        else:
            msg = f"Invalid value for 'zarr_format'. Expected 2, 3, or None. Got '{zarr_format}'."  # type: ignore[unreachable]
            raise MetadataValidationError(msg)

        if zarr_format == 2:
            # this is checked above, asserting here for mypy
            assert zgroup_bytes is not None

            if use_consolidated and maybe_consolidated_metadata_bytes is None:
                # the user requested consolidated metadata, but it was missing
                raise ValueError(consolidated_key)

            elif use_consolidated is False:
                # the user explicitly opted out of consolidated_metadata.
                # Discard anything we might have read.
                maybe_consolidated_metadata_bytes = None

            return cls._from_bytes_v2(
                store_path, zgroup_bytes, zattrs_bytes, maybe_consolidated_metadata_bytes
            )
        else:
            # V3 groups are comprised of a zarr.json object
            assert zarr_json_bytes is not None
            if not isinstance(use_consolidated, bool | None):
                raise TypeError("use_consolidated must be a bool or None for Zarr format 3.")

            return cls._from_bytes_v3(
                store_path,
                zarr_json_bytes,
                use_consolidated=use_consolidated,
            )

    @classmethod
    def _from_bytes_v2(
        cls,
        store_path: StorePath,
        zgroup_bytes: Buffer,
        zattrs_bytes: Buffer | None,
        consolidated_metadata_bytes: Buffer | None,
    ) -> AsyncGroup:
        # V2 groups are comprised of a .zgroup and .zattrs objects
        zgroup = json.loads(zgroup_bytes.to_bytes())
        zattrs = json.loads(zattrs_bytes.to_bytes()) if zattrs_bytes is not None else {}
        group_metadata = {**zgroup, "attributes": zattrs}

        if consolidated_metadata_bytes is not None:
            v2_consolidated_metadata = json.loads(consolidated_metadata_bytes.to_bytes())
            v2_consolidated_metadata = v2_consolidated_metadata["metadata"]
            # We already read zattrs and zgroup. Should we ignore these?
            v2_consolidated_metadata.pop(".zattrs", None)
            v2_consolidated_metadata.pop(".zgroup", None)

            consolidated_metadata: defaultdict[str, dict[str, Any]] = defaultdict(dict)

            # keys like air/.zarray, air/.zattrs
            for k, v in v2_consolidated_metadata.items():
                path, kind = k.rsplit("/.", 1)

                if kind == "zarray":
                    consolidated_metadata[path].update(v)
                elif kind == "zattrs":
                    consolidated_metadata[path]["attributes"] = v
                elif kind == "zgroup":
                    consolidated_metadata[path].update(v)
                else:
                    raise ValueError(f"Invalid file type '{kind}' at path '{path}")

            group_metadata["consolidated_metadata"] = {
                "metadata": dict(consolidated_metadata),
                "kind": "inline",
                "must_understand": False,
            }

        return cls.from_dict(store_path, group_metadata)

    @classmethod
    def _from_bytes_v3(
        cls,
        store_path: StorePath,
        zarr_json_bytes: Buffer,
        use_consolidated: bool | None,
    ) -> AsyncGroup:
        group_metadata = json.loads(zarr_json_bytes.to_bytes())
        if use_consolidated and group_metadata.get("consolidated_metadata") is None:
            msg = f"Consolidated metadata requested with 'use_consolidated=True' but not found in '{store_path.path}'."
            raise ValueError(msg)

        elif use_consolidated is False:
            # Drop consolidated metadata if it's there.
            group_metadata.pop("consolidated_metadata", None)

        return cls.from_dict(store_path, group_metadata)

    @classmethod
    def from_dict(
        cls,
        store_path: StorePath,
        data: dict[str, Any],
    ) -> AsyncGroup:
        node_type = data.pop("node_type", None)
        if node_type == "array":
            msg = f"An array already exists in store {store_path.store} at path {store_path.path}."
            raise ContainsArrayError(msg)
        elif node_type not in ("group", None):
            msg = f"Node type in metadata ({node_type}) is not 'group'"
            raise GroupNotFoundError(msg)
        return cls(
            metadata=GroupMetadata.from_dict(data),
            store_path=store_path,
        )

    async def setitem(self, key: str, value: Any) -> None:
        """
        Fastpath for creating a new array
        New arrays will be created with default array settings for the array type.

        Parameters
        ----------
        key : str
            Array name
        value : array-like
            Array data
        """
        path = self.store_path / key
        await async_api.save_array(
            store=path, arr=value, zarr_format=self.metadata.zarr_format, overwrite=True
        )

    async def getitem(
        self,
        key: str,
    ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata] | AsyncGroup:
        """
        Get a subarray or subgroup from the group.

        Parameters
        ----------
        key : str
            Array or group name

        Returns
        -------
        AsyncArray or AsyncGroup
        """
        store_path = self.store_path / key
        logger.debug("key=%s, store_path=%s", key, store_path)

        # Consolidated metadata lets us avoid some I/O operations so try that first.
        if self.metadata.consolidated_metadata is not None:
            return self._getitem_consolidated(store_path, key, prefix=self.name)
        try:
            return await get_node(
                store=store_path.store, path=store_path.path, zarr_format=self.metadata.zarr_format
            )
        except FileNotFoundError as e:
            raise KeyError(key) from e

    def _getitem_consolidated(
        self, store_path: StorePath, key: str, prefix: str
    ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata] | AsyncGroup:
        # getitem, in the special case where we have consolidated metadata.
        # Note that this is a regular def (non async) function.
        # This shouldn't do any additional I/O.

        # the caller needs to verify this!
        assert self.metadata.consolidated_metadata is not None

        # we support nested getitems like group/subgroup/array
        indexers = normalize_path(key).split("/")
        indexers.reverse()
        metadata: ArrayV2Metadata | ArrayV3Metadata | GroupMetadata = self.metadata

        while indexers:
            indexer = indexers.pop()
            if isinstance(metadata, ArrayV2Metadata | ArrayV3Metadata):
                # we've indexed into an array with group["array/subarray"]. Invalid.
                raise KeyError(key)
            if metadata.consolidated_metadata is None:
                # we've indexed into a group without consolidated metadata.
                # This isn't normal; typically, consolidated metadata
                # will include explicit markers for when there are no child
                # nodes as metadata={}.
                # We have some freedom in exactly how we interpret this case.
                # For now, we treat None as the same as {}, i.e. we don't
                # have any children.
                raise KeyError(key)
            try:
                metadata = metadata.consolidated_metadata.metadata[indexer]
            except KeyError as e:
                # The Group Metadata has consolidated metadata, but the key
                # isn't present. We trust this to mean that the key isn't in
                # the hierarchy, and *don't* fall back to checking the store.
                msg = f"'{key}' not found in consolidated metadata."
                raise KeyError(msg) from e

        # update store_path to ensure that AsyncArray/Group.name is correct
        if prefix != "/":
            key = "/".join([prefix.lstrip("/"), key])
        store_path = StorePath(store=store_path.store, path=key)

        if isinstance(metadata, GroupMetadata):
            return AsyncGroup(metadata=metadata, store_path=store_path)
        else:
            return AsyncArray(metadata=metadata, store_path=store_path)

    async def delitem(self, key: str) -> None:
        """Delete a group member.

        Parameters
        ----------
        key : str
            Array or group name
        """
        store_path = self.store_path / key

        await store_path.delete_dir()
        if self.metadata.consolidated_metadata:
            self.metadata.consolidated_metadata.metadata.pop(key, None)
            await self._save_metadata()

    async def get(
        self, key: str, default: DefaultT | None = None
    ) -> AsyncArray[Any] | AsyncGroup | DefaultT | None:
        """Obtain a group member, returning default if not found.

        Parameters
        ----------
        key : str
            Group member name.
        default : object
            Default value to return if key is not found (default: None).

        Returns
        -------
        object
            Group member (AsyncArray or AsyncGroup) or default if not found.
        """
        try:
            return await self.getitem(key)
        except KeyError:
            return default

    async def _save_metadata(self, ensure_parents: bool = False) -> None:
        await save_metadata(self.store_path, self.metadata, ensure_parents=ensure_parents)

    @property
    def path(self) -> str:
        """Storage path."""
        return self.store_path.path

    @property
    def name(self) -> str:
        """Group name following h5py convention."""
        if self.path:
            # follow h5py convention: add leading slash
            name = self.path
            if name[0] != "/":
                name = "/" + name
            return name
        return "/"

    @property
    def basename(self) -> str:
        """Final component of name."""
        return self.name.split("/")[-1]

    @property
    def attrs(self) -> dict[str, Any]:
        return self.metadata.attributes

    @property
    def info(self) -> Any:
        """
        Return a visual representation of the statically known information about a group.

        Note that this doesn't include dynamic information, like the number of child
        Groups or Arrays.

        Returns
        -------
        GroupInfo

        Related
        -------
        [zarr.AsyncGroup.info_complete][]
            All information about a group, including dynamic information
        """

        if self.metadata.consolidated_metadata:
            members = list(self.metadata.consolidated_metadata.flattened_metadata.values())
        else:
            members = None
        return self._info(members=members)

    async def info_complete(self) -> Any:
        """
        Return all the information for a group.

        This includes dynamic information like the number
        of child Groups or Arrays. If this group doesn't contain consolidated
        metadata then this will need to read from the backing Store.

        Returns
        -------
        GroupInfo

        Related
        -------
        [zarr.AsyncGroup.info][]
        """
        members = [x[1].metadata async for x in self.members(max_depth=None)]
        return self._info(members=members)

    def _info(
        self, members: list[ArrayV2Metadata | ArrayV3Metadata | GroupMetadata] | None = None
    ) -> Any:
        kwargs = {}
        if members is not None:
            kwargs["_count_members"] = len(members)
            count_arrays = 0
            count_groups = 0
            for member in members:
                if isinstance(member, GroupMetadata):
                    count_groups += 1
                else:
                    count_arrays += 1
            kwargs["_count_arrays"] = count_arrays
            kwargs["_count_groups"] = count_groups

        return GroupInfo(
            _name=self.store_path.path,
            _read_only=self.read_only,
            _store_type=type(self.store_path.store).__name__,
            _zarr_format=self.metadata.zarr_format,
            # maybe do a typeddict
            **kwargs,  # type: ignore[arg-type]
        )

    @property
    def store(self) -> Store:
        return self.store_path.store

    @property
    def read_only(self) -> bool:
        # Backwards compatibility for 2.x
        return self.store_path.read_only

    @property
    def synchronizer(self) -> None:
        # Backwards compatibility for 2.x
        # Not implemented in 3.x yet.
        return None

    async def create_group(
        self,
        name: str,
        *,
        overwrite: bool = False,
        attributes: dict[str, Any] | None = None,
    ) -> AsyncGroup:
        """Create a sub-group.

        Parameters
        ----------
        name : str
            Group name.
        overwrite : bool, optional
            If True, do not raise an error if the group already exists.
        attributes : dict, optional
            Group attributes.

        Returns
        -------
        g : AsyncGroup
        """
        attributes = attributes or {}
        return await type(self).from_store(
            self.store_path / name,
            attributes=attributes,
            overwrite=overwrite,
            zarr_format=self.metadata.zarr_format,
        )

    async def require_group(self, name: str, overwrite: bool = False) -> AsyncGroup:
        """Obtain a sub-group, creating one if it doesn't exist.

        Parameters
        ----------
        name : str
            Group name.
        overwrite : bool, optional
            Overwrite any existing group with given `name` if present.

        Returns
        -------
        g : AsyncGroup
        """
        if overwrite:
            # TODO: check that overwrite=True errors if an array exists where the group is being created
            grp = await self.create_group(name, overwrite=True)
        else:
            try:
                item: (
                    AsyncGroup | AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]
                ) = await self.getitem(name)
                if not isinstance(item, AsyncGroup):
                    raise TypeError(
                        f"Incompatible object ({item.__class__.__name__}) already exists"
                    )
                assert isinstance(item, AsyncGroup)  # make mypy happy
                grp = item
            except KeyError:
                grp = await self.create_group(name)
        return grp

    async def require_groups(self, *names: str) -> tuple[AsyncGroup, ...]:
        """Convenience method to require multiple groups in a single call.

        Parameters
        ----------
        *names : str
            Group names.

        Returns
        -------
        Tuple[AsyncGroup, ...]
        """
        if not names:
            return ()
        return tuple(await asyncio.gather(*(self.require_group(name) for name in names)))

    async def create_array(
        self,
        name: str,
        *,
        shape: ShapeLike | None = None,
        dtype: ZDTypeLike | None = None,
        data: np.ndarray[Any, np.dtype[Any]] | None = None,
        chunks: tuple[int, ...] | Literal["auto"] = "auto",
        shards: ShardsLike | None = None,
        filters: FiltersLike = "auto",
        compressors: CompressorsLike = "auto",
        compressor: CompressorLike = "auto",
        serializer: SerializerLike = "auto",
        fill_value: Any | None = DEFAULT_FILL_VALUE,
        order: MemoryOrder | None = None,
        attributes: dict[str, JSON] | None = None,
        chunk_key_encoding: ChunkKeyEncodingLike | None = None,
        dimension_names: DimensionNames = None,
        storage_options: dict[str, Any] | None = None,
        overwrite: bool = False,
        config: ArrayConfigLike | None = None,
        write_data: bool = True,
    ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
        """Create an array within this group.

        This method lightly wraps [zarr.core.array.create_array][].

        Parameters
        ----------
        name : str
            The name of the array relative to the group. If ``path`` is ``None``, the array will be located
            at the root of the store.
        shape : tuple[int, ...]
            Shape of the array.
        dtype : npt.DTypeLike
            Data type of the array.
        chunks : tuple[int, ...], optional
            Chunk shape of the array.
            If not specified, default are guessed based on the shape and 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 [`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
            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
            [`zarr.dtype.VariableLengthUTF8`][] or [`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 [`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.
            in [`zarr.config`][zarr.config].
            Use ``None`` to omit the default compressor.
        compressor : Codec, optional
            Deprecated in favor of ``compressors``.
        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 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].
        attributes : dict, optional
            Attributes for the 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": "."}}``.
        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.
        config : ArrayConfig or 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

        """
        compressors = _parse_deprecated_compressor(
            compressor, compressors, zarr_format=self.metadata.zarr_format
        )
        return await create_array(
            store=self.store_path,
            name=name,
            shape=shape,
            dtype=dtype,
            data=data,
            chunks=chunks,
            shards=shards,
            filters=filters,
            compressors=compressors,
            serializer=serializer,
            fill_value=fill_value,
            order=order,
            zarr_format=self.metadata.zarr_format,
            attributes=attributes,
            chunk_key_encoding=chunk_key_encoding,
            dimension_names=dimension_names,
            storage_options=storage_options,
            overwrite=overwrite,
            config=config,
            write_data=write_data,
        )

    @deprecated("Use AsyncGroup.create_array instead.", category=ZarrDeprecationWarning)
    async def create_dataset(
        self, name: str, *, shape: ShapeLike, **kwargs: Any
    ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
        """Create an array.

        !!! warning "Deprecated"
            `AsyncGroup.create_dataset()` is deprecated since v3.0.0 and will be removed in v3.1.0.
            Use `AsyncGroup.create_array` instead.

        Arrays are known as "datasets" in HDF5 terminology. For compatibility
        with h5py, Zarr groups also implement the [zarr.AsyncGroup.require_dataset][] method.

        Parameters
        ----------
        name : str
            Array name.
        **kwargs : dict
            Additional arguments passed to [zarr.AsyncGroup.create_array][].

        Returns
        -------
        a : AsyncArray
        """
        data = kwargs.pop("data", None)
        # create_dataset in zarr 2.x requires shape but not dtype if data is
        # provided. Allow this configuration by inferring dtype from data if
        # necessary and passing it to create_array
        if "dtype" not in kwargs and data is not None:
            kwargs["dtype"] = data.dtype
        array = await self.create_array(name, shape=shape, **kwargs)
        if data is not None:
            await array.setitem(slice(None), data)
        return array

    @deprecated("Use AsyncGroup.require_array instead.", category=ZarrDeprecationWarning)
    async def require_dataset(
        self,
        name: str,
        *,
        shape: tuple[int, ...],
        dtype: npt.DTypeLike = None,
        exact: bool = False,
        **kwargs: Any,
    ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
        """Obtain an array, creating if it doesn't exist.

        !!! warning "Deprecated"
            `AsyncGroup.require_dataset()` is deprecated since v3.0.0 and will be removed in v3.1.0.
            Use `AsyncGroup.require_dataset` instead.

        Arrays are known as "datasets" in HDF5 terminology. For compatibility
        with h5py, Zarr groups also implement the [zarr.AsyncGroup.create_dataset][] method.

        Other `kwargs` are as per [zarr.AsyncGroup.create_dataset][].

        Parameters
        ----------
        name : str
            Array name.
        shape : int or tuple of ints
            Array shape.
        dtype : str or dtype, optional
            NumPy dtype.
        exact : bool, optional
            If True, require `dtype` to match exactly. If false, require
            `dtype` can be cast from array dtype.

        Returns
        -------
        a : AsyncArray
        """
        return await self.require_array(name, shape=shape, dtype=dtype, exact=exact, **kwargs)

    async def require_array(
        self,
        name: str,
        *,
        shape: ShapeLike,
        dtype: npt.DTypeLike = None,
        exact: bool = False,
        **kwargs: Any,
    ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
        """Obtain an array, creating if it doesn't exist.

        Other `kwargs` are as per [zarr.AsyncGroup.create_dataset][].

        Parameters
        ----------
        name : str
            Array name.
        shape : int or tuple of ints
            Array shape.
        dtype : str or dtype, optional
            NumPy dtype.
        exact : bool, optional
            If True, require `dtype` to match exactly. If false, require
            `dtype` can be cast from array dtype.

        Returns
        -------
        a : AsyncArray
        """
        try:
            ds = await self.getitem(name)
            if not isinstance(ds, AsyncArray):
                raise TypeError(f"Incompatible object ({ds.__class__.__name__}) already exists")

            shape = parse_shapelike(shape)
            if shape != ds.shape:
                raise TypeError(f"Incompatible shape ({ds.shape} vs {shape})")

            dtype = np.dtype(dtype)
            if exact:
                if ds.dtype != dtype:
                    raise TypeError(f"Incompatible dtype ({ds.dtype} vs {dtype})")
            else:
                if not np.can_cast(ds.dtype, dtype):
                    raise TypeError(f"Incompatible dtype ({ds.dtype} vs {dtype})")
        except KeyError:
            ds = await self.create_array(name, shape=shape, dtype=dtype, **kwargs)

        return ds

    async def update_attributes(self, new_attributes: dict[str, Any]) -> AsyncGroup:
        """Update group attributes.

        Parameters
        ----------
        new_attributes : dict
            New attributes to set on the group.

        Returns
        -------
        self : AsyncGroup
        """
        self.metadata.attributes.update(new_attributes)

        # Write new metadata
        await self._save_metadata()

        return self

    def __repr__(self) -> str:
        return f"<AsyncGroup {self.store_path}>"

    async def nmembers(
        self,
        max_depth: int | None = 0,
    ) -> int:
        """Count the number of members in this group.

        Parameters
        ----------
        max_depth : int, default 0
            The maximum number of levels of the hierarchy to include. By
            default, (``max_depth=0``) only immediate children are included. Set
            ``max_depth=None`` to include all nodes, and some positive integer
            to consider children within that many levels of the root Group.

        Returns
        -------
        count : int
        """
        # check if we can use consolidated metadata, which requires that we have non-None
        # consolidated metadata at all points in the hierarchy.
        if self.metadata.consolidated_metadata is not None:
            if max_depth is not None and max_depth < 0:
                raise ValueError(f"max_depth must be None or >= 0. Got '{max_depth}' instead")
            if max_depth is None:
                return len(self.metadata.consolidated_metadata.flattened_metadata)
            else:
                return len(
                    [
                        x
                        for x in self.metadata.consolidated_metadata.flattened_metadata
                        if x.count("/") <= max_depth
                    ]
                )
        # TODO: consider using aioitertools.builtins.sum for this
        # return await aioitertools.builtins.sum((1 async for _ in self.members()), start=0)
        n = 0
        async for _ in self.members(max_depth=max_depth):
            n += 1
        return n

    async def members(
        self,
        max_depth: int | None = 0,
        *,
        use_consolidated_for_children: bool = True,
    ) -> AsyncGenerator[
        tuple[str, AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata] | AsyncGroup],
        None,
    ]:
        """
        Returns an AsyncGenerator over the arrays and groups contained in this group.
        This method requires that `store_path.store` supports directory listing.

        The results are not guaranteed to be ordered.

        Parameters
        ----------
        max_depth : int, default 0
            The maximum number of levels of the hierarchy to include. By
            default, (``max_depth=0``) only immediate children are included. Set
            ``max_depth=None`` to include all nodes, and some positive integer
            to consider children within that many levels of the root Group.
        use_consolidated_for_children : bool, default True
            Whether to use the consolidated metadata of child groups loaded
            from the store. Note that this only affects groups loaded from the
            store. If the current Group already has consolidated metadata, it
            will always be used.

        Returns
        -------
        path:
            A string giving the path to the target, relative to the Group ``self``.
        value: AsyncArray or AsyncGroup
            The AsyncArray or AsyncGroup that is a child of ``self``.
        """
        if max_depth is not None and max_depth < 0:
            raise ValueError(f"max_depth must be None or >= 0. Got '{max_depth}' instead")
        async for item in self._members(
            max_depth=max_depth, use_consolidated_for_children=use_consolidated_for_children
        ):
            yield item

    def _members_consolidated(
        self, max_depth: int | None, prefix: str = ""
    ) -> Generator[
        tuple[str, AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata] | AsyncGroup],
        None,
    ]:
        consolidated_metadata = self.metadata.consolidated_metadata

        do_recursion = max_depth is None or max_depth > 0

        # we kind of just want the top-level keys.
        if consolidated_metadata is not None:
            for key in consolidated_metadata.metadata:
                obj = self._getitem_consolidated(
                    self.store_path, key, prefix=self.name
                )  # Metadata -> Group/Array
                key = f"{prefix}/{key}".lstrip("/")
                yield key, obj

                if do_recursion and isinstance(obj, AsyncGroup):
                    if max_depth is None:
                        new_depth = None
                    else:
                        new_depth = max_depth - 1
                    yield from obj._members_consolidated(new_depth, prefix=key)

    async def _members(
        self, max_depth: int | None, *, use_consolidated_for_children: bool = True
    ) -> AsyncGenerator[
        tuple[str, AsyncArray[ArrayV3Metadata] | AsyncArray[ArrayV2Metadata] | AsyncGroup], None
    ]:
        skip_keys: tuple[str, ...]
        if self.metadata.zarr_format == 2:
            skip_keys = (".zattrs", ".zgroup", ".zarray", ".zmetadata")
        elif self.metadata.zarr_format == 3:
            skip_keys = ("zarr.json",)
        else:
            raise ValueError(f"Unknown Zarr format: {self.metadata.zarr_format}")

        if self.metadata.consolidated_metadata is not None:
            members = self._members_consolidated(max_depth=max_depth)
            for member in members:
                yield member
            return

        if not self.store_path.store.supports_listing:
            msg = (
                f"The store associated with this group ({type(self.store_path.store)}) "
                "does not support listing, "
                "specifically via the `list_dir` method. "
                "This function requires a store that supports listing."
            )

            raise ValueError(msg)
        # enforce a concurrency limit by passing a semaphore to all the recursive functions
        semaphore = asyncio.Semaphore(config.get("async.concurrency"))
        async for member in _iter_members_deep(
            self,
            max_depth=max_depth,
            skip_keys=skip_keys,
            semaphore=semaphore,
            use_consolidated_for_children=use_consolidated_for_children,
        ):
            yield member

    async def create_hierarchy(
        self,
        nodes: dict[str, ArrayV2Metadata | ArrayV3Metadata | GroupMetadata],
        *,
        overwrite: bool = False,
    ) -> AsyncIterator[
        tuple[str, AsyncGroup | AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]]
    ]:
        """
        Create a hierarchy of arrays or groups rooted at this group.

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

        Explicitly specifying a root group, e.g. with ``nodes = {'': GroupMetadata()}`` is an error
        because this group instance is the root group.

        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
        ----------
        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 path of the group. The values are instances of ``GroupMetadata`` or ``ArrayMetadata``. Note that
            all values must have the same ``zarr_format`` as the parent group -- 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, AsyncArray | AsyncGroup].
        """
        # check that all the nodes have the same zarr_format as Self
        prefix = self.path
        nodes_parsed = {}
        for key, value in nodes.items():
            if value.zarr_format != self.metadata.zarr_format:
                msg = (
                    "The zarr_format of the nodes must be the same as the parent group. "
                    f"The node at {key} has zarr_format {value.zarr_format}, but the parent group"
                    f" has zarr_format {self.metadata.zarr_format}."
                )
                raise ValueError(msg)
            if normalize_path(key) == "":
                msg = (
                    "The input defines a root node, but a root node already exists, namely this Group instance."
                    "It is an error to use this method to create a root node. "
                    "Remove the root node from the input dict, or use a function like "
                    "create_rooted_hierarchy to create a rooted hierarchy."
                )
                raise ValueError(msg)
            else:
                nodes_parsed[_join_paths([prefix, key])] = value

        async for key, node in create_hierarchy(
            store=self.store,
            nodes=nodes_parsed,
            overwrite=overwrite,
        ):
            if prefix == "":
                out_key = key
            else:
                out_key = key.removeprefix(prefix + "/")
            yield out_key, node

    async def keys(self) -> AsyncGenerator[str, None]:
        """Iterate over member names."""
        async for key, _ in self.members():
            yield key

    async def contains(self, member: str) -> bool:
        """Check if a member exists in the group.

        Parameters
        ----------
        member : str
            Member name.

        Returns
        -------
        bool
        """
        # TODO: this can be made more efficient.
        try:
            await self.getitem(member)
        except KeyError:
            return False
        else:
            return True

    async def groups(self) -> AsyncGenerator[tuple[str, AsyncGroup], None]:
        """Iterate over subgroups."""
        async for name, value in self.members():
            if isinstance(value, AsyncGroup):
                yield name, value

    async def group_keys(self) -> AsyncGenerator[str, None]:
        """Iterate over group names."""
        async for key, _ in self.groups():
            yield key

    async def group_values(self) -> AsyncGenerator[AsyncGroup, None]:
        """Iterate over group values."""
        async for _, group in self.groups():
            yield group

    async def arrays(
        self,
    ) -> AsyncGenerator[
        tuple[str, AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]], None
    ]:
        """Iterate over arrays."""
        async for key, value in self.members():
            if isinstance(value, AsyncArray):
                yield key, value

    async def array_keys(self) -> AsyncGenerator[str, None]:
        """Iterate over array names."""
        async for key, _ in self.arrays():
            yield key

    async def array_values(
        self,
    ) -> AsyncGenerator[AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata], None]:
        """Iterate over array values."""
        async for _, array in self.arrays():
            yield array

    async def tree(self, expand: bool | None = None, level: int | None = None) -> Any:
        """
        Return a tree-like representation of a hierarchy.

        This requires the optional ``rich`` dependency.

        Parameters
        ----------
        expand : bool, optional
            This keyword is not yet supported. A NotImplementedError is raised if
            it's used.
        level : int, optional
            The maximum depth below this Group to display in the tree.

        Returns
        -------
        TreeRepr
            A pretty-printable object displaying the hierarchy.
        """
        from zarr.core._tree import group_tree_async

        if expand is not None:
            raise NotImplementedError("'expand' is not yet implemented.")
        return await group_tree_async(self, max_depth=level)

    async def empty(
        self, *, name: str, shape: tuple[int, ...], **kwargs: Any
    ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
        """Create an empty array with the specified shape in this Group. The contents will
        be filled with the array's fill value or zeros if no fill value is provided.

        Parameters
        ----------
        name : str
            Name of the array.
        shape : int or tuple of int
            Shape of the empty array.
        **kwargs
            Keyword arguments passed to [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 async_api.empty(shape=shape, store=self.store_path, path=name, **kwargs)

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

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

        Returns
        -------
        AsyncArray
            The new array.
        """
        return await async_api.zeros(shape=shape, store=self.store_path, path=name, **kwargs)

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

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

        Returns
        -------
        AsyncArray
            The new array.
        """
        return await async_api.ones(shape=shape, store=self.store_path, path=name, **kwargs)

    async def full(
        self, *, name: str, shape: tuple[int, ...], fill_value: Any | None, **kwargs: Any
    ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
        """Create an array, with "fill_value" being used as the default value for uninitialized portions of the array.

        Parameters
        ----------
        name : str
            Name of the array.
        shape : int or tuple of int
            Shape of the empty array.
        fill_value : scalar
            Value to fill the array with.
        **kwargs
            Keyword arguments passed to [zarr.api.asynchronous.create][].

        Returns
        -------
        AsyncArray
            The new array.
        """
        return await async_api.full(
            shape=shape,
            fill_value=fill_value,
            store=self.store_path,
            path=name,
            **kwargs,
        )

    async def empty_like(
        self, *, name: str, data: async_api.ArrayLike, **kwargs: Any
    ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
        """Create an empty sub-array like `data`. The contents will be filled with
        the array's fill value or zeros if no fill value is provided.

        Parameters
        ----------
        name : str
            Name of the array.
        data : array-like
            The array to create an empty array like.
        **kwargs
            Keyword arguments passed to [zarr.api.asynchronous.create][].

        Returns
        -------
        AsyncArray
            The new array.
        """
        return await async_api.empty_like(a=data, store=self.store_path, path=name, **kwargs)

    async def zeros_like(
        self, *, name: str, data: async_api.ArrayLike, **kwargs: Any
    ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
        """Create a sub-array of zeros like `data`.

        Parameters
        ----------
        name : str
            Name of the array.
        data : array-like
            The array to create the new array like.
        **kwargs
            Keyword arguments passed to [zarr.api.asynchronous.create][].

        Returns
        -------
        AsyncArray
            The new array.
        """
        return await async_api.zeros_like(a=data, store=self.store_path, path=name, **kwargs)

    async def ones_like(
        self, *, name: str, data: async_api.ArrayLike, **kwargs: Any
    ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
        """Create a sub-array of ones like `data`.

        Parameters
        ----------
        name : str
            Name of the array.
        data : array-like
            The array to create the new array like.
        **kwargs
            Keyword arguments passed to [zarr.api.asynchronous.create][].

        Returns
        -------
        AsyncArray
            The new array.
        """
        return await async_api.ones_like(a=data, store=self.store_path, path=name, **kwargs)

    async def full_like(
        self, *, name: str, data: async_api.ArrayLike, **kwargs: Any
    ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
        """Create a sub-array like `data` filled with the `fill_value` of `data` .

        Parameters
        ----------
        name : str
            Name of the array.
        data : array-like
            The array to create the new array like.
        **kwargs
            Keyword arguments passed to [zarr.api.asynchronous.create][].

        Returns
        -------
        AsyncArray
            The new array.
        """
        return await async_api.full_like(a=data, store=self.store_path, path=name, **kwargs)

    async def move(self, source: str, dest: str) -> None:
        """Move a sub-group or sub-array from one path to another.

        Notes
        -----
        Not implemented
        """
        raise NotImplementedError

basename property

basename: str

Final component of name.

info property

info: Any

Return a visual representation of the statically known information about a group.

Note that this doesn't include dynamic information, like the number of child Groups or Arrays.

Returns:

• GroupInfo –

Related

zarr.AsyncGroup.info_complete All information about a group, including dynamic information

name property

name: str

Group name following h5py convention.

path property

path: str

Storage path.

array_keys async

array_keys() -> AsyncGenerator[str, None]

Iterate over array names.

Source code in zarr/core/group.py

async def array_keys(self) -> AsyncGenerator[str, None]:
    """Iterate over array names."""
    async for key, _ in self.arrays():
        yield key

array_values async

array_values() -> AsyncGenerator[
    AsyncArray[ArrayV2Metadata]
    | AsyncArray[ArrayV3Metadata],
    None,
]

Iterate over array values.

Source code in zarr/core/group.py

async def array_values(
    self,
) -> AsyncGenerator[AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata], None]:
    """Iterate over array values."""
    async for _, array in self.arrays():
        yield array

arrays async

arrays() -> AsyncGenerator[
    tuple[
        str,
        AsyncArray[ArrayV2Metadata]
        | AsyncArray[ArrayV3Metadata],
    ],
    None,
]

Iterate over arrays.

Source code in zarr/core/group.py

async def arrays(
    self,
) -> AsyncGenerator[
    tuple[str, AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]], None
]:
    """Iterate over arrays."""
    async for key, value in self.members():
        if isinstance(value, AsyncArray):
            yield key, value

contains async

contains(member: str) -> bool

Check if a member exists in the group.

Parameters:

• member (str) –

  Member name.

Returns:

• bool –

Source code in zarr/core/group.py

async def contains(self, member: str) -> bool:
    """Check if a member exists in the group.

    Parameters
    ----------
    member : str
        Member name.

    Returns
    -------
    bool
    """
    # TODO: this can be made more efficient.
    try:
        await self.getitem(member)
    except KeyError:
        return False
    else:
        return True

create_array async

create_array(
    name: str,
    *,
    shape: ShapeLike | None = None,
    dtype: ZDTypeLike | None = None,
    data: ndarray[Any, dtype[Any]] | None = None,
    chunks: tuple[int, ...] | Literal["auto"] = "auto",
    shards: ShardsLike | None = None,
    filters: FiltersLike = "auto",
    compressors: CompressorsLike = "auto",
    compressor: CompressorLike = "auto",
    serializer: SerializerLike = "auto",
    fill_value: Any | None = DEFAULT_FILL_VALUE,
    order: MemoryOrder | None = None,
    attributes: dict[str, JSON] | None = None,
    chunk_key_encoding: ChunkKeyEncodingLike | None = None,
    dimension_names: DimensionNames = None,
    storage_options: dict[str, Any] | None = None,
    overwrite: bool = False,
    config: ArrayConfigLike | None = None,
    write_data: bool = True,
) -> (
    AsyncArray[ArrayV2Metadata]
    | AsyncArray[ArrayV3Metadata]
)

Create an array within this group.

This method lightly wraps zarr.core.array.create_array.

Parameters:

• name (str) –

  The name of the array relative to the group. If path is None, the array will be located at the root of the store.

• shape (tuple[int, ...], default: None ) –

  Shape of the array.

• dtype (DTypeLike, default: None ) –

  Data type of the array.

• chunks (tuple[int, ...], default: 'auto' ) –

  Chunk shape of the array. If not specified, default are guessed based on the shape and dtype.

• 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 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 zarr.dtype.VariableLengthUTF8 or 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], 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 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 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. in zarr.config. Use None to omit the default compressor.

• compressor (Codec, default: 'auto' ) –

  Deprecated in favor of compressors.

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

• attributes (dict, default: None ) –

  Attributes for the array.

• 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": "."}}.

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

• config (ArrayConfig or 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 –

Source code in zarr/core/group.py

async def create_array(
    self,
    name: str,
    *,
    shape: ShapeLike | None = None,
    dtype: ZDTypeLike | None = None,
    data: np.ndarray[Any, np.dtype[Any]] | None = None,
    chunks: tuple[int, ...] | Literal["auto"] = "auto",
    shards: ShardsLike | None = None,
    filters: FiltersLike = "auto",
    compressors: CompressorsLike = "auto",
    compressor: CompressorLike = "auto",
    serializer: SerializerLike = "auto",
    fill_value: Any | None = DEFAULT_FILL_VALUE,
    order: MemoryOrder | None = None,
    attributes: dict[str, JSON] | None = None,
    chunk_key_encoding: ChunkKeyEncodingLike | None = None,
    dimension_names: DimensionNames = None,
    storage_options: dict[str, Any] | None = None,
    overwrite: bool = False,
    config: ArrayConfigLike | None = None,
    write_data: bool = True,
) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
    """Create an array within this group.

    This method lightly wraps [zarr.core.array.create_array][].

    Parameters
    ----------
    name : str
        The name of the array relative to the group. If ``path`` is ``None``, the array will be located
        at the root of the store.
    shape : tuple[int, ...]
        Shape of the array.
    dtype : npt.DTypeLike
        Data type of the array.
    chunks : tuple[int, ...], optional
        Chunk shape of the array.
        If not specified, default are guessed based on the shape and 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 [`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
        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
        [`zarr.dtype.VariableLengthUTF8`][] or [`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 [`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.
        in [`zarr.config`][zarr.config].
        Use ``None`` to omit the default compressor.
    compressor : Codec, optional
        Deprecated in favor of ``compressors``.
    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 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].
    attributes : dict, optional
        Attributes for the 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": "."}}``.
    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.
    config : ArrayConfig or 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

    """
    compressors = _parse_deprecated_compressor(
        compressor, compressors, zarr_format=self.metadata.zarr_format
    )
    return await create_array(
        store=self.store_path,
        name=name,
        shape=shape,
        dtype=dtype,
        data=data,
        chunks=chunks,
        shards=shards,
        filters=filters,
        compressors=compressors,
        serializer=serializer,
        fill_value=fill_value,
        order=order,
        zarr_format=self.metadata.zarr_format,
        attributes=attributes,
        chunk_key_encoding=chunk_key_encoding,
        dimension_names=dimension_names,
        storage_options=storage_options,
        overwrite=overwrite,
        config=config,
        write_data=write_data,
    )

create_dataset async

create_dataset(
    name: str, *, shape: ShapeLike, **kwargs: Any
) -> (
    AsyncArray[ArrayV2Metadata]
    | AsyncArray[ArrayV3Metadata]
)

Create an array.

Deprecated

AsyncGroup.create_dataset() is deprecated since v3.0.0 and will be removed in v3.1.0. Use AsyncGroup.create_array instead.

Arrays are known as "datasets" in HDF5 terminology. For compatibility with h5py, Zarr groups also implement the zarr.AsyncGroup.require_dataset method.

Parameters:

• name (str) –

  Array name.

• **kwargs (dict, default: {} ) –

  Additional arguments passed to zarr.AsyncGroup.create_array.

Returns:

• a ( AsyncArray ) –

Source code in zarr/core/group.py

@deprecated("Use AsyncGroup.create_array instead.", category=ZarrDeprecationWarning)
async def create_dataset(
    self, name: str, *, shape: ShapeLike, **kwargs: Any
) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
    """Create an array.

    !!! warning "Deprecated"
        `AsyncGroup.create_dataset()` is deprecated since v3.0.0 and will be removed in v3.1.0.
        Use `AsyncGroup.create_array` instead.

    Arrays are known as "datasets" in HDF5 terminology. For compatibility
    with h5py, Zarr groups also implement the [zarr.AsyncGroup.require_dataset][] method.

    Parameters
    ----------
    name : str
        Array name.
    **kwargs : dict
        Additional arguments passed to [zarr.AsyncGroup.create_array][].

    Returns
    -------
    a : AsyncArray
    """
    data = kwargs.pop("data", None)
    # create_dataset in zarr 2.x requires shape but not dtype if data is
    # provided. Allow this configuration by inferring dtype from data if
    # necessary and passing it to create_array
    if "dtype" not in kwargs and data is not None:
        kwargs["dtype"] = data.dtype
    array = await self.create_array(name, shape=shape, **kwargs)
    if data is not None:
        await array.setitem(slice(None), data)
    return array

create_group async

create_group(
    name: str,
    *,
    overwrite: bool = False,
    attributes: dict[str, Any] | None = None,
) -> AsyncGroup

Create a sub-group.

Parameters:

• name (str) –

  Group name.

• overwrite (bool, default: False ) –

  If True, do not raise an error if the group already exists.

• attributes (dict, default: None ) –

  Group attributes.

Returns:

• g ( AsyncGroup ) –

Source code in zarr/core/group.py

async def create_group(
    self,
    name: str,
    *,
    overwrite: bool = False,
    attributes: dict[str, Any] | None = None,
) -> AsyncGroup:
    """Create a sub-group.

    Parameters
    ----------
    name : str
        Group name.
    overwrite : bool, optional
        If True, do not raise an error if the group already exists.
    attributes : dict, optional
        Group attributes.

    Returns
    -------
    g : AsyncGroup
    """
    attributes = attributes or {}
    return await type(self).from_store(
        self.store_path / name,
        attributes=attributes,
        overwrite=overwrite,
        zarr_format=self.metadata.zarr_format,
    )

create_hierarchy async

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

Create a hierarchy of arrays or groups rooted at this group.

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

Explicitly specifying a root group, e.g. with nodes = {'': GroupMetadata()} is an error because this group instance is the root group.

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:

• 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 path of the group. The values are instances of GroupMetadata or ArrayMetadata. Note that all values must have the same zarr_format as the parent group -- it is an error to mix zarr versions in the same hierarchy.

  Leading "/" characters from keys will be removed.

• overwrite (bool, default: False ) –

  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, AsyncArray | AsyncGroup]. –

Source code in zarr/core/group.py

async def create_hierarchy(
    self,
    nodes: dict[str, ArrayV2Metadata | ArrayV3Metadata | GroupMetadata],
    *,
    overwrite: bool = False,
) -> AsyncIterator[
    tuple[str, AsyncGroup | AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]]
]:
    """
    Create a hierarchy of arrays or groups rooted at this group.

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

    Explicitly specifying a root group, e.g. with ``nodes = {'': GroupMetadata()}`` is an error
    because this group instance is the root group.

    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
    ----------
    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 path of the group. The values are instances of ``GroupMetadata`` or ``ArrayMetadata``. Note that
        all values must have the same ``zarr_format`` as the parent group -- 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, AsyncArray | AsyncGroup].
    """
    # check that all the nodes have the same zarr_format as Self
    prefix = self.path
    nodes_parsed = {}
    for key, value in nodes.items():
        if value.zarr_format != self.metadata.zarr_format:
            msg = (
                "The zarr_format of the nodes must be the same as the parent group. "
                f"The node at {key} has zarr_format {value.zarr_format}, but the parent group"
                f" has zarr_format {self.metadata.zarr_format}."
            )
            raise ValueError(msg)
        if normalize_path(key) == "":
            msg = (
                "The input defines a root node, but a root node already exists, namely this Group instance."
                "It is an error to use this method to create a root node. "
                "Remove the root node from the input dict, or use a function like "
                "create_rooted_hierarchy to create a rooted hierarchy."
            )
            raise ValueError(msg)
        else:
            nodes_parsed[_join_paths([prefix, key])] = value

    async for key, node in create_hierarchy(
        store=self.store,
        nodes=nodes_parsed,
        overwrite=overwrite,
    ):
        if prefix == "":
            out_key = key
        else:
            out_key = key.removeprefix(prefix + "/")
        yield out_key, node

delitem async

delitem(key: str) -> None

Delete a group member.

Parameters:

• key (str) –

  Array or group name

Source code in zarr/core/group.py

async def delitem(self, key: str) -> None:
    """Delete a group member.

    Parameters
    ----------
    key : str
        Array or group name
    """
    store_path = self.store_path / key

    await store_path.delete_dir()
    if self.metadata.consolidated_metadata:
        self.metadata.consolidated_metadata.metadata.pop(key, None)
        await self._save_metadata()

empty async

empty(
    *, name: str, shape: tuple[int, ...], **kwargs: Any
) -> (
    AsyncArray[ArrayV2Metadata]
    | AsyncArray[ArrayV3Metadata]
)

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

Parameters:

• name (str) –

  Name of the array.

• shape (int or tuple of int) –

  Shape of the empty array.

• **kwargs (Any, default: {} ) –

  Keyword arguments passed to 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.

Source code in zarr/core/group.py

async def empty(
    self, *, name: str, shape: tuple[int, ...], **kwargs: Any
) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
    """Create an empty array with the specified shape in this Group. The contents will
    be filled with the array's fill value or zeros if no fill value is provided.

    Parameters
    ----------
    name : str
        Name of the array.
    shape : int or tuple of int
        Shape of the empty array.
    **kwargs
        Keyword arguments passed to [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 async_api.empty(shape=shape, store=self.store_path, path=name, **kwargs)

empty_like async

empty_like(
    *, name: str, data: ArrayLike, **kwargs: Any
) -> (
    AsyncArray[ArrayV2Metadata]
    | AsyncArray[ArrayV3Metadata]
)

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

Parameters:

• name (str) –

  Name of the array.

• data (array - like) –

  The array to create an empty array like.

• **kwargs (Any, default: {} ) –

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

Returns:

• AsyncArray –

  The new array.

Source code in zarr/core/group.py

async def empty_like(
    self, *, name: str, data: async_api.ArrayLike, **kwargs: Any
) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
    """Create an empty sub-array like `data`. The contents will be filled with
    the array's fill value or zeros if no fill value is provided.

    Parameters
    ----------
    name : str
        Name of the array.
    data : array-like
        The array to create an empty array like.
    **kwargs
        Keyword arguments passed to [zarr.api.asynchronous.create][].

    Returns
    -------
    AsyncArray
        The new array.
    """
    return await async_api.empty_like(a=data, store=self.store_path, path=name, **kwargs)

full async

full(
    *,
    name: str,
    shape: tuple[int, ...],
    fill_value: Any | None,
    **kwargs: Any,
) -> (
    AsyncArray[ArrayV2Metadata]
    | AsyncArray[ArrayV3Metadata]
)

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

Parameters:

• name (str) –

  Name of the array.

• shape (int or tuple of int) –

  Shape of the empty array.

• fill_value (scalar) –

  Value to fill the array with.

• **kwargs (Any, default: {} ) –

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

Returns:

• AsyncArray –

  The new array.

Source code in zarr/core/group.py

async def full(
    self, *, name: str, shape: tuple[int, ...], fill_value: Any | None, **kwargs: Any
) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
    """Create an array, with "fill_value" being used as the default value for uninitialized portions of the array.

    Parameters
    ----------
    name : str
        Name of the array.
    shape : int or tuple of int
        Shape of the empty array.
    fill_value : scalar
        Value to fill the array with.
    **kwargs
        Keyword arguments passed to [zarr.api.asynchronous.create][].

    Returns
    -------
    AsyncArray
        The new array.
    """
    return await async_api.full(
        shape=shape,
        fill_value=fill_value,
        store=self.store_path,
        path=name,
        **kwargs,
    )

full_like async

full_like(
    *, name: str, data: ArrayLike, **kwargs: Any
) -> (
    AsyncArray[ArrayV2Metadata]
    | AsyncArray[ArrayV3Metadata]
)

Create a sub-array like data filled with the fill_value of data .

Parameters:

• name (str) –

  Name of the array.

• data (array - like) –

  The array to create the new array like.

• **kwargs (Any, default: {} ) –

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

Returns:

• AsyncArray –

  The new array.

Source code in zarr/core/group.py

async def full_like(
    self, *, name: str, data: async_api.ArrayLike, **kwargs: Any
) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
    """Create a sub-array like `data` filled with the `fill_value` of `data` .

    Parameters
    ----------
    name : str
        Name of the array.
    data : array-like
        The array to create the new array like.
    **kwargs
        Keyword arguments passed to [zarr.api.asynchronous.create][].

    Returns
    -------
    AsyncArray
        The new array.
    """
    return await async_api.full_like(a=data, store=self.store_path, path=name, **kwargs)

get async

get(
    key: str, default: DefaultT | None = None
) -> AsyncArray[Any] | AsyncGroup | DefaultT | None

Obtain a group member, returning default if not found.

Parameters:

• key (str) –

  Group member name.

• default (object, default: None ) –

  Default value to return if key is not found (default: None).

Returns:

• object –

  Group member (AsyncArray or AsyncGroup) or default if not found.

Source code in zarr/core/group.py

async def get(
    self, key: str, default: DefaultT | None = None
) -> AsyncArray[Any] | AsyncGroup | DefaultT | None:
    """Obtain a group member, returning default if not found.

    Parameters
    ----------
    key : str
        Group member name.
    default : object
        Default value to return if key is not found (default: None).

    Returns
    -------
    object
        Group member (AsyncArray or AsyncGroup) or default if not found.
    """
    try:
        return await self.getitem(key)
    except KeyError:
        return default

getitem async

getitem(
    key: str,
) -> (
    AsyncArray[ArrayV2Metadata]
    | AsyncArray[ArrayV3Metadata]
    | AsyncGroup
)

Get a subarray or subgroup from the group.

Parameters:

• key (str) –

  Array or group name

Returns:

• AsyncArray or AsyncGroup –

Source code in zarr/core/group.py

async def getitem(
    self,
    key: str,
) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata] | AsyncGroup:
    """
    Get a subarray or subgroup from the group.

    Parameters
    ----------
    key : str
        Array or group name

    Returns
    -------
    AsyncArray or AsyncGroup
    """
    store_path = self.store_path / key
    logger.debug("key=%s, store_path=%s", key, store_path)

    # Consolidated metadata lets us avoid some I/O operations so try that first.
    if self.metadata.consolidated_metadata is not None:
        return self._getitem_consolidated(store_path, key, prefix=self.name)
    try:
        return await get_node(
            store=store_path.store, path=store_path.path, zarr_format=self.metadata.zarr_format
        )
    except FileNotFoundError as e:
        raise KeyError(key) from e

group_keys async

group_keys() -> AsyncGenerator[str, None]

Iterate over group names.

Source code in zarr/core/group.py

async def group_keys(self) -> AsyncGenerator[str, None]:
    """Iterate over group names."""
    async for key, _ in self.groups():
        yield key

group_values async

group_values() -> AsyncGenerator[AsyncGroup, None]

Iterate over group values.

Source code in zarr/core/group.py

async def group_values(self) -> AsyncGenerator[AsyncGroup, None]:
    """Iterate over group values."""
    async for _, group in self.groups():
        yield group

groups async

groups() -> AsyncGenerator[tuple[str, AsyncGroup], None]

Iterate over subgroups.

Source code in zarr/core/group.py

async def groups(self) -> AsyncGenerator[tuple[str, AsyncGroup], None]:
    """Iterate over subgroups."""
    async for name, value in self.members():
        if isinstance(value, AsyncGroup):
            yield name, value

info_complete async

info_complete() -> Any

Return all the information for a group.

This includes dynamic information like the number of child Groups or Arrays. If this group doesn't contain consolidated metadata then this will need to read from the backing Store.

Returns:

• GroupInfo –

Related

zarr.AsyncGroup.info

Source code in zarr/core/group.py

async def info_complete(self) -> Any:
    """
    Return all the information for a group.

    This includes dynamic information like the number
    of child Groups or Arrays. If this group doesn't contain consolidated
    metadata then this will need to read from the backing Store.

    Returns
    -------
    GroupInfo

    Related
    -------
    [zarr.AsyncGroup.info][]
    """
    members = [x[1].metadata async for x in self.members(max_depth=None)]
    return self._info(members=members)

keys async

keys() -> AsyncGenerator[str, None]

Iterate over member names.

Source code in zarr/core/group.py

async def keys(self) -> AsyncGenerator[str, None]:
    """Iterate over member names."""
    async for key, _ in self.members():
        yield key

members async

members(
    max_depth: int | None = 0,
    *,
    use_consolidated_for_children: bool = True,
) -> AsyncGenerator[
    tuple[
        str,
        AsyncArray[ArrayV2Metadata]
        | AsyncArray[ArrayV3Metadata]
        | AsyncGroup,
    ],
    None,
]

Returns an AsyncGenerator over the arrays and groups contained in this group. This method requires that store_path.store supports directory listing.

The results are not guaranteed to be ordered.

Parameters:

• max_depth (int, default: 0 ) –

  The maximum number of levels of the hierarchy to include. By default, (max_depth=0) only immediate children are included. Set max_depth=None to include all nodes, and some positive integer to consider children within that many levels of the root Group.

• use_consolidated_for_children (bool, default: True ) –

  Whether to use the consolidated metadata of child groups loaded from the store. Note that this only affects groups loaded from the store. If the current Group already has consolidated metadata, it will always be used.

Returns:

• path ( AsyncGenerator[tuple[str, AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata] | AsyncGroup], None] ) –

  A string giving the path to the target, relative to the Group self.

• value ( AsyncArray or AsyncGroup ) –

  The AsyncArray or AsyncGroup that is a child of self.

Source code in zarr/core/group.py

async def members(
    self,
    max_depth: int | None = 0,
    *,
    use_consolidated_for_children: bool = True,
) -> AsyncGenerator[
    tuple[str, AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata] | AsyncGroup],
    None,
]:
    """
    Returns an AsyncGenerator over the arrays and groups contained in this group.
    This method requires that `store_path.store` supports directory listing.

    The results are not guaranteed to be ordered.

    Parameters
    ----------
    max_depth : int, default 0
        The maximum number of levels of the hierarchy to include. By
        default, (``max_depth=0``) only immediate children are included. Set
        ``max_depth=None`` to include all nodes, and some positive integer
        to consider children within that many levels of the root Group.
    use_consolidated_for_children : bool, default True
        Whether to use the consolidated metadata of child groups loaded
        from the store. Note that this only affects groups loaded from the
        store. If the current Group already has consolidated metadata, it
        will always be used.

    Returns
    -------
    path:
        A string giving the path to the target, relative to the Group ``self``.
    value: AsyncArray or AsyncGroup
        The AsyncArray or AsyncGroup that is a child of ``self``.
    """
    if max_depth is not None and max_depth < 0:
        raise ValueError(f"max_depth must be None or >= 0. Got '{max_depth}' instead")
    async for item in self._members(
        max_depth=max_depth, use_consolidated_for_children=use_consolidated_for_children
    ):
        yield item

move async

move(source: str, dest: str) -> None

Move a sub-group or sub-array from one path to another.

Notes

Not implemented

Source code in zarr/core/group.py

async def move(self, source: str, dest: str) -> None:
    """Move a sub-group or sub-array from one path to another.

    Notes
    -----
    Not implemented
    """
    raise NotImplementedError

nmembers async

nmembers(max_depth: int | None = 0) -> int

Count the number of members in this group.

Parameters:

• max_depth (int, default: 0 ) –

  The maximum number of levels of the hierarchy to include. By default, (max_depth=0) only immediate children are included. Set max_depth=None to include all nodes, and some positive integer to consider children within that many levels of the root Group.

Returns:

• count ( int ) –

Source code in zarr/core/group.py

async def nmembers(
    self,
    max_depth: int | None = 0,
) -> int:
    """Count the number of members in this group.

    Parameters
    ----------
    max_depth : int, default 0
        The maximum number of levels of the hierarchy to include. By
        default, (``max_depth=0``) only immediate children are included. Set
        ``max_depth=None`` to include all nodes, and some positive integer
        to consider children within that many levels of the root Group.

    Returns
    -------
    count : int
    """
    # check if we can use consolidated metadata, which requires that we have non-None
    # consolidated metadata at all points in the hierarchy.
    if self.metadata.consolidated_metadata is not None:
        if max_depth is not None and max_depth < 0:
            raise ValueError(f"max_depth must be None or >= 0. Got '{max_depth}' instead")
        if max_depth is None:
            return len(self.metadata.consolidated_metadata.flattened_metadata)
        else:
            return len(
                [
                    x
                    for x in self.metadata.consolidated_metadata.flattened_metadata
                    if x.count("/") <= max_depth
                ]
            )
    # TODO: consider using aioitertools.builtins.sum for this
    # return await aioitertools.builtins.sum((1 async for _ in self.members()), start=0)
    n = 0
    async for _ in self.members(max_depth=max_depth):
        n += 1
    return n

ones async

ones(
    *, name: str, shape: tuple[int, ...], **kwargs: Any
) -> (
    AsyncArray[ArrayV2Metadata]
    | AsyncArray[ArrayV3Metadata]
)

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

Parameters:

• name (str) –

  Name of the array.

• shape (int or tuple of int) –

  Shape of the empty array.

• **kwargs (Any, default: {} ) –

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

Returns:

• AsyncArray –

  The new array.

Source code in zarr/core/group.py

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

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

    Returns
    -------
    AsyncArray
        The new array.
    """
    return await async_api.ones(shape=shape, store=self.store_path, path=name, **kwargs)

ones_like async

ones_like(
    *, name: str, data: ArrayLike, **kwargs: Any
) -> (
    AsyncArray[ArrayV2Metadata]
    | AsyncArray[ArrayV3Metadata]
)

Create a sub-array of ones like data.

Parameters:

• name (str) –

  Name of the array.

• data (array - like) –

  The array to create the new array like.

• **kwargs (Any, default: {} ) –

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

Returns:

• AsyncArray –

  The new array.

Source code in zarr/core/group.py

async def ones_like(
    self, *, name: str, data: async_api.ArrayLike, **kwargs: Any
) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
    """Create a sub-array of ones like `data`.

    Parameters
    ----------
    name : str
        Name of the array.
    data : array-like
        The array to create the new array like.
    **kwargs
        Keyword arguments passed to [zarr.api.asynchronous.create][].

    Returns
    -------
    AsyncArray
        The new array.
    """
    return await async_api.ones_like(a=data, store=self.store_path, path=name, **kwargs)

open async classmethod

open(
    store: StoreLike,
    zarr_format: ZarrFormat | None = 3,
    use_consolidated: bool | str | None = None,
) -> AsyncGroup

Open a new AsyncGroup

Parameters:

• store (StoreLike) –
• zarr_format ((2, 3), default: 2 ) –
• 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) and the Store supports it.

  To explicitly require consolidated metadata, set use_consolidated=True. In this case, if the Store doesn't support consolidation or consolidated metadata is not found, a ValueError exception is raised.

  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.

Source code in zarr/core/group.py

@classmethod
async def open(
    cls,
    store: StoreLike,
    zarr_format: ZarrFormat | None = 3,
    use_consolidated: bool | str | None = None,
) -> AsyncGroup:
    """Open a new AsyncGroup

    Parameters
    ----------
    store : StoreLike
    zarr_format : {2, 3}, optional
    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) and the Store supports it.

        To explicitly require consolidated metadata, set ``use_consolidated=True``.
        In this case, if the Store doesn't support consolidation or consolidated metadata is
        not found, a ``ValueError`` exception is raised.

        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.
    """
    store_path = await make_store_path(store)
    if not store_path.store.supports_consolidated_metadata:
        # Fail if consolidated metadata was requested but the Store doesn't support it
        if use_consolidated:
            store_name = type(store_path.store).__name__
            raise ValueError(
                f"The Zarr store in use ({store_name}) doesn't support consolidated metadata."
            )

        # if use_consolidated was None (optional), the Store dictates it doesn't want consolidation
        use_consolidated = False

    consolidated_key = ZMETADATA_V2_JSON

    if (zarr_format == 2 or zarr_format is None) and isinstance(use_consolidated, str):
        consolidated_key = use_consolidated

    if zarr_format == 2:
        paths = [store_path / ZGROUP_JSON, store_path / ZATTRS_JSON]
        if use_consolidated or use_consolidated is None:
            paths.append(store_path / consolidated_key)

        zgroup_bytes, zattrs_bytes, *rest = await asyncio.gather(
            *[path.get() for path in paths]
        )
        if zgroup_bytes is None:
            raise FileNotFoundError(store_path)

        if use_consolidated or use_consolidated is None:
            maybe_consolidated_metadata_bytes = rest[0]

        else:
            maybe_consolidated_metadata_bytes = None

    elif zarr_format == 3:
        zarr_json_bytes = await (store_path / ZARR_JSON).get()
        if zarr_json_bytes is None:
            raise FileNotFoundError(store_path)
    elif zarr_format is None:
        (
            zarr_json_bytes,
            zgroup_bytes,
            zattrs_bytes,
            maybe_consolidated_metadata_bytes,
        ) = await asyncio.gather(
            (store_path / ZARR_JSON).get(),
            (store_path / ZGROUP_JSON).get(),
            (store_path / ZATTRS_JSON).get(),
            (store_path / str(consolidated_key)).get(),
        )
        if zarr_json_bytes is not None and zgroup_bytes is not None:
            # warn and favor v3
            msg = f"Both zarr.json (Zarr format 3) and .zgroup (Zarr format 2) metadata objects exist at {store_path}. Zarr format 3 will be used."
            warnings.warn(msg, category=ZarrUserWarning, stacklevel=1)
        if zarr_json_bytes is None and zgroup_bytes is None:
            raise FileNotFoundError(
                f"could not find zarr.json or .zgroup objects in {store_path}"
            )
        # set zarr_format based on which keys were found
        if zarr_json_bytes is not None:
            zarr_format = 3
        else:
            zarr_format = 2
    else:
        msg = f"Invalid value for 'zarr_format'. Expected 2, 3, or None. Got '{zarr_format}'."  # type: ignore[unreachable]
        raise MetadataValidationError(msg)

    if zarr_format == 2:
        # this is checked above, asserting here for mypy
        assert zgroup_bytes is not None

        if use_consolidated and maybe_consolidated_metadata_bytes is None:
            # the user requested consolidated metadata, but it was missing
            raise ValueError(consolidated_key)

        elif use_consolidated is False:
            # the user explicitly opted out of consolidated_metadata.
            # Discard anything we might have read.
            maybe_consolidated_metadata_bytes = None

        return cls._from_bytes_v2(
            store_path, zgroup_bytes, zattrs_bytes, maybe_consolidated_metadata_bytes
        )
    else:
        # V3 groups are comprised of a zarr.json object
        assert zarr_json_bytes is not None
        if not isinstance(use_consolidated, bool | None):
            raise TypeError("use_consolidated must be a bool or None for Zarr format 3.")

        return cls._from_bytes_v3(
            store_path,
            zarr_json_bytes,
            use_consolidated=use_consolidated,
        )

require_array async

require_array(
    name: str,
    *,
    shape: ShapeLike,
    dtype: DTypeLike = None,
    exact: bool = False,
    **kwargs: Any,
) -> (
    AsyncArray[ArrayV2Metadata]
    | AsyncArray[ArrayV3Metadata]
)

Obtain an array, creating if it doesn't exist.

Other kwargs are as per zarr.AsyncGroup.create_dataset.

Parameters:

• name (str) –

  Array name.

• shape (int or tuple of ints) –

  Array shape.

• dtype (str or dtype, default: None ) –

  NumPy dtype.

• exact (bool, default: False ) –

  If True, require dtype to match exactly. If false, require dtype can be cast from array dtype.

Returns:

• a ( AsyncArray ) –

Source code in zarr/core/group.py

async def require_array(
    self,
    name: str,
    *,
    shape: ShapeLike,
    dtype: npt.DTypeLike = None,
    exact: bool = False,
    **kwargs: Any,
) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
    """Obtain an array, creating if it doesn't exist.

    Other `kwargs` are as per [zarr.AsyncGroup.create_dataset][].

    Parameters
    ----------
    name : str
        Array name.
    shape : int or tuple of ints
        Array shape.
    dtype : str or dtype, optional
        NumPy dtype.
    exact : bool, optional
        If True, require `dtype` to match exactly. If false, require
        `dtype` can be cast from array dtype.

    Returns
    -------
    a : AsyncArray
    """
    try:
        ds = await self.getitem(name)
        if not isinstance(ds, AsyncArray):
            raise TypeError(f"Incompatible object ({ds.__class__.__name__}) already exists")

        shape = parse_shapelike(shape)
        if shape != ds.shape:
            raise TypeError(f"Incompatible shape ({ds.shape} vs {shape})")

        dtype = np.dtype(dtype)
        if exact:
            if ds.dtype != dtype:
                raise TypeError(f"Incompatible dtype ({ds.dtype} vs {dtype})")
        else:
            if not np.can_cast(ds.dtype, dtype):
                raise TypeError(f"Incompatible dtype ({ds.dtype} vs {dtype})")
    except KeyError:
        ds = await self.create_array(name, shape=shape, dtype=dtype, **kwargs)

    return ds

require_dataset async

require_dataset(
    name: str,
    *,
    shape: tuple[int, ...],
    dtype: DTypeLike = None,
    exact: bool = False,
    **kwargs: Any,
) -> (
    AsyncArray[ArrayV2Metadata]
    | AsyncArray[ArrayV3Metadata]
)

Obtain an array, creating if it doesn't exist.

Deprecated

AsyncGroup.require_dataset() is deprecated since v3.0.0 and will be removed in v3.1.0. Use AsyncGroup.require_dataset instead.

Arrays are known as "datasets" in HDF5 terminology. For compatibility with h5py, Zarr groups also implement the zarr.AsyncGroup.create_dataset method.

Other kwargs are as per zarr.AsyncGroup.create_dataset.

Parameters:

• name (str) –

  Array name.

• shape (int or tuple of ints) –

  Array shape.

• dtype (str or dtype, default: None ) –

  NumPy dtype.

• exact (bool, default: False ) –

  If True, require dtype to match exactly. If false, require dtype can be cast from array dtype.

Returns:

• a ( AsyncArray ) –

Source code in zarr/core/group.py

@deprecated("Use AsyncGroup.require_array instead.", category=ZarrDeprecationWarning)
async def require_dataset(
    self,
    name: str,
    *,
    shape: tuple[int, ...],
    dtype: npt.DTypeLike = None,
    exact: bool = False,
    **kwargs: Any,
) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
    """Obtain an array, creating if it doesn't exist.

    !!! warning "Deprecated"
        `AsyncGroup.require_dataset()` is deprecated since v3.0.0 and will be removed in v3.1.0.
        Use `AsyncGroup.require_dataset` instead.

    Arrays are known as "datasets" in HDF5 terminology. For compatibility
    with h5py, Zarr groups also implement the [zarr.AsyncGroup.create_dataset][] method.

    Other `kwargs` are as per [zarr.AsyncGroup.create_dataset][].

    Parameters
    ----------
    name : str
        Array name.
    shape : int or tuple of ints
        Array shape.
    dtype : str or dtype, optional
        NumPy dtype.
    exact : bool, optional
        If True, require `dtype` to match exactly. If false, require
        `dtype` can be cast from array dtype.

    Returns
    -------
    a : AsyncArray
    """
    return await self.require_array(name, shape=shape, dtype=dtype, exact=exact, **kwargs)

require_group async

require_group(
    name: str, overwrite: bool = False
) -> AsyncGroup

Obtain a sub-group, creating one if it doesn't exist.

Parameters:

• name (str) –

  Group name.

• overwrite (bool, default: False ) –

  Overwrite any existing group with given name if present.

Returns:

• g ( AsyncGroup ) –

Source code in zarr/core/group.py

async def require_group(self, name: str, overwrite: bool = False) -> AsyncGroup:
    """Obtain a sub-group, creating one if it doesn't exist.

    Parameters
    ----------
    name : str
        Group name.
    overwrite : bool, optional
        Overwrite any existing group with given `name` if present.

    Returns
    -------
    g : AsyncGroup
    """
    if overwrite:
        # TODO: check that overwrite=True errors if an array exists where the group is being created
        grp = await self.create_group(name, overwrite=True)
    else:
        try:
            item: (
                AsyncGroup | AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]
            ) = await self.getitem(name)
            if not isinstance(item, AsyncGroup):
                raise TypeError(
                    f"Incompatible object ({item.__class__.__name__}) already exists"
                )
            assert isinstance(item, AsyncGroup)  # make mypy happy
            grp = item
        except KeyError:
            grp = await self.create_group(name)
    return grp

require_groups async

require_groups(*names: str) -> tuple[AsyncGroup, ...]

Convenience method to require multiple groups in a single call.

Parameters:

• *names (str, default: () ) –

  Group names.

Returns:

• Tuple[AsyncGroup, ...] –

Source code in zarr/core/group.py

async def require_groups(self, *names: str) -> tuple[AsyncGroup, ...]:
    """Convenience method to require multiple groups in a single call.

    Parameters
    ----------
    *names : str
        Group names.

    Returns
    -------
    Tuple[AsyncGroup, ...]
    """
    if not names:
        return ()
    return tuple(await asyncio.gather(*(self.require_group(name) for name in names)))

setitem async

setitem(key: str, value: Any) -> None

Fastpath for creating a new array New arrays will be created with default array settings for the array type.

Parameters:

• key (str) –

  Array name

• value (array - like) –

  Array data

Source code in zarr/core/group.py

async def setitem(self, key: str, value: Any) -> None:
    """
    Fastpath for creating a new array
    New arrays will be created with default array settings for the array type.

    Parameters
    ----------
    key : str
        Array name
    value : array-like
        Array data
    """
    path = self.store_path / key
    await async_api.save_array(
        store=path, arr=value, zarr_format=self.metadata.zarr_format, overwrite=True
    )

tree async

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

Return a tree-like representation of a hierarchy.

This requires the optional rich dependency.

Parameters:

• expand (bool, default: None ) –

  This keyword is not yet supported. A NotImplementedError is raised if it's used.

• level (int, default: None ) –

  The maximum depth below this Group to display in the tree.

Returns:

• TreeRepr –

  A pretty-printable object displaying the hierarchy.

Source code in zarr/core/group.py

async def tree(self, expand: bool | None = None, level: int | None = None) -> Any:
    """
    Return a tree-like representation of a hierarchy.

    This requires the optional ``rich`` dependency.

    Parameters
    ----------
    expand : bool, optional
        This keyword is not yet supported. A NotImplementedError is raised if
        it's used.
    level : int, optional
        The maximum depth below this Group to display in the tree.

    Returns
    -------
    TreeRepr
        A pretty-printable object displaying the hierarchy.
    """
    from zarr.core._tree import group_tree_async

    if expand is not None:
        raise NotImplementedError("'expand' is not yet implemented.")
    return await group_tree_async(self, max_depth=level)

update_attributes async

update_attributes(
    new_attributes: dict[str, Any],
) -> AsyncGroup

Update group attributes.

Parameters:

• new_attributes (dict) –

  New attributes to set on the group.

Returns:

• self ( AsyncGroup ) –

Source code in zarr/core/group.py

async def update_attributes(self, new_attributes: dict[str, Any]) -> AsyncGroup:
    """Update group attributes.

    Parameters
    ----------
    new_attributes : dict
        New attributes to set on the group.

    Returns
    -------
    self : AsyncGroup
    """
    self.metadata.attributes.update(new_attributes)

    # Write new metadata
    await self._save_metadata()

    return self

zeros async

zeros(
    *, name: str, shape: tuple[int, ...], **kwargs: Any
) -> (
    AsyncArray[ArrayV2Metadata]
    | AsyncArray[ArrayV3Metadata]
)

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

Parameters:

• name (str) –

  Name of the array.

• shape (int or tuple of int) –

  Shape of the empty array.

• **kwargs (Any, default: {} ) –

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

Returns:

• AsyncArray –

  The new array.

Source code in zarr/core/group.py

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

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

    Returns
    -------
    AsyncArray
        The new array.
    """
    return await async_api.zeros(shape=shape, store=self.store_path, path=name, **kwargs)

zeros_like async

zeros_like(
    *, name: str, data: ArrayLike, **kwargs: Any
) -> (
    AsyncArray[ArrayV2Metadata]
    | AsyncArray[ArrayV3Metadata]
)

Create a sub-array of zeros like data.

Parameters:

• name (str) –

  Name of the array.

• data (array - like) –

  The array to create the new array like.

• **kwargs (Any, default: {} ) –

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

Returns:

• AsyncArray –

  The new array.

Source code in zarr/core/group.py

async def zeros_like(
    self, *, name: str, data: async_api.ArrayLike, **kwargs: Any
) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
    """Create a sub-array of zeros like `data`.

    Parameters
    ----------
    name : str
        Name of the array.
    data : array-like
        The array to create the new array like.
    **kwargs
        Keyword arguments passed to [zarr.api.asynchronous.create][].

    Returns
    -------
    AsyncArray
        The new array.
    """
    return await async_api.zeros_like(a=data, store=self.store_path, path=name, **kwargs)