zarr.creation
=============

.. py:module:: zarr.creation

.. autoapi-nested-parse::

   Helpers for creating arrays.

   .. warning::

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

   ..
       !! processed by numpydoc !!


Functions
---------

.. autoapisummary::

   zarr.creation.array
   zarr.creation.create
   zarr.creation.empty
   zarr.creation.empty_like
   zarr.creation.full
   zarr.creation.full_like
   zarr.creation.ones
   zarr.creation.ones_like
   zarr.creation.open_array
   zarr.creation.open_like
   zarr.creation.zeros
   zarr.creation.zeros_like


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

.. py:function:: array(data: numpy.typing.ArrayLike | zarr.core.array.Array, **kwargs: Any) -> zarr.core.array.Array

   
   Create an array filled with `data`.


   :Parameters:

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

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



   :Returns:

       **array** : Array
           The new array.











   ..
       !! processed by numpydoc !!

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

   
   Create an array.


   :Parameters:

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

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

       **dtype** : str or dtype, optional
           NumPy dtype.

       **compressor** : Codec, optional
           Primary compressor to compress chunk data.
           Zarr format 2 only. Zarr format 3 arrays should use ``codecs`` instead.
           
           If neither ``compressor`` nor ``filters`` are provided, the default compressor
           :class:`zarr.codecs.ZstdCodec` is used.
           
           If ``compressor`` is set to ``None``, no compression is used.

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

       **order** : {'C', 'F'}, optional
           Deprecated in favor of the ``config`` keyword argument.
           Pass ``{'order': <value>}`` to ``create`` instead of using this parameter.
           Memory layout to be used within each chunk.
           If not specified, the ``array.order`` parameter in the global config will be used.

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

       **synchronizer** : object, optional
           Array synchronizer.

       **overwrite** : bool, optional
           If True, delete all pre-existing data in ``store`` at ``path`` before
           creating the array.

       **path** : str, optional
           Path under which array is stored.

       **chunk_store** : StoreLike or None, default=None
           Separate storage for chunks. If not provided, ``store`` will be used
           for storage of both chunks and metadata.

       **filters** : Iterable[Codec] | Literal["auto"], optional
           Iterable of filters to apply to each chunk of the array, in order, before serializing that
           chunk to bytes.
           
           For Zarr format 3, a "filter" is a codec that takes an array and returns an array,
           and these values must be instances of :class:`zarr.abc.codec.ArrayArrayCodec`, or a
           dict representations of :class:`zarr.abc.codec.ArrayArrayCodec`.
           
           For Zarr format 2, a "filter" can be any numcodecs codec; you should ensure that the
           the order if your filters is consistent with the behavior of each filter.
           
           The default value of ``"auto"`` instructs Zarr to use a default used based on the data
           type of the array and the Zarr format specified. For all data types in Zarr V3, and most
           data types in Zarr V2, the default filters are empty. The only cases where default filters
           are not empty is when the Zarr format is 2, and the data type is a variable-length data type like
           :class:`zarr.dtype.VariableLengthUTF8` or :class:`zarr.dtype.VariableLengthUTF8`. In these cases,
           the default filters contains a single element which is a codec specific to that particular data type.
           
           To create an array with no filters, provide an empty iterable or the value ``None``.

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

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

       **read_only** : bool, optional
           True if array should be protected against modification.

       **object_codec** : Codec, optional
           A codec to encode object arrays, only needed if dtype=object.

       **dimension_separator** : {'.', '/'}, optional
           Separator placed between the dimensions of a chunk.
           Zarr format 2 only. Zarr format 3 arrays should use ``chunk_key_encoding`` instead.

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

       **zarr_format** : {2, 3, None}, optional
           The Zarr format to use when creating an array. The default is ``None``,
           which instructs Zarr to choose the default Zarr format value defined in the
           runtime configuration.

       **meta_array** : array-like, optional
           Not implemented.

       **attributes** : dict[str, JSON], optional
           A dictionary of user attributes to store with the array.

       **chunk_shape** : int or tuple of ints, optional
           The shape of the Array's chunks (default is None).
           Zarr format 3 only. Zarr format 2 arrays should use `chunks` instead.

       **chunk_key_encoding** : ChunkKeyEncoding, optional
           A specification of how the chunk keys are represented in storage.
           Zarr format 3 only. Zarr format 2 arrays should use `dimension_separator` instead.
           Default is ``("default", "/")``.

       **codecs** : Sequence of Codecs or dicts, optional
           An iterable of Codec or dict serializations of Codecs. Zarr V3 only.
           
           The elements of ``codecs`` specify the transformation from array values to stored bytes.
           Zarr format 3 only. Zarr format 2 arrays should use ``filters`` and ``compressor`` instead.
           
           If no codecs are provided, default codecs will be used based on the data type of the array.
           For most data types, the default codecs are the tuple ``(BytesCodec(), ZstdCodec())``;
           data types that require a special :class:`zarr.abc.codec.ArrayBytesCodec`, like variable-length strings or bytes,
           will use the :class:`zarr.abc.codec.ArrayBytesCodec` required for the data type instead of :class:`zarr.codecs.BytesCodec`.

       **dimension_names** : Iterable[str | None] | None = None
           An iterable of dimension names. Zarr format 3 only.

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

       **config** : ArrayConfigLike, optional
           Runtime configuration of the array. If provided, will override the
           default values from `zarr.config.array`.



   :Returns:

       **z** : Array
           The array.











   ..
       !! processed by numpydoc !!

.. py:function:: empty(shape: tuple[int, Ellipsis], **kwargs: Any) -> zarr.core.array.Array

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


   :Parameters:

       **shape** : int or tuple of int
           Shape of the empty array.

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



   :Returns:

       Array
           The new array.








   .. rubric:: Notes

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



   ..
       !! processed by numpydoc !!

.. py:function:: empty_like(a: zarr.api.asynchronous.ArrayLike, **kwargs: Any) -> zarr.core.array.Array

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


   :Parameters:

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

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



   :Returns:

       Array
           The new array.








   .. rubric:: Notes

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



   ..
       !! processed by numpydoc !!

.. py:function:: full(shape: tuple[int, Ellipsis], fill_value: Any, **kwargs: Any) -> zarr.core.array.Array

   
   Create an array with a default fill value.


   :Parameters:

       **shape** : int or tuple of int
           Shape of the empty array.

       **fill_value** : scalar
           Fill value.

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



   :Returns:

       Array
           The new array.











   ..
       !! processed by numpydoc !!

.. py:function:: full_like(a: zarr.api.asynchronous.ArrayLike, **kwargs: Any) -> zarr.core.array.Array

   
   Create a filled array like another array.


   :Parameters:

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

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



   :Returns:

       Array
           The new array.











   ..
       !! processed by numpydoc !!

.. py:function:: ones(shape: tuple[int, Ellipsis], **kwargs: Any) -> zarr.core.array.Array

   
   Create an array with a fill value of one.


   :Parameters:

       **shape** : int or tuple of int
           Shape of the empty array.

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



   :Returns:

       Array
           The new array.











   ..
       !! processed by numpydoc !!

.. py:function:: ones_like(a: zarr.api.asynchronous.ArrayLike, **kwargs: Any) -> zarr.core.array.Array

   
   Create an array of ones like another array.


   :Parameters:

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

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



   :Returns:

       Array
           The new array.











   ..
       !! processed by numpydoc !!

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

   
   Open an array using file-mode-like semantics.


   :Parameters:

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

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

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

       **path** : str, optional
           Path in store to array.

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

       **\*\*kwargs**
           Any keyword arguments to pass to :func:`create`.



   :Returns:

       AsyncArray
           The opened array.











   ..
       !! processed by numpydoc !!

.. py:function:: open_like(a: zarr.api.asynchronous.ArrayLike, path: str, **kwargs: Any) -> zarr.core.array.Array

   
   Open a persistent array like another array.


   :Parameters:

       **a** : Array
           The shape and data-type of a define these same attributes of the returned array.

       **path** : str
           The path to the new array.

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



   :Returns:

       AsyncArray
           The opened array.











   ..
       !! processed by numpydoc !!

.. py:function:: zeros(shape: tuple[int, Ellipsis], **kwargs: Any) -> zarr.core.array.Array

   
   Create an array with a fill value of zero.


   :Parameters:

       **shape** : int or tuple of int
           Shape of the empty array.

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



   :Returns:

       Array
           The new array.











   ..
       !! processed by numpydoc !!

.. py:function:: zeros_like(a: zarr.api.asynchronous.ArrayLike, **kwargs: Any) -> zarr.core.array.Array

   
   Create an array of zeros like another array.


   :Parameters:

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

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



   :Returns:

       Array
           The new array.











   ..
       !! processed by numpydoc !!

