zarr.convenience
================

.. py:module:: zarr.convenience

.. autoapi-nested-parse::

   Convenience helpers.

   .. warning::

       This sub-module is deprecated. All functions here are defined
       in the top level zarr namespace instead.

   ..
       !! processed by numpydoc !!


Functions
---------

.. autoapisummary::

   zarr.convenience.consolidate_metadata
   zarr.convenience.copy
   zarr.convenience.copy_all
   zarr.convenience.copy_store
   zarr.convenience.load
   zarr.convenience.open
   zarr.convenience.open_consolidated
   zarr.convenience.save
   zarr.convenience.save_array
   zarr.convenience.save_group
   zarr.convenience.tree


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

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

   
   Consolidate the metadata of all nodes in a hierarchy.

   Upon completion, the metadata of the root node in the Zarr hierarchy will be
   updated to include all the metadata of child nodes.

   :Parameters:

       **store** : StoreLike
           The store-like object whose metadata you wish to consolidate.

       **path** : str, optional
           A path to a group in the store to consolidate at. Only children
           below that group will be consolidated.
           
           By default, the root node is used so all the metadata in the
           store is consolidated.

       **zarr_format** : {2, 3, None}, optional
           The zarr format of the hierarchy. By default the zarr format
           is inferred.



   :Returns:

       group: Group
           The group, with the ``consolidated_metadata`` field set to include
           the metadata of each child node.











   ..
       !! processed by numpydoc !!

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

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

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

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

   
   Load data from an array or group into memory.


   :Parameters:

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

       **path** : str or None, optional
           The path within the store from which to load.



   :Returns:

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







   .. seealso::

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

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



   ..
       !! processed by numpydoc !!

.. py:function:: open(store: zarr.storage.StoreLike | None = None, *, mode: zarr.core.common.AccessModeLiteral = 'a', zarr_version: zarr.core.common.ZarrFormat | None = None, zarr_format: zarr.core.common.ZarrFormat | None = None, path: str | None = None, storage_options: dict[str, Any] | None = None, **kwargs: Any) -> zarr.core.array.Array | zarr.core.group.Group

   
   Open a group or array using file-mode-like semantics.


   :Parameters:

       **store** : Store or str, optional
           Store or path to directory in file system or name of zip file.

       **mode** : {'r', 'r+', 'a', 'w', 'w-'}, optional
           Persistence mode: 'r' means read only (must exist); 'r+' means
           read/write (must exist); 'a' means read/write (create if doesn't
           exist); 'w' means create (overwrite if exists); 'w-' means create
           (fail if exists).

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

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

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

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



   :Returns:

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











   ..
       !! processed by numpydoc !!

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

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
















   ..
       !! processed by numpydoc !!

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

   
   Save an array or group of arrays to the local file system.


   :Parameters:

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

       **\*args** : ndarray
           NumPy arrays with data to save.

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

       **path** : str or None, optional
           The path within the group where the arrays will be saved.

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














   ..
       !! processed by numpydoc !!

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

   
   Save a NumPy array to the local file system.

   Follows a similar API to the NumPy save() function.

   :Parameters:

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

       **arr** : ndarray
           NumPy array with data to save.

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

       **path** : str or None, optional
           The path within the store where the array will be saved.

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

       **\*\*kwargs**
           Passed through to :func:`create`, e.g., compressor.














   ..
       !! processed by numpydoc !!

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

   
   Save several NumPy arrays to the local file system.

   Follows a similar API to the NumPy savez()/savez_compressed() functions.

   :Parameters:

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

       **\*args** : ndarray
           NumPy arrays with data to save.

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

       **path** : str or None, optional
           Path within the store where the group will be saved.

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

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














   ..
       !! processed by numpydoc !!

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

   
   Provide a rich display of the hierarchy.

   .. deprecated:: 3.0.0
       `zarr.tree()` is deprecated and will be removed in a future release.
       Use `group.tree()` instead.

   :Parameters:

       **grp** : Group
           Zarr or h5py group.

       **expand** : bool, optional
           Only relevant for HTML representation. If True, tree will be fully expanded.

       **level** : int, optional
           Maximum depth to descend into hierarchy.



   :Returns:

       TreeRepr
           A pretty-printable object displaying the hierarchy.











   ..
       !! processed by numpydoc !!

