Skip to main content

__Back to top __ `Ctrl`+`K`

  * Quickstart 
  * User guide 
  * API reference 
  * Release notes 
  * Developer’s Guide 
  * More 
    * About 

__ Search `Ctrl`+`K`

______

  * [__ GitHub](https://github.com/zarr-developers/zarr-python "GitHub")
  * [__ Bluesky](https://bsky.app/profile/zarr.dev "Bluesky")
  * [__ Mastodon](https://fosstodon.org/@zarr "Mastodon")
  * [](https://zarr.dev/ "Zarr Dev")

__ Search `Ctrl`+`K`

  * Quickstart 
  * User guide 
  * API reference 
  * Release notes 
  * Developer’s Guide 
  * About 

______

  * [__ GitHub](https://github.com/zarr-developers/zarr-python "GitHub")
  * [__ Bluesky](https://bsky.app/profile/zarr.dev "Bluesky")
  * [__ Mastodon](https://fosstodon.org/@zarr "Mastodon")
  * [](https://zarr.dev/ "Zarr Dev")

# Zarr-Python#

## Quickstart#

Welcome to the Zarr-Python Quickstart guide! This page will help you get up
and running with the Zarr library in Python to efficiently manage and analyze
multi-dimensional arrays.

Zarr is a powerful library for storage of n-dimensional arrays, supporting
chunking, compression, and various backends, making it a versatile choice for
scientific and large-scale data.

### Installation#

Zarr requires Python 3.11 or higher. You can install it via pip:

    
    
    pip install zarr
    

or conda:

    
    
    conda install --channel conda-forge zarr
    

### Creating an Array#

To get started, you can create a simple Zarr array:

    
    
    >>> import zarr
    >>> import numpy as np
    >>>
    >>> # Create a 2D Zarr array
    >>> z = zarr.create_array(
    ...    store="data/example-1.zarr",
    ...    shape=(100, 100),
    ...    chunks=(10, 10),
    ...    dtype="f4"
    ... )
    >>>
    >>> # Assign data to the array
    >>> z[:, :] = np.random.random((100, 100))
    >>> z.info
    Type               : Array
    Zarr format        : 3
    Data type          : DataType.float32
    Shape              : (100, 100)
    Chunk shape        : (10, 10)
    Order              : C
    Read-only          : False
    Store type         : LocalStore
    Codecs             : [{'endian': <Endian.little: 'little'>}, {'level': 0, 'checksum': False}]
    No. bytes          : 40000 (39.1K)
    

Here, we created a 2D array of shape `(100, 100)`, chunked into blocks of
`(10, 10)`, and filled it with random floating-point data. This array was
written to a `LocalStore` in the `data/example-1.zarr` directory.

#### Compression and Filters#

Zarr supports data compression and filters. For example, to use Blosc
compression:

    
    
    >>> z = zarr.create_array(
    ...    "data/example-3.zarr",
    ...    mode="w", shape=(100, 100),
    ...    chunks=(10, 10), dtype="f4",
    ...    compressors=zarr.codecs.BloscCodec(cname="zstd", clevel=3, shuffle=zarr.codecs.BloscShuffle.shuffle)
    ... )
    >>> z[:, :] = np.random.random((100, 100))
    >>>
    >>> z.info
    Type               : Array
    Zarr format        : 3
    Data type          : DataType.float32
    Shape              : (100, 100)
    Chunk shape        : (10, 10)
    Order              : C
    Read-only          : False
    Store type         : LocalStore
    Codecs             : [{'endian': <Endian.little: 'little'>}, {'level': 0, 'checksum': False}]
    No. bytes          : 40000 (39.1K)
    

This compresses the data using the Zstandard codec with shuffle enabled for
better compression.

### Hierarchical Groups#

Zarr allows you to create hierarchical groups, similar to directories:

    
    
    >>> # Create nested groups and add arrays
    >>> root = zarr.group("data/example-2.zarr")
    >>> foo = root.create_group(name="foo")
    >>> bar = root.create_array(
    ...     name="bar", shape=(100, 10), chunks=(10, 10), dtype="f4"
    ... )
    >>> spam = foo.create_array(name="spam", shape=(10,), dtype="i4")
    >>>
    >>> # Assign values
    >>> bar[:, :] = np.random.random((100, 10))
    >>> spam[:] = np.arange(10)
    >>>
    >>> # print the hierarchy
    >>> root.tree()
    /
    ├── bar (100, 10) float32
    └── foo
        └── spam (10,) int32
    

This creates a group with two datasets: `foo` and `bar`.

#### Batch Hierarchy Creation#

Zarr provides tools for creating a collection of arrays and groups with a
single function call. Suppose we want to copy existing groups and arrays into
a new storage backend:

    
    
    >>> # Create nested groups and add arrays
    >>> root = zarr.group("data/example-3.zarr", attributes={'name': 'root'})
    >>> foo = root.create_group(name="foo")
    >>> bar = root.create_array(
    ...     name="bar", shape=(100, 10), chunks=(10, 10), dtype="f4"
    ... )
    >>> nodes = {'': root.metadata} | {k: v.metadata for k,v in root.members()}
    >>> print(nodes)
    >>> from zarr.storage import MemoryStore
    >>> new_nodes = dict(zarr.create_hierarchy(store=MemoryStore(), nodes=nodes))
    >>> new_root = new_nodes['']
    >>> assert new_root.attrs == root.attrs
    

Note that `zarr.create_hierarchy()` will only initialize arrays and groups –
copying array data must be done in a separate step.

### Persistent Storage#

Zarr supports persistent storage to disk or cloud-compatible backends. While
examples above utilized a `zarr.storage.LocalStore`, a number of other storage
options are available.

Zarr integrates seamlessly with cloud object storage such as Amazon S3 and
Google Cloud Storage using external libraries like
[s3fs](https://s3fs.readthedocs.io) or [gcsfs](https://gcsfs.readthedocs.io):

    
    
    >>> import s3fs 
    >>>
    >>> z = zarr.create_array("s3://example-bucket/foo", mode="w", shape=(100, 100), chunks=(10, 10), dtype="f4") 
    >>> z[:, :] = np.random.random((100, 100)) 
    

A single-file store can also be created using the the `zarr.storage.ZipStore`:

    
    
    >>> # Store the array in a ZIP file
    >>> store = zarr.storage.ZipStore("data/example-3.zip", mode='w')
    >>>
    >>> z = zarr.create_array(
    ...     store=store,
    ...     mode="w",
    ...     shape=(100, 100),
    ...     chunks=(10, 10),
    ...     dtype="f4"
    ... )
    >>>
    >>> # write to the array
    >>> z[:, :] = np.random.random((100, 100))
    >>>
    >>> # the ZipStore must be explicitly closed
    >>> store.close()
    

To open an existing array from a ZIP file:

    
    
    >>> # Open the ZipStore in read-only mode
    >>> store = zarr.storage.ZipStore("data/example-3.zip", read_only=True)
    >>>
    >>> z = zarr.open_array(store, mode='r')
    >>>
    >>> # read the data as a NumPy Array
    >>> z[:]
    array([[0.66734236, 0.15667458, 0.98720884, ..., 0.36229587, 0.67443246,
            0.34315267],
        [0.65787303, 0.9544212 , 0.4830079 , ..., 0.33097172, 0.60423803,
            0.45621237],
        [0.27632037, 0.9947008 , 0.42434934, ..., 0.94860053, 0.6226942 ,
            0.6386924 ],
        ...,
        [0.12854576, 0.934397  , 0.19524333, ..., 0.11838563, 0.4967675 ,
            0.43074256],
        [0.82029045, 0.4671437 , 0.8090906 , ..., 0.7814118 , 0.42650765,
            0.95929915],
        [0.4335856 , 0.7565437 , 0.7828931 , ..., 0.48119593, 0.66220033,
            0.6652362 ]], shape=(100, 100), dtype=float32)
    

Read more about Zarr’s storage options in the User Guide.

### Next Steps#

Now that you’re familiar with the basics, explore the following resources:

  * [User Guide](user-guide)

  * [API Reference](api)

## User guide#

### Installation#

#### Required dependencies#

Required dependencies include:

  * [Python](https://docs.python.org/3/) (3.11 or later)

  * [packaging](https://packaging.pypa.io) (22.0 or later)

  * [numpy](https://numpy.org) (1.26 or later)

  * [numcodecs[crc32c]](https://numcodecs.readthedocs.io) (0.14 or later)

  * [typing_extensions](https://typing-extensions.readthedocs.io) (4.9 or later)

  * [donfig](https://donfig.readthedocs.io) (0.8 or later)

#### pip#

Zarr is available on [PyPI](https://pypi.org/project/zarr/). Install it using
`pip`:

    
    
    $ pip install zarr
    

There are a number of optional dependency groups you can install for extra
functionality. These can be installed using `pip install "zarr[<extra>]"`,
e.g. `pip install "zarr[gpu]"`

  * `gpu`: support for GPUs

  * `remote`: support for reading/writing to remote data stores

Additional optional dependencies include `rich`, `universal_pathlib`. These
must be installed separately.

#### conda#

Zarr is also published to [conda-forge](https://conda-forge.org). Install it
using `conda`:

    
    
    $ conda install -c conda-forge zarr
    

Conda does not support optional dependencies, so you will have to manually
install any packages needed to enable extra functionality.

#### Dependency support#

Zarr has endorsed [Scientific-Python SPEC 0](https://scientific-
python.org/specs/spec-0000/) and now follows the version support window as
outlined below:

  * Python: 36 months after initial release

  * Core package dependencies (e.g. NumPy): 24 months after initial release

#### Development#

To install the latest development version of Zarr, see the contributing guide.

### Working with arrays#

#### Creating an array#

Zarr has several functions for creating arrays. For example:

    
    
    >>> import zarr
    >>> store = zarr.storage.MemoryStore()
    >>> z = zarr.create_array(store=store, shape=(10000, 10000), chunks=(1000, 1000), dtype='int32')
    >>> z
    <Array memory://... shape=(10000, 10000) dtype=int32>
    

The code above creates a 2-dimensional array of 32-bit integers with 10000
rows and 10000 columns, divided into chunks where each chunk has 1000 rows and
1000 columns (and so there will be 100 chunks in total). The data is written
to a `zarr.storage.MemoryStore` (e.g. an in-memory dict). See Persistent
arrays for details on storing arrays in other stores, and see Array data types
for an in-depth look at the data types supported by Zarr.

For a complete list of array creation routines see the `zarr` module
documentation.

#### Reading and writing data#

Zarr arrays support a similar interface to
[NumPy](https://numpy.org/doc/stable/) arrays for reading and writing data.
For example, the entire array can be filled with a scalar value:

    
    
    >>> z[:] = 42
    

Regions of the array can also be written to, e.g.:

    
    
    >>> import numpy as np
    >>>
    >>> z[0, :] = np.arange(10000)
    >>> z[:, 0] = np.arange(10000)
    

The contents of the array can be retrieved by slicing, which will load the
requested region into memory as a NumPy array, e.g.:

    
    
    >>> z[0, 0]
    array(0, dtype=int32)
    >>> z[-1, -1]
    array(42, dtype=int32)
    >>> z[0, :]
    array([   0,    1,    2, ..., 9997, 9998, 9999],
          shape=(10000,), dtype=int32)
    >>> z[:, 0]
    array([   0,    1,    2, ..., 9997, 9998, 9999],
          shape=(10000,), dtype=int32)
    >>> z[:]
    array([[   0,    1,    2, ..., 9997, 9998, 9999],
           [   1,   42,   42, ...,   42,   42,   42],
           [   2,   42,   42, ...,   42,   42,   42],
           ...,
           [9997,   42,   42, ...,   42,   42,   42],
           [9998,   42,   42, ...,   42,   42,   42],
           [9999,   42,   42, ...,   42,   42,   42]],
          shape=(10000, 10000), dtype=int32)
    

Read more about NumPy-style indexing can be found in the [NumPy
documentation](https://numpy.org/doc/stable/user/basics.indexing.html).

#### Persistent arrays#

In the examples above, compressed data for each chunk of the array was stored
in main memory. Zarr arrays can also be stored on a file system, enabling
persistence of data between sessions. To do this, we can change the store
argument to point to a filesystem path:

    
    
    >>> z1 = zarr.create_array(store='data/example-1.zarr', shape=(10000, 10000), chunks=(1000, 1000), dtype='int32')
    

The array above will store its configuration metadata and all compressed chunk
data in a directory called `'data/example-1.zarr'` relative to the current
working directory. The `zarr.create_array()` function provides a convenient
way to create a new persistent array or continue working with an existing
array. Note, there is no need to close an array: data are automatically
flushed to disk, and files are automatically closed whenever an array is
modified.

Persistent arrays support the same interface for reading and writing data,
e.g.:

    
    
    >>> z1[:] = 42
    >>> z1[0, :] = np.arange(10000)
    >>> z1[:, 0] = np.arange(10000)
    

Check that the data have been written and can be read again:

    
    
    >>> z2 = zarr.open_array('data/example-1.zarr', mode='r')
    >>> np.all(z1[:] == z2[:])
    np.True_
    

If you are just looking for a fast and convenient way to save NumPy arrays to
disk then load back into memory later, the functions `zarr.save()` and
`zarr.load()` may be useful. E.g.:

    
    
    >>> a = np.arange(10)
    >>> zarr.save('data/example-2.zarr', a)
    >>> zarr.load('data/example-2.zarr')
    array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
    

Please note that there are a number of other options for persistent array
storage, see the Storage Guide guide for more details.

#### Resizing and appending#

A Zarr array can be resized, which means that any of its dimensions can be
increased or decreased in length. For example:

    
    
    >>> z = zarr.create_array(store='data/example-3.zarr', shape=(10000, 10000), dtype='int32',chunks=(1000, 1000))
    >>> z[:] = 42
    >>> z.shape
    (10000, 10000)
    >>> z.resize((20000, 10000))
    >>> z.shape
    (20000, 10000)
    

Note that when an array is resized, the underlying data are not rearranged in
any way. If one or more dimensions are shrunk, any chunks falling outside the
new array shape will be deleted from the underlying store.

`zarr.Array.append()` is provided as a convenience function, which can be used
to append data to any axis. E.g.:

    
    
    >>> a = np.arange(10000000, dtype='int32').reshape(10000, 1000)
    >>> z = zarr.create_array(store='data/example-4.zarr', shape=a.shape, dtype=a.dtype, chunks=(1000, 100))
    >>> z[:] = a
    >>> z.shape
    (10000, 1000)
    >>> z.append(a)
    (20000, 1000)
    >>> z.append(np.vstack([a, a]), axis=1)
    (20000, 2000)
    >>> z.shape
    (20000, 2000)
    

#### Compressors#

A number of different compressors can be used with Zarr. Zarr includes Blosc,
Zstandard and Gzip compressors. Additional compressors are available through a
separate package called [NumCodecs](https://numcodecs.readthedocs.io/) which
provides various compressor libraries including LZ4, Zlib, BZ2 and LZMA.
Different compressors can be provided via the `compressors` keyword argument
accepted by all array creation functions. For example:

    
    
    >>> compressors = zarr.codecs.BloscCodec(cname='zstd', clevel=3, shuffle=zarr.codecs.BloscShuffle.bitshuffle)
    >>> data = np.arange(100000000, dtype='int32').reshape(10000, 10000)
    >>> z = zarr.create_array(store='data/example-5.zarr', shape=data.shape, dtype=data.dtype, chunks=(1000, 1000), compressors=compressors)
    >>> z[:] = data
    >>> z.compressors
    (BloscCodec(typesize=4, cname=<BloscCname.zstd: 'zstd'>, clevel=3, shuffle=<BloscShuffle.bitshuffle: 'bitshuffle'>, blocksize=0),)
    

This array above will use Blosc as the primary compressor, using the Zstandard
algorithm (compression level 3) internally within Blosc, and with the bit-
shuffle filter applied.

When using a compressor, it can be useful to get some diagnostics on the
compression ratio. Zarr arrays provide the `zarr.Array.info` property which
can be used to print useful diagnostics, e.g.:

    
    
    >>> z.info
    Type               : Array
    Zarr format        : 3
    Data type          : Int32(endianness='little')
    Fill value         : 0
    Shape              : (10000, 10000)
    Chunk shape        : (1000, 1000)
    Order              : C
    Read-only          : False
    Store type         : LocalStore
    Filters            : ()
    Serializer         : BytesCodec(endian=<Endian.little: 'little'>)
    Compressors        : (BloscCodec(typesize=4, cname=<BloscCname.zstd: 'zstd'>, clevel=3, shuffle=<BloscShuffle.bitshuffle: 'bitshuffle'>, blocksize=0),)
    No. bytes          : 400000000 (381.5M)
    

The `zarr.Array.info_complete()` method inspects the underlying store and
prints additional diagnostics, e.g.:

    
    
    >>> z.info_complete()
    Type               : Array
    Zarr format        : 3
    Data type          : Int32(endianness='little')
    Fill value         : 0
    Shape              : (10000, 10000)
    Chunk shape        : (1000, 1000)
    Order              : C
    Read-only          : False
    Store type         : LocalStore
    Filters            : ()
    Serializer         : BytesCodec(endian=<Endian.little: 'little'>)
    Compressors        : (BloscCodec(typesize=4, cname=<BloscCname.zstd: 'zstd'>, clevel=3, shuffle=<BloscShuffle.bitshuffle: 'bitshuffle'>, blocksize=0),)
    No. bytes          : 400000000 (381.5M)
    No. bytes stored   : 3558573 (3.4M)
    Storage ratio      : 112.4
    Chunks Initialized : 100
    

Note

`zarr.Array.info_complete()` will inspect the underlying store and may be slow
for large arrays. Use `zarr.Array.info` if detailed storage statistics are not
needed.

If you don’t specify a compressor, by default Zarr uses the Zstandard
compressor.

In addition to Blosc and Zstandard, other compression libraries can also be
used. For example, here is an array using Gzip compression, level 1:

    
    
    >>> data = np.arange(100000000, dtype='int32').reshape(10000, 10000)
    >>> z = zarr.create_array(store='data/example-6.zarr', shape=data.shape, dtype=data.dtype, chunks=(1000, 1000), compressors=zarr.codecs.GzipCodec(level=1))
    >>> z[:] = data
    >>> z.compressors
    (GzipCodec(level=1),)
    

Here is an example using LZMA from
[NumCodecs](https://numcodecs.readthedocs.io/) with a custom filter pipeline
including LZMA’s built-in delta filter:

    
    
    >>> import lzma
    >>> from numcodecs.zarr3 import LZMA
    >>>
    >>> lzma_filters = [dict(id=lzma.FILTER_DELTA, dist=4), dict(id=lzma.FILTER_LZMA2, preset=1)]
    >>> compressors = LZMA(filters=lzma_filters)
    >>> data = np.arange(100000000, dtype='int32').reshape(10000, 10000)
    >>> z = zarr.create_array(store='data/example-7.zarr', shape=data.shape, dtype=data.dtype, chunks=(1000, 1000), compressors=compressors)
    >>> z.compressors
    (LZMA(codec_name='numcodecs.lzma', codec_config={'filters': [{'id': 3, 'dist': 4}, {'id': 33, 'preset': 1}]}),)
    

To disable compression, set `compressors=None` when creating an array, e.g.:

    
    
    >>> z = zarr.create_array(store='data/example-8.zarr', shape=(100000000,), chunks=(1000000,), dtype='int32', compressors=None)
    >>> z.compressors
    ()
    

#### Filters#

In some cases, compression can be improved by transforming the data in some
way. For example, if nearby values tend to be correlated, then shuffling the
bytes within each numerical value or storing the difference between adjacent
values may increase compression ratio. Some compressors provide built-in
filters that apply transformations to the data prior to compression. For
example, the Blosc compressor has built-in implementations of byte- and bit-
shuffle filters, and the LZMA compressor has a built-in implementation of a
delta filter. However, to provide additional flexibility for implementing and
using filters in combination with different compressors, Zarr also provides a
mechanism for configuring filters outside of the primary compressor.

Here is an example using a delta filter with the Blosc compressor:

    
    
    >>> from numcodecs.zarr3 import Delta
    >>>
    >>> filters = [Delta(dtype='int32')]
    >>> compressors = zarr.codecs.BloscCodec(cname='zstd', clevel=1, shuffle=zarr.codecs.BloscShuffle.shuffle)
    >>> data = np.arange(100000000, dtype='int32').reshape(10000, 10000)
    >>> z = zarr.create_array(store='data/example-9.zarr', shape=data.shape, dtype=data.dtype, chunks=(1000, 1000), filters=filters, compressors=compressors)
    >>> z.info_complete()
    Type               : Array
    Zarr format        : 3
    Data type          : Int32(endianness='little')
    Fill value         : 0
    Shape              : (10000, 10000)
    Chunk shape        : (1000, 1000)
    Order              : C
    Read-only          : False
    Store type         : LocalStore
    Filters            : (Delta(codec_name='numcodecs.delta', codec_config={'dtype': 'int32'}),)
    Serializer         : BytesCodec(endian=<Endian.little: 'little'>)
    Compressors        : (BloscCodec(typesize=4, cname=<BloscCname.zstd: 'zstd'>, clevel=1, shuffle=<BloscShuffle.shuffle: 'shuffle'>, blocksize=0),)
    No. bytes          : 400000000 (381.5M)
    No. bytes stored   : 826
    Storage ratio      : 484261.5
    Chunks Initialized : 0
    

For more information about available filter codecs, see the
[Numcodecs](https://numcodecs.readthedocs.io/) documentation.

#### Advanced indexing#

Zarr arrays support several methods for advanced or “fancy” indexing, which
enable a subset of data items to be extracted or updated in an array without
loading the entire array into memory.

Note that although this functionality is similar to some of the advanced
indexing capabilities available on NumPy arrays and on h5py datasets, **the
Zarr API for advanced indexing is different from both NumPy and h5py** , so
please read this section carefully. For a complete description of the indexing
API, see the documentation for the `zarr.Array` class.

##### Indexing with coordinate arrays#

Items from a Zarr array can be extracted by providing an integer array of
coordinates. E.g.:

    
    
    >>> data = np.arange(10) ** 2
    >>> z = zarr.create_array(store='data/example-10.zarr', shape=data.shape, dtype=data.dtype)
    >>> z[:] = data
    >>> z[:]
    array([ 0,  1,  4,  9, 16, 25, 36, 49, 64, 81])
    >>> z.get_coordinate_selection([2, 5])
    array([ 4, 25])
    

Coordinate arrays can also be used to update data, e.g.:

    
    
    >>> z.set_coordinate_selection([2, 5], [-1, -2])
    >>> z[:]
    array([ 0,  1, -1,  9, 16, -2, 36, 49, 64, 81])
    

For multidimensional arrays, coordinates must be provided for each dimension,
e.g.:

    
    
    >>> data = np.arange(15).reshape(3, 5)
    >>> z = zarr.create_array(store='data/example-11.zarr', shape=data.shape, dtype=data.dtype)
    >>> z[:] = data
    >>> z[:]
    array([[ 0,  1,  2,  3,  4],
           [ 5,  6,  7,  8,  9],
           [10, 11, 12, 13, 14]])
    >>> z.get_coordinate_selection(([0, 2], [1, 3]))
    array([ 1, 13])
    >>> z.set_coordinate_selection(([0, 2], [1, 3]), [-1, -2])
    >>> z[:]
    array([[ 0, -1,  2,  3,  4],
           [ 5,  6,  7,  8,  9],
           [10, 11, 12, -2, 14]])
    

For convenience, coordinate indexing is also available via the `vindex`
property, as well as the square bracket operator, e.g.:

    
    
    >>> z.vindex[[0, 2], [1, 3]]
    array([-1, -2])
    >>> z.vindex[[0, 2], [1, 3]] = [-3, -4]
    >>> z[:]
    array([[ 0, -3,  2,  3,  4],
           [ 5,  6,  7,  8,  9],
           [10, 11, 12, -4, 14]])
    >>> z[[0, 2], [1, 3]]
    array([-3, -4])
    

When the indexing arrays have different shapes, they are broadcast together.
That is, the following two calls are equivalent:

    
    
    >>> z[1, [1, 3]]
    array([6, 8])
    >>> z[[1, 1], [1, 3]]
    array([6, 8])
    

##### Indexing with a mask array#

Items can also be extracted by providing a Boolean mask. E.g.:

    
    
    >>> data = np.arange(10) ** 2
    >>> z = zarr.create_array(store='data/example-12.zarr', shape=data.shape, dtype=data.dtype)
    >>> z[:] = data
    >>> z[:]
    array([ 0,  1,  4,  9, 16, 25, 36, 49, 64, 81])
    >>> sel = np.zeros_like(z, dtype=bool)
    >>> sel[2] = True
    >>> sel[5] = True
    >>> z.get_mask_selection(sel)
    array([ 4, 25])
    >>> z.set_mask_selection(sel, [-1, -2])
    >>> z[:]
    array([ 0,  1, -1,  9, 16, -2, 36, 49, 64, 81])
    

Here’s a multidimensional example:

    
    
    >>> data = np.arange(15).reshape(3, 5)
    >>> z = zarr.create_array(store='data/example-13.zarr', shape=data.shape, dtype=data.dtype)
    >>> z[:] = data
    >>> z[:]
    array([[ 0,  1,  2,  3,  4],
           [ 5,  6,  7,  8,  9],
           [10, 11, 12, 13, 14]])
    >>> sel = np.zeros_like(z, dtype=bool)
    >>> sel[0, 1] = True
    >>> sel[2, 3] = True
    >>> z.get_mask_selection(sel)
    array([ 1, 13])
    >>> z.set_mask_selection(sel, [-1, -2])
    >>> z[:]
    array([[ 0, -1,  2,  3,  4],
           [ 5,  6,  7,  8,  9],
           [10, 11, 12, -2, 14]])
    

For convenience, mask indexing is also available via the `vindex` property,
e.g.:

    
    
    >>> z.vindex[sel]
    array([-1, -2])
    >>> z.vindex[sel] = [-3, -4]
    >>> z[:]
    array([[ 0, -3,  2,  3,  4],
           [ 5,  6,  7,  8,  9],
           [10, 11, 12, -4, 14]])
    

Mask indexing is conceptually the same as coordinate indexing, and is
implemented internally via the same machinery. Both styles of indexing allow
selecting arbitrary items from an array, also known as point selection.

##### Orthogonal indexing#

Zarr arrays also support methods for orthogonal indexing, which allows
selections to be made along each dimension of an array independently. For
example, this allows selecting a subset of rows and/or columns from a
2-dimensional array. E.g.:

    
    
    >>> data = np.arange(15).reshape(3, 5)
    >>> z = zarr.create_array(store='data/example-14.zarr', shape=data.shape, dtype=data.dtype)
    >>> z[:] = data
    >>> z[:]
    array([[ 0,  1,  2,  3,  4],
           [ 5,  6,  7,  8,  9],
           [10, 11, 12, 13, 14]])
    >>> z.get_orthogonal_selection(([0, 2], slice(None)))  # select first and third rows
    array([[ 0,  1,  2,  3,  4],
           [10, 11, 12, 13, 14]])
    >>> z.get_orthogonal_selection((slice(None), [1, 3]))  # select second and fourth columns
    array([[ 1,  3],
           [ 6,  8],
           [11, 13]])
    >>> z.get_orthogonal_selection(([0, 2], [1, 3]))  # select rows [0, 2] and columns [1, 4]
    array([[ 1,  3],
           [11, 13]])
    

Data can also be modified, e.g.:

    
    
    >>> z.set_orthogonal_selection(([0, 2], [1, 3]), [[-1, -2], [-3, -4]])
    

For convenience, the orthogonal indexing functionality is also available via
the `oindex` property, e.g.:

    
    
    >>> data = np.arange(15).reshape(3, 5)
    >>> z = zarr.create_array(store='data/example-15.zarr', shape=data.shape, dtype=data.dtype)
    >>> z[:] = data
    >>> z.oindex[[0, 2], :]  # select first and third rows
    array([[ 0,  1,  2,  3,  4],
           [10, 11, 12, 13, 14]])
    >>> z.oindex[:, [1, 3]]  # select second and fourth columns
    array([[ 1,  3],
           [ 6,  8],
           [11, 13]])
    >>> z.oindex[[0, 2], [1, 3]]  # select rows [0, 2] and columns [1, 4]
    array([[ 1,  3],
           [11, 13]])
    >>> z.oindex[[0, 2], [1, 3]] = [[-1, -2], [-3, -4]]
    >>> z[:]
    array([[ 0, -1,  2, -2,  4],
           [ 5,  6,  7,  8,  9],
           [10, -3, 12, -4, 14]])
    

Any combination of integer, slice, 1D integer array and/or 1D Boolean array
can be used for orthogonal indexing.

If the index contains at most one iterable, and otherwise contains only slices
and integers, orthogonal indexing is also available directly on the array:

    
    
    >>> data = np.arange(15).reshape(3, 5)
    >>> z = zarr.create_array(store='data/example-16.zarr', shape=data.shape, dtype=data.dtype)
    >>> z[:] = data
    >>> np.all(z.oindex[[0, 2], :] == z[[0, 2], :])
    np.True_
    

##### Block Indexing#

Zarr also support block indexing, which allows selections of whole chunks
based on their logical indices along each dimension of an array. For example,
this allows selecting a subset of chunk aligned rows and/or columns from a
2-dimensional array. E.g.:

    
    
    >>> data = np.arange(100).reshape(10, 10)
    >>> z = zarr.create_array(store='data/example-17.zarr', shape=data.shape, dtype=data.dtype, chunks=(3, 3))
    >>> z[:] = data
    

Retrieve items by specifying their block coordinates:

    
    
    >>> z.get_block_selection(1)
    array([[30, 31, 32, 33, 34, 35, 36, 37, 38, 39],
           [40, 41, 42, 43, 44, 45, 46, 47, 48, 49],
           [50, 51, 52, 53, 54, 55, 56, 57, 58, 59]])
    

Equivalent slicing:

    
    
    >>> z[3:6]
    array([[30, 31, 32, 33, 34, 35, 36, 37, 38, 39],
           [40, 41, 42, 43, 44, 45, 46, 47, 48, 49],
           [50, 51, 52, 53, 54, 55, 56, 57, 58, 59]])
    

For convenience, the block selection functionality is also available via the
blocks property, e.g.:

    
    
    >>> z.blocks[1]
    array([[30, 31, 32, 33, 34, 35, 36, 37, 38, 39],
           [40, 41, 42, 43, 44, 45, 46, 47, 48, 49],
           [50, 51, 52, 53, 54, 55, 56, 57, 58, 59]])
    

Block index arrays may be multidimensional to index multidimensional arrays.
For example:

    
    
    >>> z.blocks[0, 1:3]
    array([[ 3,  4,  5,  6,  7,  8],
           [13, 14, 15, 16, 17, 18],
           [23, 24, 25, 26, 27, 28]])
    

Data can also be modified. Let’s start by a simple 2D array:

    
    
    >>> z = zarr.create_array(store='data/example-18.zarr', shape=(6, 6), dtype=int, chunks=(2, 2))
    

Set data for a selection of items:

    
    
    >>> z.set_block_selection((1, 0), 1)
    >>> z[...]
    array([[0, 0, 0, 0, 0, 0],
           [0, 0, 0, 0, 0, 0],
           [1, 1, 0, 0, 0, 0],
           [1, 1, 0, 0, 0, 0],
           [0, 0, 0, 0, 0, 0],
           [0, 0, 0, 0, 0, 0]])
    

For convenience, this functionality is also available via the `blocks`
property. E.g.:

    
    
    >>> z.blocks[:, 2] = 7
    >>> z[...]
    array([[0, 0, 0, 0, 7, 7],
           [0, 0, 0, 0, 7, 7],
           [1, 1, 0, 0, 7, 7],
           [1, 1, 0, 0, 7, 7],
           [0, 0, 0, 0, 7, 7],
           [0, 0, 0, 0, 7, 7]])
    

Any combination of integer and slice can be used for block indexing:

    
    
    >>> z.blocks[2, 1:3]
    array([[0, 0, 7, 7],
           [0, 0, 7, 7]])
    >>>
    >>> root = zarr.create_group('data/example-19.zarr')
    >>> foo = root.create_array(name='foo', shape=(1000, 100), chunks=(10, 10), dtype='float32')
    >>> bar = root.create_array(name='foo/bar', shape=(100,), dtype='int32')
    >>> foo[:, :] = np.random.random((1000, 100))
    >>> bar[:] = np.arange(100)
    >>> root.tree()
    /
    └── foo (1000, 100) float32
    

#### Sharding#

Using small chunk shapes in very large arrays can lead to a very large number
of chunks. This can become a performance issue for file systems and object
storage. With Zarr format 3, a new sharding feature has been added to address
this issue.

With sharding, multiple chunks can be stored in a single storage object (e.g.
a file). Within a shard, chunks are compressed and serialized separately. This
allows individual chunks to be read independently. However, when writing data,
a full shard must be written in one go for optimal performance and to avoid
concurrency issues. That means that shards are the units of writing and chunks
are the units of reading. Users need to configure the chunk and shard shapes
accordingly.

Sharded arrays can be created by providing the `shards` parameter to
`zarr.create_array()`.

    
    
    >>> a = zarr.create_array('data/example-20.zarr', shape=(10000, 10000), shards=(1000, 1000), chunks=(100, 100), dtype='uint8')
    >>> a[:] = (np.arange(10000 * 10000) % 256).astype('uint8').reshape(10000, 10000)
    >>> a.info_complete()
    Type               : Array
    Zarr format        : 3
    Data type          : UInt8()
    Fill value         : 0
    Shape              : (10000, 10000)
    Shard shape        : (1000, 1000)
    Chunk shape        : (100, 100)
    Order              : C
    Read-only          : False
    Store type         : LocalStore
    Filters            : ()
    Serializer         : BytesCodec(endian=None)
    Compressors        : (ZstdCodec(level=0, checksum=False),)
    No. bytes          : 100000000 (95.4M)
    No. bytes stored   : 3981473 (3.8M)
    Storage ratio      : 25.1
    Shards Initialized : 100
    

In this example a shard shape of (1000, 1000) and a chunk shape of (100, 100)
is used. This means that 10*10 chunks are stored in each shard, and there are
10*10 shards in total. Without the `shards` argument, there would be 10,000
chunks stored as individual files.

#### Missing features in 3.0#

The following features have not been ported to 3.0 yet.

##### Copying and migrating data#

See the Zarr-Python 2 documentation on [Copying and migrating
data](https://zarr.readthedocs.io/en/support-v2/tutorial.html#copying-
migrating-data) for more details.

### Working with groups#

Zarr supports hierarchical organization of arrays via groups. As with arrays,
groups can be stored in memory, on disk, or via other storage systems that
support a similar interface.

To create a group, use the `zarr.group()` function:

    
    
    >>> import zarr
    >>> store = zarr.storage.MemoryStore()
    >>> root = zarr.create_group(store=store)
    >>> root
    <Group memory://...>
    

Groups have a similar API to the Group class from
[h5py](https://www.h5py.org/). For example, groups can contain other groups:

    
    
    >>> foo = root.create_group('foo')
    >>> bar = foo.create_group('bar')
    

Groups can also contain arrays, e.g.:

    
    
    >>> z1 = bar.create_array(name='baz', shape=(10000, 10000), chunks=(1000, 1000), dtype='int32')
    >>> z1
    <Array memory://.../foo/bar/baz shape=(10000, 10000) dtype=int32>
    

Members of a group can be accessed via the suffix notation, e.g.:

    
    
    >>> root['foo']
    <Group memory://.../foo>
    

The ‘/’ character can be used to access multiple levels of the hierarchy in
one call, e.g.:

    
    
    >>> root['foo/bar']
    <Group memory://.../foo/bar>
    >>> root['foo/bar/baz']
    <Array memory://.../foo/bar/baz shape=(10000, 10000) dtype=int32>
    

The `zarr.Group.tree()` method can be used to print a tree representation of
the hierarchy, e.g.:

    
    
    >>> root.tree()
    /
    └── foo
        └── bar
            └── baz (10000, 10000) int32
    

The `zarr.open_group()` function provides a convenient way to create or re-
open a group stored in a directory on the file-system, with sub-groups stored
in sub-directories, e.g.:

    
    
    >>> root = zarr.open_group('data/group.zarr', mode='w')
    >>> root
    <Group file://data/group.zarr>
    >>>
    >>> z = root.create_array(name='foo/bar/baz', shape=(10000, 10000), chunks=(1000, 1000), dtype='int32')
    >>> z
    <Array file://data/group.zarr/foo/bar/baz shape=(10000, 10000) dtype=int32>
    

For more information on groups see the `zarr.Group` API docs.

#### Batch Group Creation#

You can also create multiple groups concurrently with a single function call.
`zarr.create_hierarchy()` takes a `zarr.storage.Store` instance and a dict of
`key : metadata` pairs, parses that dict, and writes metadata documents to
storage:

    
    
    >>> from zarr import create_hierarchy
    >>> from zarr.core.group import GroupMetadata
    >>> from zarr.storage import LocalStore
    >>> node_spec = {'a/b/c': GroupMetadata()}
    >>> nodes_created = dict(create_hierarchy(store=LocalStore(root='data'), nodes=node_spec))
    >>> print(sorted(nodes_created.items(), key=lambda kv: len(kv[0])))
    [('', <Group file://data>), ('a', <Group file://data/a>), ('a/b', <Group file://data/a/b>), ('a/b/c', <Group file://data/a/b/c>)]
    

Note that we only specified a single group named `a/b/c`, but 4 groups were
created. These additional groups were created to ensure that the desired node
`a/b/c` is connected to the root group `''` by a sequence of intermediate
groups. `zarr.create_hierarchy()` normalizes the `nodes` keyword argument to
ensure that the resulting hierarchy is complete, i.e. all groups or arrays are
connected to the root of the hierarchy via intermediate groups.

Because `zarr.create_hierarchy()` concurrently creates metadata documents,
it’s more efficient than repeated calls to `create_group()` or
`create_array()`, provided you can statically define the metadata for the
groups and arrays you want to create.

#### Array and group diagnostics#

Diagnostic information about arrays and groups is available via the `info`
property. E.g.:

    
    
    >>> store = zarr.storage.MemoryStore()
    >>> root = zarr.group(store=store)
    >>> foo = root.create_group('foo')
    >>> bar = foo.create_array(name='bar', shape=1000000, chunks=100000, dtype='int64')
    >>> bar[:] = 42
    >>> baz = foo.create_array(name='baz', shape=(1000, 1000), chunks=(100, 100), dtype='float32')
    >>> baz[:] = 4.2
    >>> root.info
    Name        :
    Type        : Group
    Zarr format : 3
    Read-only   : False
    Store type  : MemoryStore
    >>> foo.info
    Name        : foo
    Type        : Group
    Zarr format : 3
    Read-only   : False
    Store type  : MemoryStore
    >>> bar.info_complete()
    Type               : Array
    Zarr format        : 3
    Data type          : Int64(endianness='little')
    Fill value         : 0
    Shape              : (1000000,)
    Chunk shape        : (100000,)
    Order              : C
    Read-only          : False
    Store type         : MemoryStore
    Filters            : ()
    Serializer         : BytesCodec(endian=<Endian.little: 'little'>)
    Compressors        : (ZstdCodec(level=0, checksum=False),)
    No. bytes          : 8000000 (7.6M)
    No. bytes stored   : 1614 (1.6K)
    Storage ratio      : 4956.6
    Chunks Initialized : 10
    >>> baz.info
    Type               : Array
    Zarr format        : 3
    Data type          : Float32(endianness='little')
    Fill value         : 0.0
    Shape              : (1000, 1000)
    Chunk shape        : (100, 100)
    Order              : C
    Read-only          : False
    Store type         : MemoryStore
    Filters            : ()
    Serializer         : BytesCodec(endian=<Endian.little: 'little'>)
    Compressors        : (ZstdCodec(level=0, checksum=False),)
    No. bytes          : 4000000 (3.8M)
    

Groups also have the `zarr.Group.tree()` method, e.g.:

    
    
    >>> root.tree()
    /
    └── foo
        ├── bar (1000000,) int64
        └── baz (1000, 1000) float32
    

Note

`zarr.Group.tree()` requires the optional
[rich](https://rich.readthedocs.io/en/stable/) dependency. It can be installed
with the `[tree]` extra.

### Working with attributes#

Zarr arrays and groups support custom key/value attributes, which can be
useful for storing application-specific metadata. For example:

    
    
    >>> import zarr
    >>> store = zarr.storage.MemoryStore()
    >>> root = zarr.create_group(store=store)
    >>> root.attrs['foo'] = 'bar'
    >>> z = root.create_array(name='zzz', shape=(10000, 10000), dtype='int32')
    >>> z.attrs['baz'] = 42
    >>> z.attrs['qux'] = [1, 4, 7, 12]
    >>> sorted(root.attrs)
    ['foo']
    >>> 'foo' in root.attrs
    True
    >>> root.attrs['foo']
    'bar'
    >>> sorted(z.attrs)
    ['baz', 'qux']
    >>> z.attrs['baz']
    42
    >>> z.attrs['qux']
    [1, 4, 7, 12]
    

Internally Zarr uses JSON to store array attributes, so attribute values must
be JSON serializable.

### Storage guide#

Zarr-Python supports multiple storage backends, including: local file systems,
Zip files, remote stores via [fsspec](https://filesystem-spec.readthedocs.io)
(S3, HTTP, etc.), and in-memory stores. In Zarr-Python 3, stores must
implement the abstract store API from `zarr.abc.store.Store`.

Note

Unlike Zarr-Python 2 where the store interface was built around a generic
`MutableMapping` API, Zarr-Python 3 utilizes a custom store API that utilizes
Python’s AsyncIO library.

#### Implicit Store Creation#

In most cases, it is not required to create a `Store` object explicitly.
Passing a string to Zarr’s top level API will result in the store being
created automatically.:

    
    
    >>> import zarr
    >>>
    >>> # Implicitly create a writable LocalStore
    >>> zarr.create_group(store='data/foo/bar')
    <Group file://data/foo/bar>
    >>>
    >>> # Implicitly create a read-only FsspecStore
    >>> zarr.open_group(
    ...    store='s3://noaa-nwm-retro-v2-zarr-pds',
    ...    mode='r',
    ...    storage_options={'anon': True}
    ... )
    <Group <FsspecStore(S3FileSystem, noaa-nwm-retro-v2-zarr-pds)>>
    >>>
    >>> # Implicitly creates a MemoryStore
    >>> data = {}
    >>> zarr.create_group(store=data)
    <Group memory://...>
    

#### Explicit Store Creation#

In some cases, it may be helpful to create a store instance directly. Zarr-
Python offers four built-in store: `zarr.storage.LocalStore`,
`zarr.storage.FsspecStore`, `zarr.storage.ZipStore`,
`zarr.storage.MemoryStore`, and `zarr.storage.ObjectStore`.

##### Local Store#

The `zarr.storage.LocalStore` stores data in a nested set of directories on a
local filesystem.:

    
    
    >>> store = zarr.storage.LocalStore('data/foo/bar', read_only=True)
    >>> zarr.open_group(store=store, mode='r')
    <Group file://data/foo/bar>
    

##### Zip Store#

The `zarr.storage.ZipStore` stores the contents of a Zarr hierarchy in a
single Zip file. The [Zip Store specification](https://github.com/zarr-
developers/zarr-specs/pull/311) is currently in draft form.:

    
    
    >>> store = zarr.storage.ZipStore('data.zip', mode='w')
    >>> zarr.create_array(store=store, shape=(2,), dtype='float64')
    <Array zip://data.zip shape=(2,) dtype=float64>
    

##### Remote Store#

The `zarr.storage.FsspecStore` stores the contents of a Zarr hierarchy in
following the same logical layout as the `LocalStore`, except the store is
assumed to be on a remote storage system such as cloud object storage (e.g.
AWS S3, Google Cloud Storage, Azure Blob Store). The
`zarr.storage.FsspecStore` is backed by [fsspec](https://filesystem-
spec.readthedocs.io) and can support any backend that implements the
[AbstractFileSystem](https://filesystem-
spec.readthedocs.io/en/stable/api.html#fsspec.spec.AbstractFileSystem) API.
`storage_options` can be used to configure the fsspec backend.:

    
    
    >>> store = zarr.storage.FsspecStore.from_url(
    ...    's3://noaa-nwm-retro-v2-zarr-pds',
    ...    read_only=True,
    ...    storage_options={'anon': True}
    ... )
    >>> zarr.open_group(store=store, mode='r')
    <Group <FsspecStore(S3FileSystem, noaa-nwm-retro-v2-zarr-pds)>>
    

The type of filesystem (e.g. S3, https, etc..) is inferred from the scheme of
the url (e.g. s3 for “**s3** ://noaa-nwm-retro-v2-zarr-pds”). In case a
specific filesystem is needed, one can explicitly create it. For example to
create a S3 filesystem:

    
    
    >>> import fsspec
    >>> fs = fsspec.filesystem(
    ...    's3', anon=True, asynchronous=True,
    ...    client_kwargs={'endpoint_url': "https://noaa-nwm-retro-v2-zarr-pds.s3.amazonaws.com"}
    ... )
    >>> store = zarr.storage.FsspecStore(fs)
    

##### Memory Store#

The `zarr.storage.MemoryStore` a in-memory store that allows for serialization
of Zarr data (metadata and chunks) to a dictionary.:

    
    
    >>> data = {}
    >>> store = zarr.storage.MemoryStore(data)
    >>> # TODO: replace with create_array after #2463
    >>> zarr.create_array(store=store, shape=(2,), dtype='float64')
    <Array memory://... shape=(2,) dtype=float64>
    

##### Object Store#

`zarr.storage.ObjectStore` stores the contents of the Zarr hierarchy using any
ObjectStore [storage
implementation](https://developmentseed.org/obstore/latest/api/store/),
including AWS S3
([`obstore.store.S3Store`](https://developmentseed.org/obstore/latest/api/store/aws/#obstore.store.S3Store
"\(in obstore v0.0.0\)")), Google Cloud Storage
([`obstore.store.GCSStore`](https://developmentseed.org/obstore/latest/api/store/gcs/#obstore.store.GCSStore
"\(in obstore v0.0.0\)")), and Azure Blob Storage
([`obstore.store.AzureStore`](https://developmentseed.org/obstore/latest/api/store/azure/#obstore.store.AzureStore
"\(in obstore v0.0.0\)")). This store is backed by
[obstore](https://developmentseed.org/obstore/latest/), which builds on the
production quality Rust library
[object_store](https://docs.rs/object_store/latest/object_store/).

    
    
    >>> from zarr.storage import ObjectStore
    >>> from obstore.store import MemoryStore
    >>>
    >>> store = ObjectStore(MemoryStore())
    >>> zarr.create_array(store=store, shape=(2,), dtype='float64')
    <Array object_store://... shape=(2,) dtype=float64>
    

Here’s an example of using ObjectStore for accessing remote data:

    
    
    >>> from zarr.storage import ObjectStore
    >>> from obstore.store import S3Store
    >>>
    >>> s3_store = S3Store('noaa-nwm-retro-v2-zarr-pds', skip_signature=True, region="us-west-2")
    >>> store = zarr.storage.ObjectStore(store=s3_store, read_only=True)
    >>> group = zarr.open_group(store=store, mode='r')
    >>> group.info
    Name        :
    Type        : Group
    Zarr format : 2
    Read-only   : True
    Store type  : ObjectStore
    No. members : 12
    No. arrays  : 12
    No. groups  : 0
    

Warning

The `zarr.storage.ObjectStore` class is experimental.

#### Developing custom stores#

Zarr-Python `zarr.abc.store.Store` API is meant to be extended. The Store
Abstract Base Class includes all of the methods needed to be a fully
operational store in Zarr Python. Zarr also provides a test harness for custom
stores: `zarr.testing.store.StoreTests`.

### Runtime configuration#

`zarr.config` is responsible for managing the configuration of zarr and is
based on the [donfig](https://github.com/pytroll/donfig) Python library.

Configuration values can be set using code like the following:

    
    
    >>> import zarr
    >>>
    >>> zarr.config.set({'array.order': 'F'})
    <donfig.config_obj.ConfigSet object at ...>
    >>>
    >>> # revert this change so it doesn't impact the rest of the docs
    >>> zarr.config.set({'array.order': 'C'})
    <donfig.config_obj.ConfigSet object at ...>
    

Alternatively, configuration values can be set using environment variables,
e.g. `ZARR_ARRAY__ORDER=F`.

The configuration can also be read from a YAML file in standard locations. For
more information, see the [donfig
documentation](https://donfig.readthedocs.io/en/latest/).

Configuration options include the following:

  * Default Zarr format `default_zarr_version`

  * Default array order in memory `array.order`

  * Default filters, serializers and compressors, e.g. `array.v3_default_filters`, `array.v3_default_serializer`, `array.v3_default_compressors`, `array.v2_default_filters` and `array.v2_default_compressor`

  * Whether empty chunks are written to storage `array.write_empty_chunks`

  * Async and threading options, e.g. `async.concurrency` and `threading.max_workers`

  * Selections of implementations of codecs, codec pipelines and buffers

  * Enabling GPU support with `zarr.config.enable_gpu()`. See Using GPUs with Zarr for more.

For selecting custom implementations of codecs, pipelines, buffers and
ndbuffers, first register the implementations in the registry and then select
them in the config. For example, an implementation of the bytes codec in a
class `'custompackage.NewBytesCodec'`, requires the value of
`codecs.bytes.name` to be `'custompackage.NewBytesCodec'`.

This is the current default configuration:

    
    
    >>> zarr.config.pprint()
    {'array': {'order': 'C',
               'write_empty_chunks': False},
    'async': {'concurrency': 10, 'timeout': None},
    'buffer': 'zarr.buffer.cpu.Buffer',
    'codec_pipeline': {'batch_size': 1,
                      'path': 'zarr.core.codec_pipeline.BatchedCodecPipeline'},
    'codecs': {'blosc': 'zarr.codecs.blosc.BloscCodec',
                'bytes': 'zarr.codecs.bytes.BytesCodec',
                'crc32c': 'zarr.codecs.crc32c_.Crc32cCodec',
                'endian': 'zarr.codecs.bytes.BytesCodec',
                'gzip': 'zarr.codecs.gzip.GzipCodec',
                'sharding_indexed': 'zarr.codecs.sharding.ShardingCodec',
                'transpose': 'zarr.codecs.transpose.TransposeCodec',
                'vlen-bytes': 'zarr.codecs.vlen_utf8.VLenBytesCodec',
                'vlen-utf8': 'zarr.codecs.vlen_utf8.VLenUTF8Codec',
                'zstd': 'zarr.codecs.zstd.ZstdCodec'},
    'default_zarr_format': 3,
    'json_indent': 2,
    'ndbuffer': 'zarr.buffer.cpu.NDBuffer',
    'threading': {'max_workers': None}}
    

### 3.0 Migration Guide#

Zarr-Python 3 represents a major refactor of the Zarr-Python codebase. Some of
the goals motivating this refactor included:

  * adding support for the Zarr format 3 specification (along with the Zarr format 2 specification)

  * cleaning up internal and user facing APIs

  * improving performance (particularly in high latency storage environments like cloud object stores)

To accommodate this, Zarr-Python 3 introduces a number of changes to the API,
including a number of significant breaking changes and deprecations.

This page provides a guide explaining breaking changes and deprecations to
help you migrate your code from version 2 to version 3. If we have missed
anything, please open a [GitHub issue](https://github.com/zarr-
developers/zarr-python/issues/new) so we can improve this guide.

#### Compatibility target#

The goals described above necessitated some breaking changes to the API (hence
the major version update), but where possible we have maintained backwards
compatibility in the most widely used parts of the API. This in the
`zarr.Array` and `zarr.Group` classes and the “top-level API” (e.g.
`zarr.open_array()` and `zarr.open_group()`).

#### Getting ready for 3.0#

Before migrating to Zarr-Python 3, we suggest projects that depend on Zarr-
Python take the following actions in order:

  1. Pin the supported Zarr-Python version to `zarr>=2,<3`. This is a best practice and will protect your users from any incompatibilities that may arise during the release of Zarr-Python 3. This pin can be removed after migrating to Zarr-Python 3.

  2. Limit your imports from the Zarr-Python package. Most of the primary API `zarr.*` will be compatible in Zarr-Python 3. However, the following breaking API changes are planned:

     * `numcodecs.*` will no longer be available in `zarr.*`. To migrate, import codecs directly from `numcodecs`:
           
           from numcodecs import Blosc
           # instead of:
           # from zarr import Blosc
           

     * The `zarr.v3_api_available` feature flag is being removed. In Zarr-Python 3 the v3 API is always available, so you shouldn’t need to use this flag.

     * The following internal modules are being removed or significantly changed. If your application relies on imports from any of the below modules, you will need to either a) modify your application to no longer rely on these imports or b) vendor the parts of the specific modules that you need.

       * `zarr.attrs` has gone, with no replacement

       * `zarr.codecs` has changed, see “Codecs” section below for more information

       * `zarr.context` has gone, with no replacement

       * `zarr.core` remains but should be considered private API

       * `zarr.hierarchy` has gone, with no replacement (use `zarr.Group` inplace of `zarr.hierarchy.Group`)

       * `zarr.indexing` has gone, with no replacement

       * `zarr.meta` has gone, with no replacement

       * `zarr.meta_v1` has gone, with no replacement

       * `zarr.sync` has gone, with no replacement

       * `zarr.types` has gone, with no replacement

       * `zarr.util` has gone, with no replacement

       * `zarr.n5` has gone, see below for an alternative N5 options

  3. Test that your package works with version 3.

  4. Update the pin to include `zarr>=3,<4`.

#### Zarr-Python 2 support window#

Zarr-Python 2.x is still available, though we recommend migrating to Zarr-
Python 3 for its performance improvements and new features. Security and bug
fixes will be made to the 2.x series for at least six months following the
first Zarr-Python 3 release. If you need to use the latest Zarr-Python 2
release, you can install it with:

    
    
    $ pip install "zarr==2.*"
    

Note

Development and maintenance of the 2.x release series has moved to the
[support/v2](https://github.com/zarr-developers/zarr-python/tree/support/v2)
branch. Issues and pull requests related to this branch are tagged with the
[V2](https://github.com/zarr-developers/zarr-python/labels/V2) label.

#### Migrating to Zarr-Python 3#

The following sections provide details on breaking changes in Zarr-Python 3.

##### The Array class#

  1. Disallow direct construction - the signature for initializing the `Array` class has changed significantly. Please use `zarr.create_array()` or `zarr.open_array()` instead of directly constructing the `zarr.Array` class.

  2. Defaulting to `zarr_format=3` \- newly created arrays will use the version 3 of the Zarr specification. To continue using version 2, set `zarr_format=2` when creating arrays or set `default_zarr_version=2` in Zarr’s runtime configuration.

##### The Group class#

  1. Disallow direct construction - use `zarr.open_group()` or `zarr.create_group()` instead of directly constructing the `zarr.Group` class.

  2. Most of the h5py compatibility methods are deprecated and will issue warnings if used. The following functions are drop in replacements that have the same signature and functionality:

     * Use `zarr.Group.create_array()` in place of `zarr.Group.create_dataset()`

     * Use `zarr.Group.require_array()` in place of `zarr.Group.require_dataset()`

  3. Disallow “.” syntax for getting group members. To get a member of a group named `foo`, use `group["foo"]` in place of `group.foo`.

##### The Store class#

The Store API has changed significant in Zarr-Python 3. The most notable
changes to the Store API are:

###### Store Import Paths#

Several store implementations have moved from the top-level module to
`zarr.storage`:

Store import changes from v2 to v3#

    
    
    # Before (v2)
    - from zarr import MemoryStore, DirectoryStore
    + from zarr.storage import MemoryStore, LocalStore  # LocalStore replaces DirectoryStore
    

Common replacements:

v2 Import | v3 Import  
---|---  
`zarr.MemoryStore` | `zarr.storage.MemoryStore`  
`zarr.DirectoryStore` | `zarr.storage.LocalStore`  
`zarr.TempStore` | Use `tempfile.TemporaryDirectory` with `LocalStore`  
  
  1. Replaced the `MutableMapping` base class in favor of a custom abstract base class (`zarr.abc.store.Store`).

  2. Switched to an asynchronous interface for all store methods that result in IO. This change ensures that all store methods are non-blocking and are as performant as possible.

Beyond the changes store interface, a number of deprecated stores were also
removed in Zarr-Python 3. See [#1274](https://github.com/zarr-developers/zarr-
python/issues/1274) for more details on the removal of these stores.

  * `N5Store` \- see [zarr-developers/n5py](https://github.com/zarr-developers/n5py) for an alternative interface to N5 formatted data.

  * `ABSStore` \- use the `zarr.storage.FsspecStore` instead along with fsspec’s [adlfs backend](https://github.com/fsspec/adlfs).

The following stores have been removed altogether. Users who need these stores
will have to implement their own version in zarr-python v3.

  * `DBMStore`

  * `LMDBStore`

  * `SQLiteStore`

  * `MongoDBStore`

  * `RedisStore`

At present, the latter five stores in this list do not have an equivalent in
Zarr-Python 3. If you are interested in developing a custom store that targets
these backends, see developing custom stores or open an
[issue](https://github.com/zarr-developers/zarr-python/issues) to discuss your
use case.

##### Codecs#

Codecs defined in `numcodecs` (and also imported into the `zarr.codecs`
namespace in Zarr-Python 2) should still be used when creating Zarr format 2
arrays.

Codecs for creating Zarr format 3 arrays are available in two locations:

  * zarr.codecs contains Zarr format 3 codecs that are defined in the [codecs section of the Zarr format 3 specification](https://zarr-specs.readthedocs.io/en/latest/v3/codecs/index.html).

  * numcodecs.zarr3 contains codecs from `numcodecs` that can be used to create Zarr format 3 arrays, but are not necessarily part of the Zarr format 3 specification.

##### Dependencies#

When installing using `pip`:

  * The new `remote` dependency group can be used to install a supported version of `fsspec`, required for remote data access.

  * The new `gpu` dependency group can be used to install a supported version of `cuda`, required for GPU functionality.

  * The `jupyter` optional dependency group has been removed, since v3 contains no jupyter specific functionality.

##### Miscellaneous#

  * The keyword argument `zarr_version` available in most creation functions in `zarr` (e.g. `zarr.create()`, `zarr.open()`, `zarr.group()`, `zarr.array()`) has been deprecated in favor of `zarr_format`.

#### 🚧 Work in Progress 🚧#

Zarr-Python 3 is still under active development, and is not yet fully
complete. The following list summarizes areas of the codebase that we expect
to build out after the 3.0.0 release. If features listed below are important
to your use case of Zarr-Python, please open (or comment on) a [GitHub
issue](https://github.com/zarr-developers/zarr-python/issues/new).

  * The following functions / methods have not been ported to Zarr-Python 3 yet:

    * `zarr.copy()` ([#2407](https://github.com/zarr-developers/zarr-python/issues/2407))

    * `zarr.copy_all()` ([#2407](https://github.com/zarr-developers/zarr-python/issues/2407))

    * `zarr.copy_store()` ([#2407](https://github.com/zarr-developers/zarr-python/issues/2407))

    * `zarr.Group.move()` ([#2108](https://github.com/zarr-developers/zarr-python/issues/2108))

  * The following features (corresponding to function arguments to functions in `zarr`) have not been ported to Zarr-Python 3 yet. Using these features will raise a warning or a `NotImplementedError`:

    * `cache_attrs`

    * `cache_metadata`

    * `chunk_store` ([#2495](https://github.com/zarr-developers/zarr-python/issues/2495))

    * `meta_array`

    * `object_codec` ([#2617](https://github.com/zarr-developers/zarr-python/issues/2617))

    * `synchronizer` ([#1596](https://github.com/zarr-developers/zarr-python/issues/1596))

    * `dimension_separator`

  * The following features that were supported by Zarr-Python 2 have not been ported to Zarr-Python 3 yet:

    * Structured arrays / dtypes ([#2134](https://github.com/zarr-developers/zarr-python/issues/2134))

    * Fixed-length string dtypes ([#2347](https://github.com/zarr-developers/zarr-python/issues/2347))

    * Datetime and timedelta dtypes ([#2616](https://github.com/zarr-developers/zarr-python/issues/2616))

    * Object dtypes ([#2617](https://github.com/zarr-developers/zarr-python/issues/2617))

    * Ragged arrays ([#2618](https://github.com/zarr-developers/zarr-python/issues/2618))

    * Groups and Arrays do not implement `__enter__` and `__exit__` protocols ([#2619](https://github.com/zarr-developers/zarr-python/issues/2619))

    * Big Endian dtypes ([#2324](https://github.com/zarr-developers/zarr-python/issues/2324))

    * Default filters for object dtypes for Zarr format 2 arrays ([#2627](https://github.com/zarr-developers/zarr-python/issues/2627))

### Advanced Topics#

#### Array data types#

##### Zarr’s Data Type Model#

Zarr is designed for interoperability with NumPy, so if you are familiar with
NumPy or any other N-dimensional array library, Zarr’s model for array data
types should seem familiar. However, Zarr data types have some unique features
that are described in this document.

Zarr arrays operate under an essential design constraint: unlike NumPy arrays,
Zarr arrays are designed to be stored and accessed by other Zarr
implementations. This means that, among other things, Zarr data types must be
serializable to metadata documents in accordance with the Zarr specifications,
which adds some unique aspects to the Zarr data type model.

The following sections explain Zarr’s data type model in greater detail and
demonstrate the Zarr Python APIs for working with Zarr data types.

###### Array Data Types#

Every Zarr array has a data type, which defines the meaning of the array’s
elements. An array’s data type is encoded in the JSON metadata for the array.
This means that the data type of an array must be JSON-serializable.

In Zarr V2, the data type of an array is stored in the `dtype` field in array
metadata. Zarr V3 changed the name of this field to `data_type` and also
defined new rules for the values that can be assigned to the `data_type`
field.

For example, in Zarr V2, the boolean array data type was represented in array
metadata as the string `"|b1"`. In Zarr V3, the same type is represented as
the string `"bool"`.

###### Scalars#

Zarr also specifies how array elements, i.e., scalars, are encoded in array
metadata. This is necessary because Zarr uses a field in array metadata to
define a default value for chunks that are not stored. This field, called
`fill_value` in both Zarr V2 and Zarr V3 metadata documents, contains a JSON
value that can be decoded to a scalar value compatible with the array’s data
type.

For the boolean data type, the scalar encoding is simple—booleans are natively
supported by JSON, so Zarr saves booleans as JSON booleans. Other scalars,
like floats or raw bytes, have more elaborate encoding schemes, and in some
cases, this scheme depends on the Zarr format version.

##### Data Types in Zarr Version 2#

Version 2 of the Zarr format defined its data types relative to [NumPy’s data
types](https://numpy.org/doc/2.1/reference/arrays.dtypes.html#data-type-
objects-dtype), and added a few non-NumPy data types as well. With one
exception (structured data types), the Zarr V2 JSON identifier for a data type
is just the NumPy `str` attribute of that data type:

    
    
    >>> import zarr
    >>> import numpy as np
    >>> import json
    >>>
    >>> store = {}
    >>> np_dtype = np.dtype('int64')
    >>> np_dtype.str
    '<i8'
    >>> z = zarr.create_array(store=store, shape=(1,), dtype=np_dtype, zarr_format=2)
    >>> dtype_meta = json.loads(store['.zarray'].to_bytes())["dtype"]
    >>> dtype_meta
    '<i8'
    

Note

The `<` character in the data type metadata encodes the
[endianness](https://numpy.org/doc/2.2/reference/generated/numpy.dtype.byteorder.html),
or “byte order,” of the data type. As per the NumPy model, in Zarr version 2
each data type has an endianness where applicable. However, Zarr version 3
data types do not store endianness information.

There are two special cases to consider: “structured” data types, and “object”
data types.

###### Structured Data Type#

NumPy allows the construction of a so-called “structured” data types comprised
of ordered collections of named fields, where each field is itself a distinct
NumPy data type. See the NumPy documentation
[here](https://numpy.org/doc/stable/user/basics.rec.html).

Crucially, NumPy does not use a special data type for structured data
types—instead, NumPy implements structured data types as an optional feature
of the so-called “Void” data type, which models arbitrary fixed-size byte
strings. The `str` attribute of a regular NumPy void data type is the same as
the `str` of a NumPy structured data type. This means that the `str` attribute
does not convey information about the fields contained in a structured data
type. For these reasons, Zarr V2 uses a special data type encoding for
structured data types. They are stored in JSON as lists of pairs, where the
first element is a string, and the second element is a Zarr V2 data type
specification. This representation supports recursion.

For example:

    
    
    >>> store = {}
    >>> np_dtype = np.dtype([('field_a', '>i2'), ('field_b', [('subfield_c', '>f4'), ('subfield_d', 'i2')])])
    >>> np_dtype.str
    '|V8'
    >>> z = zarr.create_array(store=store, shape=(1,), dtype=np_dtype, zarr_format=2)
    >>> dtype_meta = json.loads(store['.zarray'].to_bytes())["dtype"]
    >>> dtype_meta
    [['field_a', '>i2'], ['field_b', [['subfield_c', '>f4'], ['subfield_d', '<i2']]]]
    

###### Object Data Type#

The NumPy “object” type is essentially an array of references to arbitrary
Python objects. It can model arrays of variable-length UTF-8 strings, arrays
of variable-length byte strings, or even arrays of variable-length arrays,
each with a distinct data type. This makes the “object” data type expressive,
but also complicated to store.

Zarr Python cannot persistently store references to arbitrary Python objects.
But if each of those Python objects has a consistent type, then we can use a
special encoding procedure to store the array. This is how Zarr Python stores
variable-length UTF-8 strings, or variable-length byte strings.

Although these are separate data types in this library, they are both “object”
arrays in NumPy, which means they have the _same_ Zarr V2 string
representation: `"|O"`.

So for Zarr V2 we have to disambiguate different “object” data type arrays on
the basis of their encoding procedure, i.e., the codecs declared in the
`filters` and `compressor` attributes of array metadata.

If an array with data type “object” used the `"vlen-utf8"` codec, then it was
interpreted as an array of variable-length strings. If an array with data type
“object” used the `"vlen-bytes"` codec, then it was interpreted as an array of
variable-length byte strings.

This all means that the `dtype` field alone does not fully specify a data type
in Zarr V2. The name of the object codec used, if one was used, is also
required. Although this fact can be ignored for many simple numeric data
types, any comprehensive approach to Zarr V2 data types must either reject the
“object” data types or include the “object codec” identifier in the JSON form
of the basic data type model.

##### Data Types in Zarr Version 3#

The NumPy-based Zarr V2 data type representation was effective for simple data
types but struggled with more complex data types, like “object” and
“structured” data types. To address these limitations, Zarr V3 introduced
several key changes to how data types are represented:

  * Instead of copying NumPy character codecs, Zarr V3 defines an identifier for each data type. The basic data types are identified by strings like `"int8"`, `"int16"`, etc., and data types that require a configuration can be identified by a JSON object.

For example, this JSON object declares a datetime data type:

        
        {
          "name": "numpy.datetime64",
          "configuration": {
            "unit": "s",
            "scale_factor": 10
          }
        }
        

  * Zarr V3 data types do not have endianness. This is a departure from Zarr V2, where multi-byte data types are defined with endianness information. Instead, Zarr V3 requires that the endianness of encoded array chunks is specified in the `codecs` attribute of array metadata. The Zarr V3 specification leaves the in-memory endianness of decoded array chunks as an implementation detail.

For more about data types in Zarr V3, see the [V3 specification](https://zarr-
specs.readthedocs.io/en/latest/v3/data-types/index.html).

##### Data Types in Zarr Python#

The two Zarr formats that Zarr Python supports specify data types in different
ways: data types in Zarr version 2 are encoded as NumPy-compatible strings (or
lists, in the case of structured data types), while data types in Zarr V3 are
encoded as either strings or JSON objects. Zarr V3 data types do not have any
associated endianness information, unlike Zarr V2 data types.

Zarr Python needs to support both Zarr V2 and V3, which means we need to
abstract over these differences. We do this with an abstract Zarr data type
class: [ZDType](../api/zarr/dtype/index.html#zarr.dtype.ZDType), which
provides Zarr V2 and Zarr V3 compatibility routines for “native” data types.

In this context, a “native” data type is a Python class, typically defined in
another library, that models an array’s data type. For example,
`np.dtypes.UInt8DType` is a native data type defined in NumPy. Zarr Python
wraps the NumPy `uint8` with a `ZDType` instance called
[UInt8](../api/zarr/dtype/index.html#zarr.dtype.ZDType).

As of this writing, the only native data types Zarr Python supports are NumPy
data types. We could avoid the “native data type” jargon and just say “NumPy
data type,” but we do not want to rule out the possibility of using non-NumPy
array backends in the future.

Each data type supported by Zarr Python is modeled by a `ZDType` subclass,
which provides an API for the following operations:

  * Encoding and decoding a native data type

  * Encoding and decoding a data type to and from Zarr V2 and Zarr V3 array metadata

  * Encoding and decoding a scalar value to and from Zarr V2 and Zarr V3 array metadata

  * Casting a Python object to a scalar value consistent with the data type

###### List of data types#

The following section lists the data types built in to Zarr Python. With a few
exceptions, Zarr Python supports nearly all of the data types in NumPy. If you
need a data type that is not listed here, it’s possible to create it yourself:
see Adding New Data Types.

###### Boolean#

  * [Boolean](../api/zarr/dtype/index.html#zarr.dtype.Bool)

###### Integral#

  * [Signed 8-bit integer](../api/zarr/dtype/index.html#zarr.dtype.Int8)

  * [Signed 16-bit integer](../api/zarr/dtype/index.html#zarr.dtype.Int16)

  * [Signed 32-bit integer](../api/zarr/dtype/index.html#zarr.dtype.Int32)

  * [Signed 64-bit integer](../api/zarr/dtype/index.html#zarr.dtype.Int64)

  * [Unsigned 8-bit integer](../api/zarr/dtype/index.html#zarr.dtype.UInt8)

  * [Unsigned 16-bit integer](../api/zarr/dtype/index.html#zarr.dtype.UInt16)

  * [Unsigned 32-bit integer](../api/zarr/dtype/index.html#zarr.dtype.UInt32)

  * [Unsigned 64-bit integer](../api/zarr/dtype/index.html#zarr.dtype.UInt64)

###### Floating-point#

  * [16-bit floating-point](../api/zarr/dtype/index.html#zarr.dtype.Float16)

  * [32-bit floating-point](../api/zarr/dtype/index.html#zarr.dtype.Float32)

  * [64-bit floating-point](../api/zarr/dtype/index.html#zarr.dtype.Float64)

  * [64-bit complex floating-point](../api/zarr/dtype/index.html#zarr.dtype.Complex64)

  * [128-bit complex floating-point](../api/zarr/dtype/index.html#zarr.dtype.Complex128)

###### String#

  * [Fixed-length UTF-32 string](../api/zarr/dtype/index.html#zarr.dtype.FixedLengthUTF32)

  * [Variable-length UTF-8 string](../api/zarr/dtype/index.html#zarr.dtype.VariableLengthUTF8)

###### Bytes#

  * [Fixed-length null-terminated bytes](../api/zarr/dtype/index.html#zarr.dtype.NullTerminatedBytes)

  * [Fixed-length raw bytes](../api/zarr/dtype/index.html#zarr.dtype.RawBytes)

  * [Variable-length bytes](../api/zarr/dtype/index.html#zarr.dtype.VariableLengthBytes)

###### Temporal#

  * [DateTime64](../api/zarr/dtype/index.html#zarr.dtype.DateTime64)

  * [TimeDelta64](../api/zarr/dtype/index.html#zarr.dtype.TimeDelta64)

###### Struct-like#

  * [Structured](../api/zarr/dtype/index.html#zarr.dtype.Structured)

###### Example Usage#

This section will demonstrates the basic usage of Zarr data types.

Create a `ZDType` from a native data type:

    
    
    >>> from zarr.core.dtype import Int8
    >>> import numpy as np
    >>> int8 = Int8.from_native_dtype(np.dtype('int8'))
    

Convert back to a native data type:

    
    
    >>> native_dtype = int8.to_native_dtype()
    >>> assert native_dtype == np.dtype('int8')
    

Get the default scalar value for the data type:

    
    
    >>> default_value = int8.default_scalar()
    >>> assert default_value == np.int8(0)
    

Serialize to JSON for Zarr V2:

    
    
    >>> json_v2 = int8.to_json(zarr_format=2)
    >>> json_v2
    {'name': '|i1', 'object_codec_id': None}
    

Note

The representation returned by `to_json(zarr_format=2)` is more abstract than
the literal contents of Zarr V2 array metadata, because the JSON
representation used by the `ZDType` classes must be distinct across different
data types. As noted earlier, Zarr V2 identifies multiple distinct data types
with the “object” data type identifier `"|O"`. Extra information is needed to
disambiguate these data types from one another. That’s the reason for the
`object_codec_id` field you see here.

And for V3:

    
    
    >>> json_v3 = int8.to_json(zarr_format=3)
    >>> json_v3
    'int8'
    

Serialize a scalar value to JSON:

    
    
    >>> json_value = int8.to_json_scalar(42, zarr_format=3)
    >>> json_value
    42
    

Deserialize a scalar value from JSON:

    
    
    >>> scalar_value = int8.from_json_scalar(42, zarr_format=3)
    >>> assert scalar_value == np.int8(42)
    

###### Adding New Data Types#

Each Zarr data type is a separate Python class that inherits from
[ZDType](../api/zarr/dtype/index.html#zarr.dtype.ZDType). You can define a
custom data type by writing your own subclass of
[ZDType](../api/zarr/dtype/index.html#zarr.dtype.ZDType) and adding your data
type to the data type registry. A complete example of this process is included
below.

The source code for this example can be found in the
`examples/custom_dtype.py` file in the Zarr Python project directory.

    
    
    # /// script
    # requires-python = ">=3.11"
    # dependencies = [
    #   "zarr @ git+https://github.com/zarr-developers/zarr-python.git@main",
    #   "ml_dtypes==0.5.1",
    #   "pytest==8.4.1"
    # ]
    # ///
    #
    
    """
    Demonstrate how to extend Zarr Python by defining a new data type
    """
    
    import json
    import sys
    from pathlib import Path
    from typing import ClassVar, Literal, Self, TypeGuard, overload
    
    import ml_dtypes  # necessary to add extra dtypes to NumPy
    import numpy as np
    import pytest
    
    import zarr
    from zarr.core.common import JSON, ZarrFormat
    from zarr.core.dtype import ZDType, data_type_registry
    from zarr.core.dtype.common import (
        DataTypeValidationError,
        DTypeConfig_V2,
        DTypeJSON,
        check_dtype_spec_v2,
    )
    
    # This is the int2 array data type
    int2_dtype_cls = type(np.dtype("int2"))
    
    # This is the int2 scalar type
    int2_scalar_cls = ml_dtypes.int2
    
    
    class Int2(ZDType[int2_dtype_cls, int2_scalar_cls]):
        """
        This class provides a Zarr compatibility layer around the int2 data type (the ``dtype`` of a
        NumPy array of type int2) and the int2 scalar type (the ``dtype`` of the scalar value inside an int2 array).
        """
    
        # This field is as the key for the data type in the internal data type registry, and also
        # as the identifier for the data type when serializaing the data type to disk for zarr v3
        _zarr_v3_name: ClassVar[Literal["int2"]] = "int2"
        # this field will be used internally
        _zarr_v2_name: ClassVar[Literal["int2"]] = "int2"
    
        # we bind a class variable to the native data type class so we can create instances of it
        dtype_cls = int2_dtype_cls
    
        @classmethod
        def from_native_dtype(cls, dtype: np.dtype) -> Self:
            """Create an instance of this ZDType from a native dtype."""
            if cls._check_native_dtype(dtype):
                return cls()
            raise DataTypeValidationError(
                f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
            )
    
        def to_native_dtype(self: Self) -> int2_dtype_cls:
            """Create an int2 dtype instance from this ZDType"""
            return self.dtype_cls()
    
        @classmethod
        def _check_json_v2(cls, data: DTypeJSON) -> TypeGuard[DTypeConfig_V2[Literal["|b1"], None]]:
            """
            Type check for Zarr v2-flavored JSON.
    
            This will check that the input is a dict like this:
            .. code-block:: json
    
            {
                "name": "int2",
                "object_codec_id": None
            }
    
            Note that this representation differs from the ``dtype`` field looks like in zarr v2 metadata.
            Specifically, whatever goes into the ``dtype`` field in metadata is assigned to the ``name`` field here.
    
            See the Zarr docs for more information about the JSON encoding for data types.
            """
            return (
                check_dtype_spec_v2(data) and data["name"] == "int2" and data["object_codec_id"] is None
            )
    
        @classmethod
        def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[Literal["int2"]]:
            """
            Type check for Zarr V3-flavored JSON.
    
            Checks that the input is the string "int2".
            """
            return data == cls._zarr_v3_name
    
        @classmethod
        def _from_json_v2(cls, data: DTypeJSON) -> Self:
            """
            Create an instance of this ZDType from Zarr V3-flavored JSON.
            """
            if cls._check_json_v2(data):
                return cls()
            #  This first does a type check on the input, and if that passes we create an instance of the ZDType.
            msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v2_name!r}"
            raise DataTypeValidationError(msg)
    
        @classmethod
        def _from_json_v3(cls: type[Self], data: DTypeJSON) -> Self:
            """
            Create an instance of this ZDType from Zarr V3-flavored JSON.
    
            This first does a type check on the input, and if that passes we create an instance of the ZDType.
            """
            if cls._check_json_v3(data):
                return cls()
            msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
            raise DataTypeValidationError(msg)
    
        @overload  # type: ignore[override]
        def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[Literal["int2"], None]: ...
    
        @overload
        def to_json(self, zarr_format: Literal[3]) -> Literal["int2"]: ...
    
        def to_json(
            self, zarr_format: ZarrFormat
        ) -> DTypeConfig_V2[Literal["int2"], None] | Literal["int2"]:
            """
            Serialize this ZDType to v2- or v3-flavored JSON
    
            If the zarr_format is 2, then return a dict like this:
            .. code-block:: json
    
            {
                "name": "int2",
                "object_codec_id": None
            }
    
            If the zarr_format is 3, then return the string "int2"
    
            """
            if zarr_format == 2:
                return {"name": "int2", "object_codec_id": None}
            elif zarr_format == 3:
                return self._zarr_v3_name
            raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
    
        def _check_scalar(self, data: object) -> TypeGuard[int | ml_dtypes.int2]:
            """
            Check if a python object is a valid int2-compatible scalar
    
            The strictness of this type check is an implementation degree of freedom.
            You could be strict here, and only accept int2 values, or be open and accept any integer
            or any object and rely on exceptions from the int2 constructor that will be called in
            cast_scalar.
            """
            return isinstance(data, (int, int2_scalar_cls))
    
        def cast_scalar(self, data: object) -> ml_dtypes.int2:
            """
            Attempt to cast a python object to an int2.
    
            We first perform a type check to ensure that the input type is appropriate, and if that
            passes we call the int2 scalar constructor.
            """
            if self._check_scalar(data):
                return ml_dtypes.int2(data)
            msg = (
                f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
                f"data type {self}."
            )
            raise TypeError(msg)
    
        def default_scalar(self) -> ml_dtypes.int2:
            """
            Get the default scalar value. This will be used when automatically selecting a fill value.
            """
            return ml_dtypes.int2(0)
    
        def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> int:
            """
            Convert a python object to a JSON representation of an int2 scalar.
            This is necessary for taking user input for the ``fill_value`` attribute in array metadata.
    
            In this implementation, we optimistically convert the input to an int,
            and then check that it lies in the acceptable range for this data type.
            """
            # We could add a type check here, but we don't need to for this example
            val: int = int(data)  # type: ignore[call-overload]
            if val not in (-2, -1, 0, 1):
                raise ValueError("Invalid value. Expected -2, -1, 0, or 1.")
            return val
    
        def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> ml_dtypes.int2:
            """
            Read a JSON-serializable value as an int2 scalar.
    
            We first perform a type check to ensure that the JSON value is well-formed, then call the
            int2 scalar constructor.
    
            The base definition of this method requires that it take a zarr_format parameter because
            other data types serialize scalars differently in zarr v2 and v3, but we don't use this here.
    
            """
            if self._check_scalar(data):
                return ml_dtypes.int2(data)
            raise TypeError(f"Invalid type: {data}. Expected an int.")
    
    
    # after defining dtype class, it must be registered with the data type registry so zarr can use it
    data_type_registry.register(Int2._zarr_v3_name, Int2)
    
    
    # this parametrized function will create arrays in zarr v2 and v3 using our new data type
    @pytest.mark.parametrize("zarr_format", [2, 3])
    def test_custom_dtype(tmp_path: Path, zarr_format: Literal[2, 3]) -> None:
        # create array and write values
        z_w = zarr.create_array(
            store=tmp_path, shape=(4,), dtype="int2", zarr_format=zarr_format, compressors=None
        )
        z_w[:] = [-1, -2, 0, 1]
    
        # open the array
        z_r = zarr.open_array(tmp_path, mode="r")
    
        print(z_r.info_complete())
    
        # look at the array metadata
        if zarr_format == 2:
            meta_file = tmp_path / ".zarray"
        else:
            meta_file = tmp_path / "zarr.json"
        print(json.dumps(json.loads(meta_file.read_text()), indent=2))
    
    
    if __name__ == "__main__":
        # Run the example with printed output, and a dummy pytest configuration file specified.
        # Without the dummy configuration file, at test time pytest will attempt to use the
        # configuration file in the project root, which will error because Zarr is using some
        # plugins that are not installed in this example.
        sys.exit(pytest.main(["-s", __file__, f"-c {__file__}"]))
    

###### Data Type Resolution#

Although Zarr Python uses a different data type model from NumPy, you can
still define a Zarr array with a NumPy data type object:

    
    
    >>> from zarr import create_array
    >>> import numpy as np
    >>> a = create_array({}, shape=(10,), dtype=np.dtype('int'))
    >>> a
    <Array memory:... shape=(10,) dtype=int64>
    

Or a string representation of a NumPy data type:

    
    
    >>> a = create_array({}, shape=(10,), dtype='<i8')
    >>> a
    <Array memory:... shape=(10,) dtype=int64>
    

The `Array` object presents itself like a NumPy array, including exposing a
NumPy data type as its `dtype` attribute:

    
    
    >>> type(a.dtype)
    <class 'numpy.dtypes.Int64DType'>
    

But if we inspect the metadata for the array, we can see the Zarr data type
object:

    
    
    >>> type(a.metadata.data_type)
    <class 'zarr.core.dtype.npy.int.Int64'>
    

This example illustrates a general problem Zarr Python has to solve: how can
we allow users to specify a data type as a string or a NumPy `dtype` object,
and produce the right Zarr data type from that input? We call this process
“data type resolution.” Zarr Python also performs data type resolution when
reading stored arrays, although in this case the input is a JSON value instead
of a NumPy data type.

For simple data types like `int`, the solution could be extremely simple: just
maintain a lookup table that maps a NumPy data type to the Zarr data type
equivalent. But not all data types are so simple. Consider this case:

    
    
    >>> from zarr import create_array
    >>> import warnings
    >>> import numpy as np
    >>> warnings.simplefilter("ignore", category=FutureWarning)
    >>> a = create_array({}, shape=(10,), dtype=[('a', 'f8'), ('b', 'i8')])
    >>> a.dtype # this is the NumPy data type
    dtype([('a', '<f8'), ('b', '<i8')])
    >>> a.metadata.data_type # this is the Zarr data type
    Structured(fields=(('a', Float64(endianness='little')), ('b', Int64(endianness='little'))))
    

In this example, we created a [NumPy structured data
type](https://numpy.org/doc/stable/user/basics.rec.html#structured-datatypes).
This data type is a container that can hold any NumPy data type, which makes
it recursive. It is not possible to make a lookup table that relates all NumPy
structured data types to their Zarr equivalents, as there is a nearly
unbounded number of different structured data types. So instead of a static
lookup table, Zarr Python relies on a dynamic approach to data type
resolution.

Zarr Python defines a collection of Zarr data types. This collection, called a
“data type registry,” is essentially a dictionary where the keys are strings
(a canonical name for each data type), and the values are the data type
classes themselves. Dynamic data type resolution entails iterating over these
data type classes, invoking that class’ from_native_dtype method, and
returning a concrete data type instance if and only if exactly one of those
constructor invocations is successful.

In plain language, we take some user input, like a NumPy data type, offer it
to all the known data type classes, and return an instance of the one data
type class that can accept that user input.

We want to avoid a situation where the same native data type matches multiple
Zarr data types; that is, a NumPy data type should _uniquely_ specify a single
Zarr data type. But data type resolution is dynamic, so it’s not possible to
statically guarantee this uniqueness constraint. Therefore, we attempt data
type resolution against _every_ data type class, and if, for some reason, a
native data type matches multiple Zarr data types, we treat this as an error
and raise an exception.

If you have a NumPy data type and you want to get the corresponding `ZDType`
instance, you can use the `parse_dtype` function, which will use the dynamic
resolution described above. `parse_dtype` handles a range of input types:

  * NumPy data types:
        
        >>> import numpy as np
        >>> from zarr.dtype import parse_dtype
        >>> my_dtype = np.dtype('>M8[10s]')
        >>> parse_dtype(my_dtype, zarr_format=2)
        DateTime64(endianness='big', scale_factor=10, unit='s')
        

  * NumPy data type-compatible strings:
        
        >>> dtype_str = '>M8[10s]'
        >>> parse_dtype(dtype_str, zarr_format=2)
        DateTime64(endianness='big', scale_factor=10, unit='s')
        

  * `ZDType` instances:
        
        >>> from zarr.dtype import DateTime64
        >>> zdt = DateTime64(endianness='big', scale_factor=10, unit='s')
        >>> parse_dtype(zdt, zarr_format=2) # Use a ZDType (this is a no-op)
        DateTime64(endianness='big', scale_factor=10, unit='s')
        

  * Python dictionaries (requires `zarr_format=3`). These dictionaries must be consistent with the `JSON` form of the data type:
        
        >>> dt_dict = {"name": "numpy.datetime64", "configuration": {"unit": "s", "scale_factor": 10}}
        >>> parse_dtype(dt_dict, zarr_format=3)
        DateTime64(endianness='little', scale_factor=10, unit='s')
        >>> parse_dtype(dt_dict, zarr_format=3).to_json(zarr_format=3)
        {'name': 'numpy.datetime64', 'configuration': {'unit': 's', 'scale_factor': 10}}
        

#### Optimizing performance#

##### Chunk optimizations#

###### Chunk size and shape#

In general, chunks of at least 1 megabyte (1M) uncompressed size seem to
provide better performance, at least when using the Blosc compression library.

The optimal chunk shape will depend on how you want to access the data. E.g.,
for a 2-dimensional array, if you only ever take slices along the first
dimension, then chunk across the second dimension. If you know you want to
chunk across an entire dimension you can use the full size of that dimension
within the `chunks` argument, e.g.:

    
    
    >>> import zarr
    >>> z1 = zarr.create_array(store={}, shape=(10000, 10000), chunks=(100, 10000), dtype='int32')
    >>> z1.chunks
    (100, 10000)
    

Alternatively, if you only ever take slices along the second dimension, then
chunk across the first dimension, e.g.:

    
    
    >>> z2 = zarr.create_array(store={}, shape=(10000, 10000), chunks=(10000, 100), dtype='int32')
    >>> z2.chunks
    (10000, 100)
    

If you require reasonable performance for both access patterns then you need
to find a compromise, e.g.:

    
    
    >>> z3 = zarr.create_array(store={}, shape=(10000, 10000), chunks=(1000, 1000), dtype='int32')
    >>> z3.chunks
    (1000, 1000)
    

If you are feeling lazy, you can let Zarr guess a chunk shape for your data by
providing `chunks='auto'`, although please note that the algorithm for
guessing a chunk shape is based on simple heuristics and may be far from
optimal. E.g.:

    
    
    >>> z4 = zarr.create_array(store={}, shape=(10000, 10000), chunks='auto', dtype='int32')
    >>> z4.chunks
    (625, 625)
    

If you know you are always going to be loading the entire array into memory,
you can turn off chunks by providing `chunks` equal to `shape`, in which case
there will be one single chunk for the array:

    
    
    >>> z5 = zarr.create_array(store={}, shape=(10000, 10000), chunks=(10000, 10000), dtype='int32')
    >>> z5.chunks
    (10000, 10000)
    

###### Sharding#

If you have large arrays but need small chunks to efficiently access the data,
you can use sharding. Sharding provides a mechanism to store multiple chunks
in a single storage object or file. This can be useful because traditional
file systems and object storage systems may have performance issues storing
and accessing many files. Additionally, small files can be inefficient to
store if they are smaller than the block size of the file system.

Picking a good combination of chunk shape and shard shape is important for
performance. The chunk shape determines what unit of your data can be read
independently, while the shard shape determines what unit of your data can be
written efficiently.

For an example, consider you have a 100 GB array and need to read small chunks
of 1 MB. Without sharding, each chunk would be one file resulting in 100,000
files. That can already cause performance issues on some file systems. With
sharding, you could use a shard size of 1 GB. This would result in 1000 chunks
per file and 100 files in total, which seems manageable for most storage
systems. You would still be able to read each 1 MB chunk independently, but
you would need to write your data in 1 GB increments.

To use sharding, you need to specify the `shards` parameter when creating the
array.

    
    
    >>> z6 = zarr.create_array(store={}, shape=(10000, 10000, 1000), shards=(1000, 1000, 1000), chunks=(100, 100, 100), dtype='uint8')
    >>> z6.info
    Type               : Array
    Zarr format        : 3
    Data type          : UInt8()
    Fill value         : 0
    Shape              : (10000, 10000, 1000)
    Shard shape        : (1000, 1000, 1000)
    Chunk shape        : (100, 100, 100)
    Order              : C
    Read-only          : False
    Store type         : MemoryStore
    Filters            : ()
    Serializer         : BytesCodec(endian=None)
    Compressors        : (ZstdCodec(level=0, checksum=False),)
    No. bytes          : 100000000000 (93.1G)
    

###### Chunk memory layout#

The order of bytes **within each chunk** of an array can be changed via the
`order` config option, to use either C or Fortran layout. For multi-
dimensional arrays, these two layouts may provide different compression
ratios, depending on the correlation structure within the data. E.g.:

    
    
    >>> import numpy as np
    >>>
    >>> a = np.arange(100000000, dtype='int32').reshape(10000, 10000).T
    >>> c = zarr.create_array(store={}, shape=a.shape, chunks=(1000, 1000), dtype=a.dtype, config={'order': 'C'})
    >>> c[:] = a
    >>> c.info_complete()
    Type               : Array
    Zarr format        : 3
    Data type          : Int32(endianness='little')
    Fill value         : 0
    Shape              : (10000, 10000)
    Chunk shape        : (1000, 1000)
    Order              : C
    Read-only          : False
    Store type         : MemoryStore
    Filters            : ()
    Serializer         : BytesCodec(endian=<Endian.little: 'little'>)
    Compressors        : (ZstdCodec(level=0, checksum=False),)
    No. bytes          : 400000000 (381.5M)
    No. bytes stored   : 342588911 (326.7M)
    Storage ratio      : 1.2
    Chunks Initialized : 100
    >>> with zarr.config.set({'array.order': 'F'}):
    ...     f = zarr.create_array(store={}, shape=a.shape, chunks=(1000, 1000), dtype=a.dtype)
    ...     f[:] = a
    >>> f.info_complete()
    Type               : Array
    Zarr format        : 3
    Data type          : Int32(endianness='little')
    Fill value         : 0
    Shape              : (10000, 10000)
    Chunk shape        : (1000, 1000)
    Order              : F
    Read-only          : False
    Store type         : MemoryStore
    Filters            : ()
    Serializer         : BytesCodec(endian=<Endian.little: 'little'>)
    Compressors        : (ZstdCodec(level=0, checksum=False),)
    No. bytes          : 400000000 (381.5M)
    No. bytes stored   : 342588911 (326.7M)
    Storage ratio      : 1.2
    Chunks Initialized : 100
    

In the above example, Fortran order gives a better compression ratio. This is
an artificial example but illustrates the general point that changing the
order of bytes within chunks of an array may improve the compression ratio,
depending on the structure of the data, the compression algorithm used, and
which compression filters (e.g., byte-shuffle) have been applied.

###### Empty chunks#

It is possible to configure how Zarr handles the storage of chunks that are
“empty” (i.e., every element in the chunk is equal to the array’s fill value).
When creating an array with `write_empty_chunks=False`, Zarr will check
whether a chunk is empty before compression and storage. If a chunk is empty,
then Zarr does not store it, and instead deletes the chunk from storage if the
chunk had been previously stored.

This optimization prevents storing redundant objects and can speed up reads,
but the cost is added computation during array writes, since the contents of
each chunk must be compared to the fill value, and these advantages are
contingent on the content of the array. If you know that your data will form
chunks that are almost always non-empty, then there is no advantage to the
optimization described above. In this case, creating an array with
`write_empty_chunks=True` (the default) will instruct Zarr to write every
chunk without checking for emptiness.

The following example illustrates the effect of the `write_empty_chunks` flag
on the time required to write an array with different values.:

    
    
    >>> import zarr
    >>> import numpy as np
    >>> import time
    >>>
    >>> def timed_write(write_empty_chunks):
    ...     """
    ...     Measure the time required and number of objects created when writing
    ...     to a Zarr array with random ints or fill value.
    ...     """
    ...     chunks = (8192,)
    ...     shape = (chunks[0] * 1024,)
    ...     data = np.random.randint(0, 255, shape)
    ...     dtype = 'uint8'
    ...     arr = zarr.create_array(
    ...         f'data/example-{write_empty_chunks}.zarr',
    ...         shape=shape,
    ...         chunks=chunks,
    ...         dtype=dtype,
    ...         fill_value=0,
    ...         config={'write_empty_chunks': write_empty_chunks}
    ...      )
    ...     # initialize all chunks
    ...     arr[:] = 100
    ...     result = []
    ...     for value in (data, arr.fill_value):
    ...         start = time.time()
    ...         arr[:] = value
    ...         elapsed = time.time() - start
    ...         result.append((elapsed, arr.nchunks_initialized))
    ...     return result
    ... # log results
    >>> for write_empty_chunks in (True, False):
    ...     full, empty = timed_write(write_empty_chunks)
    ...     print(f'\nwrite_empty_chunks={write_empty_chunks}:\n\tRandom Data: {full[0]:.4f}s, {full[1]} objects stored\n\t Empty Data: {empty[0]:.4f}s, {empty[1]} objects stored\n')
    write_empty_chunks=True:
         Random Data: ..., 1024 objects stored
          Empty Data: ...s, 1024 objects stored
    
    write_empty_chunks=False:
         Random Data: ...s, 1024 objects stored
          Empty Data: ...s, 0 objects stored
    

In this example, writing random data is slightly slower with
`write_empty_chunks=True`, but writing empty data is substantially faster and
generates far fewer objects in storage.

###### Changing chunk shapes (rechunking)#

Coming soon.

##### Parallel computing and synchronization#

Coming soon.

##### Pickle support#

Zarr arrays and groups can be pickled, as long as the underlying store object
can be pickled. With the exception of the `zarr.storage.MemoryStore`, any of
the storage classes provided in the `zarr.storage` module can be pickled.

If an array or group is backed by a persistent store such as the a
`zarr.storage.LocalStore`, `zarr.storage.ZipStore` or
`zarr.storage.FsspecStore` then the store data **are not** pickled. The only
thing that is pickled is the necessary parameters to allow the store to re-
open any underlying files or databases upon being unpickled.

E.g., pickle/unpickle an local store array:

    
    
    >>> import pickle
    >>> data = np.arange(100000)
    >>> z1 = zarr.create_array(store='data/example-2.zarr', shape=data.shape, chunks=data.shape, dtype=data.dtype)
    >>> z1[:] = data
    >>> s = pickle.dumps(z1)
    >>> z2 = pickle.loads(s)
    >>> z1 == z2
    True
    >>> np.all(z1[:] == z2[:])
    np.True_
    

##### Configuring Blosc#

Coming soon.

#### Consolidated metadata#

Warning

The Consolidated Metadata feature in Zarr-Python is considered experimental
for v3 stores. [zarr-specs#309](https://github.com/zarr-developers/zarr-
specs/pull/309) has proposed a formal extension to the v3 specification to
support consolidated metadata.

Zarr-Python implements the [Consolidated Metadata](https://github.com/zarr-
developers/zarr-specs/pull/309) for v2 and v3 stores. Consolidated metadata
can reduce the time needed to load the metadata for an entire hierarchy,
especially when the metadata is being served over a network. Consolidated
metadata essentially stores all the metadata for a hierarchy in the metadata
of the root Group.

##### Usage#

If consolidated metadata is present in a Zarr Group’s metadata then it is used
by default. The initial read to open the group will need to communicate with
the store (reading from a file for a `zarr.storage.LocalStore`, making a
network request for a `zarr.storage.FsspecStore`). After that, any subsequent
metadata reads get child Group or Array nodes will _not_ require reads from
the store.

In Python, the consolidated metadata is available on the
`.consolidated_metadata` attribute of the `GroupMetadata` object.

    
    
    >>> import zarr
    >>>
    >>> store = zarr.storage.MemoryStore()
    >>> group = zarr.create_group(store=store)
    >>> group.create_array(shape=(1,), name='a', dtype='float64')
    <Array memory://.../a shape=(1,) dtype=float64>
    >>> group.create_array(shape=(2, 2), name='b', dtype='float64')
    <Array memory://.../b shape=(2, 2) dtype=float64>
    >>> group.create_array(shape=(3, 3, 3), name='c', dtype='float64')
    <Array memory://.../c shape=(3, 3, 3) dtype=float64>
    >>> zarr.consolidate_metadata(store)
    <Group memory://...>
    

If we open that group, the Group’s metadata has a
`zarr.core.group.ConsolidatedMetadata` that can be used.:

    
    
    >>> consolidated = zarr.open_group(store=store)
    >>> consolidated_metadata = consolidated.metadata.consolidated_metadata.metadata
    >>> from pprint import pprint
    >>> pprint(dict(sorted(consolidated_metadata.items())))
    {'a': ArrayV3Metadata(shape=(1,),
                           data_type=Float64(endianness='little'),
                           chunk_grid=RegularChunkGrid(chunk_shape=(1,)),
                           chunk_key_encoding=DefaultChunkKeyEncoding(name='default',
                                                                      separator='/'),
                           fill_value=np.float64(0.0),
                           codecs=(BytesCodec(endian=<Endian.little: 'little'>),
                                   ZstdCodec(level=0, checksum=False)),
                           attributes={},
                           dimension_names=None,
                           zarr_format=3,
                           node_type='array',
                           storage_transformers=()),
      'b': ArrayV3Metadata(shape=(2, 2),
                           data_type=Float64(endianness='little'),
                           chunk_grid=RegularChunkGrid(chunk_shape=(2, 2)),
                           chunk_key_encoding=DefaultChunkKeyEncoding(name='default',
                                                                      separator='/'),
                           fill_value=np.float64(0.0),
                           codecs=(BytesCodec(endian=<Endian.little: 'little'>),
                                   ZstdCodec(level=0, checksum=False)),
                           attributes={},
                           dimension_names=None,
                           zarr_format=3,
                           node_type='array',
                           storage_transformers=()),
      'c': ArrayV3Metadata(shape=(3, 3, 3),
                           data_type=Float64(endianness='little'),
                           chunk_grid=RegularChunkGrid(chunk_shape=(3, 3, 3)),
                           chunk_key_encoding=DefaultChunkKeyEncoding(name='default',
                                                                      separator='/'),
                           fill_value=np.float64(0.0),
                           codecs=(BytesCodec(endian=<Endian.little: 'little'>),
                                   ZstdCodec(level=0, checksum=False)),
                           attributes={},
                           dimension_names=None,
                           zarr_format=3,
                           node_type='array',
                           storage_transformers=())}
    

Operations on the group to get children automatically use the consolidated
metadata.:

    
    
    >>> consolidated['a']  # no read / HTTP request to the Store is required
    <Array memory://.../a shape=(1,) dtype=float64>
    

With nested groups, the consolidated metadata is available on the children,
recursively.:

    
    
    >>> child = group.create_group('child', attributes={'kind': 'child'})
    >>> grandchild = child.create_group('child', attributes={'kind': 'grandchild'})
    >>> consolidated = zarr.consolidate_metadata(store)
    >>>
    >>> consolidated['child'].metadata.consolidated_metadata
    ConsolidatedMetadata(metadata={'child': GroupMetadata(attributes={'kind': 'grandchild'}, zarr_format=3, consolidated_metadata=ConsolidatedMetadata(metadata={}, kind='inline', must_understand=False), node_type='group')}, kind='inline', must_understand=False)
    

##### Synchronization and Concurrency#

Consolidated metadata is intended for read-heavy use cases on slowly changing
hierarchies. For hierarchies where new nodes are constantly being added,
removed, or modified, consolidated metadata may not be desirable.

  1. It will add some overhead to each update operation, since the metadata would need to be re-consolidated to keep it in sync with the store.

  2. Readers using consolidated metadata will regularly see a “past” version of the metadata, at the time they read the root node with its consolidated metadata.

##### Stores Without Support for Consolidated Metadata#

Some stores may want to opt out of the consolidated metadata mechanism. This
may be for several reasons like:

  * They want to maintain read-write consistency, which is challenging with consolidated metadata.

  * They have their own consolidated metadata mechanism.

  * They offer good enough performance without need for consolidation.

This type of store can declare it doesn’t want consolidation by implementing
Store.supports_consolidated_metadata and returning False. For stores that
don’t support consolidation, Zarr will:

  * Raise an error on consolidate_metadata calls, maintaining the store in its unconsolidated state.

  * Raise an error in AsyncGroup.open(…, use_consolidated=True)

  * Not use consolidated metadata in AsyncGroup.open(…, use_consolidated=None)

#### Extending Zarr#

Zarr-Python 3 was designed to be extensible. This means that you can extend
the library by writing custom classes and plugins. Currently, Zarr can be
extended in the following ways:

##### Custom codecs#

Note

This section explains how custom codecs can be created for Zarr format 3
arrays. For Zarr format 2, codecs should subclass the
[numcodecs.abc.Codec](https://numcodecs.readthedocs.io/en/stable/abc.html#numcodecs.abc.Codec)
base class and register through
[numcodecs.registry.register_codec](https://numcodecs.readthedocs.io/en/stable/registry.html#numcodecs.registry.register_codec).

There are three types of codecs in Zarr: \- array-to-array \- array-to-bytes
\- bytes-to-bytes

Array-to-array codecs are used to transform the array data before serializing
to bytes. Examples include delta encoding or scaling codecs. Array-to-bytes
codecs are used for serializing the array data to bytes. In Zarr, the main
codec to use for numeric arrays is the `zarr.codecs.BytesCodec`. Bytes-to-
bytes codecs transform the serialized bytestreams of the array data. Examples
include compression codecs, such as `zarr.codecs.GzipCodec`,
`zarr.codecs.BloscCodec` or `zarr.codecs.ZstdCodec`, and codecs that add a
checksum to the bytestream, such as `zarr.codecs.Crc32cCodec`.

Custom codecs for Zarr are implemented by subclassing the relevant base class,
see `zarr.abc.codec.ArrayArrayCodec`, `zarr.abc.codec.ArrayBytesCodec` and
`zarr.abc.codec.BytesBytesCodec`. Most custom codecs should implemented the
`_encode_single` and `_decode_single` methods. These methods operate on single
chunks of the array data. Alternatively, custom codecs can implement the
`encode` and `decode` methods, which operate on batches of chunks, in case the
codec is intended to implement its own batch processing.

Custom codecs should also implement the following methods:

  * `compute_encoded_size`, which returns the byte size of the encoded data given the byte size of the original data. It should raise `NotImplementedError` for codecs with variable-sized outputs, such as compression codecs.

  * `validate` (optional), which can be used to check that the codec metadata is compatible with the array metadata. It should raise errors if not.

  * `resolve_metadata` (optional), which is important for codecs that change the shape, dtype or fill value of a chunk.

  * `evolve_from_array_spec` (optional), which can be useful for automatically filling in codec configuration metadata from the array metadata.

To use custom codecs in Zarr, they need to be registered using the [entrypoint
mechanism](https://packaging.python.org/en/latest/specifications/entry-
points/). Commonly, entrypoints are declared in the `pyproject.toml` of your
package under the `[project.entry-points."zarr.codecs"]` section. Zarr will
automatically discover and load all codecs registered with the entrypoint
mechanism from imported modules.

    
    
    [project.entry-points."zarr.codecs"]
    "custompackage.fancy_codec" = "custompackage:FancyCodec"
    

New codecs need to have their own unique identifier. To avoid naming
collisions, it is strongly recommended to prefix the codec identifier with a
unique name. For example, the codecs from `numcodecs` are prefixed with
`numcodecs.`, e.g. `numcodecs.delta`.

Note

Note that the extension mechanism for the Zarr format 3 is still under
development. Requirements for custom codecs including the choice of codec
identifiers might change in the future.

It is also possible to register codecs as replacements for existing codecs.
This might be useful for providing specialized implementations, such as GPU-
based codecs. In case of multiple codecs, the `zarr.core.config` mechanism can
be used to select the preferred implementation.

##### Custom stores#

Coming soon.

##### Custom array buffers#

Zarr-python provides control over where and how arrays stored in memory
through `zarr.buffer`. Currently both CPU (the default) and GPU
implementations are provided (see Using GPUs with Zarr for more). You can
implement your own buffer classes by implementing the interface defined in
`zarr.abc.buffer`.

##### Other extensions#

In the future, Zarr will support writing custom custom data types and chunk
grids.

#### Using GPUs with Zarr#

Zarr can use GPUs to accelerate your workload by running
`zarr.config.enable_gpu()`.

Note

zarr-python currently supports reading the ndarray data into device (GPU)
memory as the final stage of the codec pipeline. Data will still be read into
or copied to host (CPU) memory for encoding and decoding.

In the future, codecs will be available compressing and decompressing data on
the GPU, avoiding the need to move data between the host and device for
compression and decompression.

##### Reading data into device memory#

`zarr.config.enable_gpu()` configures Zarr to use GPU memory for the data
buffers used internally by Zarr.

    
    
    >>> import zarr
    >>> import cupy as cp  
    >>> zarr.config.enable_gpu()  
    >>> store = zarr.storage.MemoryStore()  
    >>> z = zarr.create_array(  
    ...     store=store, shape=(100, 100), chunks=(10, 10), dtype="float32",
    ... )
    >>> type(z[:10, :10])  
    cupy.ndarray
    

Note that the output type is a `cupy.ndarray` rather than a NumPy array.

## zarr#

### Submodules#

#### zarr.abc#

##### Submodules#

###### zarr.abc.buffer#

###### Classes#

`ArrayLike` | Protocol for the array-like type that underlie Buffer  
---|---  
`Buffer` | A flat contiguous memory block  
`BufferPrototype` | Prototype of the Buffer and NDBuffer class  
`NDArrayLike` | Protocol for the nd-array-like type that underlie NDBuffer  
`NDBuffer` | An n-dimensional memory block  
  
###### Module Contents#

_class _zarr.abc.buffer.ArrayLike#

    

Bases: `Protocol`

Protocol for the array-like type that underlie Buffer

_property _dtype _:
[numpy.dtype](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype
"\(in NumPy v2.3\)")[Any]_#

    

_property _ndim _: [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")_#

    

_property _size _: [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")_#

    

_class _zarr.abc.buffer.Buffer(_array_like : ArrayLike_)#

    

Bases: [`abc.ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "\(in
Python v3.13\)")

A flat contiguous memory block

We use Buffer throughout Zarr to represent a contiguous block of memory.

A Buffer is backed by a underlying array-like instance that represents the
memory. The memory type is unspecified; can be regular host memory, CUDA
device memory, or something else. The only requirement is that the array-like
instance can be copied/converted to a regular Numpy array (host memory).

Parameters:

    

**array_like**

    

array-like object that must be 1-dim, contiguous, and byte dtype.

Notes

This buffer is untyped, so all indexing and sizes are in bytes.

as_array_like() -> ArrayLike#

    

Returns the underlying array (host or device memory) of this buffer

This will never copy data.

Returns:

    

The underlying 1d array such as a NumPy or CuPy array.

    

as_buffer_like() -> zarr.core.common.BytesLike#

    

Returns the buffer as an object that implements the Python buffer protocol.

Returns:

    

An object that implements the Python buffer protocol

    

Notes

Might have to copy data, since the implementation uses .as_numpy_array().

_abstract _as_numpy_array() -> numpy.typing.NDArray[Any]#

    

Returns the buffer as a NumPy array (host memory).

Returns:

    

NumPy array of this buffer (might be a data copy)

    

Notes

Might have to copy data, consider using .as_array_like() instead.

_classmethod _create_zero_length() -> Self#

    

Abstractmethod:

    

Create an empty buffer with length zero

Returns:

    

New empty 0-length buffer

    

_classmethod _from_array_like(_array_like : ArrayLike_) -> Self#

    

Create a new buffer of an array-like object

Parameters:

    

**array_like**

    

array-like object that must be 1-dim, contiguous, and byte dtype.

Returns:

    

New buffer representing array_like

    

_classmethod _from_buffer(_buffer : Buffer_) -> Self#

    

Abstractmethod:

    

Create a new buffer of an existing Buffer

This is useful if you want to ensure that an existing buffer is of the correct
subclass of Buffer. E.g., MemoryStore uses this to return a buffer instance of
the subclass specified by its BufferPrototype argument.

Typically, this only copies data if the data has to be moved between memory
types, such as from host to device memory.

Parameters:

    

**buffer**

    

buffer object.

Returns:

    

A new buffer representing the content of the input buffer

    

Notes

Subclasses of Buffer must override this method to implement more optimal
conversions that avoid copies where possible

_classmethod _from_bytes(_bytes_like : zarr.core.common.BytesLike_) -> Self#

    

Abstractmethod:

    

Create a new buffer of a bytes-like object (host memory)

Parameters:

    

**bytes_like**

    

bytes-like object

Returns:

    

New buffer representing bytes_like

    

to_bytes() -> [bytes](https://docs.python.org/3/library/stdtypes.html#bytes
"\(in Python v3.13\)")#

    

Returns the buffer as bytes (host memory).

Returns:

    

bytes of this buffer (data copy)

    

Warning

Will always copy data, only use this method for small buffers such as metadata
buffers. If possible, use .as_numpy_array() or .as_array_like() instead.

_class _zarr.abc.buffer.BufferPrototype#

    

Bases: `NamedTuple`

Prototype of the Buffer and NDBuffer class

The protocol must be pickable.

Attributes:

    

**buffer**

    

The Buffer class to use when Zarr needs to create new Buffer.

**nd_buffer**

    

The NDBuffer class to use when Zarr needs to create new NDBuffer.

buffer _: [type](https://docs.python.org/3/library/functions.html#type "\(in
Python v3.13\)")[Buffer]_#

    

nd_buffer _: [type](https://docs.python.org/3/library/functions.html#type
"\(in Python v3.13\)")[NDBuffer]_#

    

_class _zarr.abc.buffer.NDArrayLike#

    

Bases: `Protocol`

Protocol for the nd-array-like type that underlie NDBuffer

all() -> [bool](https://docs.python.org/3/library/functions.html#bool "\(in
Python v3.13\)")#

    

astype(

    _dtype : numpy.typing.DTypeLike_,
    _order : Literal['K', 'A', 'C', 'F'] = ..._,
    _*_ ,
    _copy : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = ..._,
) -> Self#

    

copy() -> Self#

    

fill(_value : Any_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

ravel(_order : Literal['K', 'A', 'C', 'F'] = ..._) -> Self#

    

reshape(

    _shape : zarr.core.common.ChunkCoords | Literal[-1]_,
    _*_ ,
    _order : Literal['A', 'C', 'F'] = ..._,
) -> Self#

    

transpose(

    _axes : SupportsIndex | [collections.abc.Sequence](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "\(in Python v3.13\)")[SupportsIndex] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")_,
) -> Self#

    

view(_dtype : numpy.typing.DTypeLike_) -> Self#

    

_property _dtype _:
[numpy.dtype](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype
"\(in NumPy v2.3\)")[Any]_#

    

_property _ndim _: [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")_#

    

_property _shape _: zarr.core.common.ChunkCoords_#

    

_property _size _: [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")_#

    

_class _zarr.abc.buffer.NDBuffer(_array : NDArrayLike_)#

    

An n-dimensional memory block

We use NDBuffer throughout Zarr to represent a n-dimensional memory block.

A NDBuffer is backed by a underlying ndarray-like instance that represents the
memory. The memory type is unspecified; can be regular host memory, CUDA
device memory, or something else. The only requirement is that the ndarray-
like instance can be copied/converted to a regular Numpy array (host memory).

Parameters:

    

**array** ndarray_like

    

ndarray-like object that is convertible to a regular Numpy array.

Notes

The two buffer classes Buffer and NDBuffer are very similar. In fact, Buffer
is a special case of NDBuffer where dim=1, stride=1, and dtype=”B”. However,
in order to use Python’s type system to differentiate between the contiguous
Buffer and the n-dim (non-contiguous) NDBuffer, we keep the definition of the
two classes separate.

all_equal(_other : Any_, _equal_nan :
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)") = True_) ->
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")#

    

Compare to other using np.array_equal.

as_ndarray_like() -> NDArrayLike#

    

Returns the underlying array (host or device memory) of this buffer

This will never copy data.

Returns:

    

The underlying array such as a NumPy or CuPy array.

    

_abstract _as_numpy_array() -> numpy.typing.NDArray[Any]#

    

Returns the buffer as a NumPy array (host memory).

Returns:

    

NumPy array of this buffer (might be a data copy)

    

Warning

Might have to copy data, consider using .as_ndarray_like() instead.

as_scalar() -> ScalarType#

    

Returns the buffer as a scalar value

astype(

    _dtype : numpy.typing.DTypeLike_,
    _order : Literal['K', 'A', 'C', 'F'] = 'K'_,
) -> Self#

    

copy() -> Self#

    

_classmethod _create(

    _*_ ,
    _shape : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")]_,
    _dtype : numpy.typing.DTypeLike_,
    _order : Literal['C', 'F'] = 'C'_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> Self#

    

Abstractmethod:

    

Create a new buffer and its underlying ndarray-like object

Parameters:

    

**shape**

    

The shape of the buffer and its underlying ndarray-like object

**dtype**

    

The datatype of the buffer and its underlying ndarray-like object

**order**

    

Whether to store multi-dimensional data in row-major (C-style) or column-major
(Fortran-style) order in memory.

**fill_value**

    

If not None, fill the new buffer with a scalar value.

Returns:

    

New buffer representing a new ndarray_like object

    

Notes

A subclass can overwrite this method to create a ndarray-like object other
then the default Numpy array.

_classmethod _empty(

    _shape : zarr.core.common.ChunkCoords_,
    _dtype : numpy.typing.DTypeLike_,
    _order : Literal['C', 'F'] = 'C'_,
) -> Self#

    

Create an empty buffer with the given shape, dtype, and order.

This method can be faster than `NDBuffer.create` because it doesn’t have to
initialize the memory used by the underlying ndarray-like object.

Parameters:

    

**shape**

    

The shape of the buffer and its underlying ndarray-like object

**dtype**

    

The datatype of the buffer and its underlying ndarray-like object

**order**

    

Whether to store multi-dimensional data in row-major (C-style) or column-major
(Fortran-style) order in memory.

Returns:

    

buffer

    

New buffer representing a new ndarray_like object with empty data.

See also

`NDBuffer.create`

    

Create a new buffer with some initial fill value.

fill(_value : Any_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_classmethod _from_ndarray_like(_ndarray_like : NDArrayLike_) -> Self#

    

Create a new buffer of a ndarray-like object

Parameters:

    

**ndarray_like**

    

ndarray-like object

Returns:

    

New buffer representing ndarray_like

    

_classmethod _from_numpy_array(_array_like : numpy.typing.ArrayLike_) -> Self#

    

Abstractmethod:

    

Create a new buffer of Numpy array-like object

Parameters:

    

**array_like**

    

Object that can be coerced into a Numpy array

Returns:

    

New buffer representing array_like

    

reshape(_newshape : zarr.core.common.ChunkCoords | Literal[-1]_) -> Self#
    

squeeze(_axis : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple
"\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), Ellipsis]_) -> Self#

    

transpose(

    _axes : SupportsIndex | [collections.abc.Sequence](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "\(in Python v3.13\)")[SupportsIndex] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")_,
) -> Self#

    

_property _byteorder _: zarr.codecs.bytes.Endian_#

    

_property _dtype _:
[numpy.dtype](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype
"\(in NumPy v2.3\)")[Any]_#

    

_property _shape _:
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), Ellipsis]_#

    

###### zarr.abc.codec#

###### Attributes#

`CodecInput` |   
---|---  
`CodecOutput` |   
  
###### Classes#

`ArrayArrayCodec` | Base class for array-to-array codecs.  
---|---  
`ArrayBytesCodec` | Base class for array-to-bytes codecs.  
`ArrayBytesCodecPartialDecodeMixin` | Mixin for array-to-bytes codecs that implement partial decoding.  
`ArrayBytesCodecPartialEncodeMixin` | Mixin for array-to-bytes codecs that implement partial encoding.  
`BaseCodec` | Generic base class for codecs.  
`BytesBytesCodec` | Base class for bytes-to-bytes codecs.  
`CodecPipeline` | Base class for implementing CodecPipeline.  
  
###### Module Contents#

_class _zarr.abc.codec.ArrayArrayCodec#

    

Bases: `BaseCodec`[`zarr.core.buffer.NDBuffer`, `zarr.core.buffer.NDBuffer`]

Base class for array-to-array codecs.

_abstract _compute_encoded_size(

    _input_byte_length : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")_,
    _chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> [int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Given an input byte length, this method returns the output byte length. Raises
a NotImplementedError for codecs with variable-sized outputs (e.g.
compressors).

Parameters:

    

**input_byte_length** int

    
**chunk_spec** ArraySpec

    
Returns:

    

int

    

_async _decode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Decodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecOutput | None, ArraySpec]]
    

Ordered set of encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecInput | None]
    

_async _encode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Encodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecInput | None, ArraySpec]]
    

Ordered set of to-be-encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecOutput | None]
    

evolve_from_array_spec(_array_spec : zarr.core.array_spec.ArraySpec_) -> Self#

    

Fills in codec configuration parameters that can be automatically inferred
from the array metadata.

Parameters:

    

**array_spec** ArraySpec

    
Returns:

    

Self

    

_classmethod _from_dict(_data :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), zarr.core.common.JSON]_) -> Self#

    

Create an instance of the model from a dictionary

resolve_metadata(

    _chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> zarr.core.array_spec.ArraySpec#

    

Computed the spec of the chunk after it has been encoded by the codec. This is
important for codecs that change the shape, data type or fill value of a
chunk. The spec will then be used for subsequent codecs in the pipeline.

Parameters:

    

**chunk_spec** ArraySpec

    
Returns:

    

ArraySpec

    

to_dict() -> [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"), zarr.core.common.JSON]#

    

Recursively serialize this model to a dictionary. This method inspects the
fields of self and calls x.to_dict() for any fields that are instances of
Metadata. Sequences of Metadata are similarly recursed into, and the output of
that recursion is collected in a list.

validate(

    _*_ ,
    _shape : zarr.core.common.ChunkCoords_,
    _dtype : zarr.core.dtype.wrapper.ZDType[zarr.core.dtype.wrapper.TBaseDType, zarr.core.dtype.wrapper.TBaseScalar]_,
    _chunk_grid : zarr.core.chunk_grids.ChunkGrid_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Validates that the codec configuration is compatible with the array metadata.
Raises errors when the codec configuration is not compatible.

Parameters:

    

**shape** ChunkCoords

    

The array shape

**dtype** np.dtype[Any]

    

The array data type

**chunk_grid** ChunkGrid

    

The array chunk grid

is_fixed_size _: [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")_#

    

_class _zarr.abc.codec.ArrayBytesCodec#

    

Bases: `BaseCodec`[`zarr.core.buffer.NDBuffer`, `zarr.core.buffer.Buffer`]

Base class for array-to-bytes codecs.

_abstract _compute_encoded_size(

    _input_byte_length : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")_,
    _chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> [int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Given an input byte length, this method returns the output byte length. Raises
a NotImplementedError for codecs with variable-sized outputs (e.g.
compressors).

Parameters:

    

**input_byte_length** int

    
**chunk_spec** ArraySpec

    
Returns:

    

int

    

_async _decode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Decodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecOutput | None, ArraySpec]]
    

Ordered set of encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecInput | None]
    

_async _encode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Encodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecInput | None, ArraySpec]]
    

Ordered set of to-be-encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecOutput | None]
    

evolve_from_array_spec(_array_spec : zarr.core.array_spec.ArraySpec_) -> Self#

    

Fills in codec configuration parameters that can be automatically inferred
from the array metadata.

Parameters:

    

**array_spec** ArraySpec

    
Returns:

    

Self

    

_classmethod _from_dict(_data :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), zarr.core.common.JSON]_) -> Self#

    

Create an instance of the model from a dictionary

resolve_metadata(

    _chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> zarr.core.array_spec.ArraySpec#

    

Computed the spec of the chunk after it has been encoded by the codec. This is
important for codecs that change the shape, data type or fill value of a
chunk. The spec will then be used for subsequent codecs in the pipeline.

Parameters:

    

**chunk_spec** ArraySpec

    
Returns:

    

ArraySpec

    

to_dict() -> [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"), zarr.core.common.JSON]#

    

Recursively serialize this model to a dictionary. This method inspects the
fields of self and calls x.to_dict() for any fields that are instances of
Metadata. Sequences of Metadata are similarly recursed into, and the output of
that recursion is collected in a list.

validate(

    _*_ ,
    _shape : zarr.core.common.ChunkCoords_,
    _dtype : zarr.core.dtype.wrapper.ZDType[zarr.core.dtype.wrapper.TBaseDType, zarr.core.dtype.wrapper.TBaseScalar]_,
    _chunk_grid : zarr.core.chunk_grids.ChunkGrid_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Validates that the codec configuration is compatible with the array metadata.
Raises errors when the codec configuration is not compatible.

Parameters:

    

**shape** ChunkCoords

    

The array shape

**dtype** np.dtype[Any]

    

The array data type

**chunk_grid** ChunkGrid

    

The array chunk grid

is_fixed_size _: [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")_#

    

_class _zarr.abc.codec.ArrayBytesCodecPartialDecodeMixin#

    

Mixin for array-to-bytes codecs that implement partial decoding.

_async _decode_partial(

    _batch_info : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[zarr.abc.store.ByteGetter, zarr.core.indexing.SelectorTuple, zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[zarr.core.buffer.NDBuffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Partially decodes a batch of chunks. This method determines parts of a chunk
from the slice selection, fetches these parts from the store (via ByteGetter)
and decodes them.

Parameters:

    

**batch_info** Iterable[tuple[ByteGetter, SelectorTuple, ArraySpec]]

    

Ordered set of information about slices of encoded chunks. The slice selection
determines which parts of the chunk will be fetched. The ByteGetter is used to
fetch the necessary bytes. The chunk spec contains information about the
construction of an array from the bytes.

Returns:

    

Iterable[NDBuffer | None]
    

_class _zarr.abc.codec.ArrayBytesCodecPartialEncodeMixin#

    

Mixin for array-to-bytes codecs that implement partial encoding.

_async _encode_partial(

    _batch_info : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[zarr.abc.store.ByteSetter, zarr.core.buffer.NDBuffer, zarr.core.indexing.SelectorTuple, zarr.core.array_spec.ArraySpec]]_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Partially encodes a batch of chunks. This method determines parts of a chunk
from the slice selection, encodes them and writes these parts to the store
(via ByteSetter). If merging with existing chunk data in the store is
necessary, this method will read from the store first and perform the merge.

Parameters:

    

**batch_info** Iterable[tuple[ByteSetter, NDBuffer, SelectorTuple, ArraySpec]]

    

Ordered set of information about slices of to-be-encoded chunks. The slice
selection determines which parts of the chunk will be encoded. The ByteSetter
is used to write the necessary bytes and fetch bytes for existing chunk data.
The chunk spec contains information about the chunk.

_class _zarr.abc.codec.BaseCodec#

    

Bases: `zarr.abc.metadata.Metadata`, `Generic`[`CodecInput`, `CodecOutput`]

Generic base class for codecs.

Codecs can be registered via zarr.codecs.registry.

Warning

This class is not intended to be directly, please use ArrayArrayCodec,
ArrayBytesCodec or BytesBytesCodec for subclassing.

_abstract _compute_encoded_size(

    _input_byte_length : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")_,
    _chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> [int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Given an input byte length, this method returns the output byte length. Raises
a NotImplementedError for codecs with variable-sized outputs (e.g.
compressors).

Parameters:

    

**input_byte_length** int

    
**chunk_spec** ArraySpec

    
Returns:

    

int

    

_async _decode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Decodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecOutput | None, ArraySpec]]
    

Ordered set of encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecInput | None]
    

_async _encode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Encodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecInput | None, ArraySpec]]
    

Ordered set of to-be-encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecOutput | None]
    

evolve_from_array_spec(_array_spec : zarr.core.array_spec.ArraySpec_) -> Self#

    

Fills in codec configuration parameters that can be automatically inferred
from the array metadata.

Parameters:

    

**array_spec** ArraySpec

    
Returns:

    

Self

    

_classmethod _from_dict(_data :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), zarr.core.common.JSON]_) -> Self#

    

Create an instance of the model from a dictionary

resolve_metadata(

    _chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> zarr.core.array_spec.ArraySpec#

    

Computed the spec of the chunk after it has been encoded by the codec. This is
important for codecs that change the shape, data type or fill value of a
chunk. The spec will then be used for subsequent codecs in the pipeline.

Parameters:

    

**chunk_spec** ArraySpec

    
Returns:

    

ArraySpec

    

to_dict() -> [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"), zarr.core.common.JSON]#

    

Recursively serialize this model to a dictionary. This method inspects the
fields of self and calls x.to_dict() for any fields that are instances of
Metadata. Sequences of Metadata are similarly recursed into, and the output of
that recursion is collected in a list.

validate(

    _*_ ,
    _shape : zarr.core.common.ChunkCoords_,
    _dtype : zarr.core.dtype.wrapper.ZDType[zarr.core.dtype.wrapper.TBaseDType, zarr.core.dtype.wrapper.TBaseScalar]_,
    _chunk_grid : zarr.core.chunk_grids.ChunkGrid_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Validates that the codec configuration is compatible with the array metadata.
Raises errors when the codec configuration is not compatible.

Parameters:

    

**shape** ChunkCoords

    

The array shape

**dtype** np.dtype[Any]

    

The array data type

**chunk_grid** ChunkGrid

    

The array chunk grid

is_fixed_size _: [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")_#

    

_class _zarr.abc.codec.BytesBytesCodec#

    

Bases: `BaseCodec`[`zarr.core.buffer.Buffer`, `zarr.core.buffer.Buffer`]

Base class for bytes-to-bytes codecs.

_abstract _compute_encoded_size(

    _input_byte_length : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")_,
    _chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> [int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Given an input byte length, this method returns the output byte length. Raises
a NotImplementedError for codecs with variable-sized outputs (e.g.
compressors).

Parameters:

    

**input_byte_length** int

    
**chunk_spec** ArraySpec

    
Returns:

    

int

    

_async _decode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Decodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecOutput | None, ArraySpec]]
    

Ordered set of encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecInput | None]
    

_async _encode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Encodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecInput | None, ArraySpec]]
    

Ordered set of to-be-encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecOutput | None]
    

evolve_from_array_spec(_array_spec : zarr.core.array_spec.ArraySpec_) -> Self#

    

Fills in codec configuration parameters that can be automatically inferred
from the array metadata.

Parameters:

    

**array_spec** ArraySpec

    
Returns:

    

Self

    

_classmethod _from_dict(_data :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), zarr.core.common.JSON]_) -> Self#

    

Create an instance of the model from a dictionary

resolve_metadata(

    _chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> zarr.core.array_spec.ArraySpec#

    

Computed the spec of the chunk after it has been encoded by the codec. This is
important for codecs that change the shape, data type or fill value of a
chunk. The spec will then be used for subsequent codecs in the pipeline.

Parameters:

    

**chunk_spec** ArraySpec

    
Returns:

    

ArraySpec

    

to_dict() -> [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"), zarr.core.common.JSON]#

    

Recursively serialize this model to a dictionary. This method inspects the
fields of self and calls x.to_dict() for any fields that are instances of
Metadata. Sequences of Metadata are similarly recursed into, and the output of
that recursion is collected in a list.

validate(

    _*_ ,
    _shape : zarr.core.common.ChunkCoords_,
    _dtype : zarr.core.dtype.wrapper.ZDType[zarr.core.dtype.wrapper.TBaseDType, zarr.core.dtype.wrapper.TBaseScalar]_,
    _chunk_grid : zarr.core.chunk_grids.ChunkGrid_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Validates that the codec configuration is compatible with the array metadata.
Raises errors when the codec configuration is not compatible.

Parameters:

    

**shape** ChunkCoords

    

The array shape

**dtype** np.dtype[Any]

    

The array data type

**chunk_grid** ChunkGrid

    

The array chunk grid

is_fixed_size _: [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")_#

    

_class _zarr.abc.codec.CodecPipeline#

    

Base class for implementing CodecPipeline. A CodecPipeline implements the read
and write paths for chunk data. On the read path, it is responsible for
fetching chunks from a store (via ByteGetter), decoding them and assembling an
output array. On the write path, it encodes the chunks and writes them to a
store (via ByteSetter).

_abstract _compute_encoded_size(

    _byte_length : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")_,
    _array_spec : zarr.core.array_spec.ArraySpec_,
) -> [int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Given an input byte length, this method returns the output byte length. Raises
a NotImplementedError for codecs with variable-sized outputs (e.g.
compressors).

Parameters:

    

**byte_length** int

    
**array_spec** ArraySpec

    
Returns:

    

int

    

_abstract _decode(

    _chunk_bytes_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[zarr.core.buffer.NDBuffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Async:

    

Decodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunk_bytes_and_specs** Iterable[tuple[Buffer | None, ArraySpec]]
    

Ordered set of encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[NDBuffer | None]
    

_abstract _encode(

    _chunk_arrays_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[zarr.core.buffer.NDBuffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Async:

    

Encodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunk_arrays_and_specs** Iterable[tuple[NDBuffer | None, ArraySpec]]
    

Ordered set of to-be-encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[Buffer | None]
    

_abstract _evolve_from_array_spec(_array_spec :
zarr.core.array_spec.ArraySpec_) -> Self#

    

Fills in codec configuration parameters that can be automatically inferred
from the array metadata.

Parameters:

    

**array_spec** ArraySpec

    
Returns:

    

Self

    

_classmethod _from_array_metadata_and_store(

    _array_metadata : zarr.core.metadata.ArrayMetadata_,
    _store : zarr.abc.store.Store_,
) -> Self#

    

Abstractmethod:

    

Creates a codec pipeline from array metadata and a store path.

Raises NotImplementedError by default, indicating the CodecPipeline must be
created with from_codecs instead.

Parameters:

    

**array_metadata** ArrayMetadata

    
**store** Store

    
Returns:

    

Self

    

_classmethod _from_codecs(_codecs :
[collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable
"\(in Python v3.13\)")[Codec]_) -> Self#

    

Abstractmethod:

    

Creates a codec pipeline from an iterable of codecs.

Parameters:

    

**codecs** Iterable[Codec]

    
Returns:

    

Self

    

_abstract _read(

    _batch_info : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[zarr.abc.store.ByteGetter, zarr.core.array_spec.ArraySpec, zarr.core.indexing.SelectorTuple, zarr.core.indexing.SelectorTuple, [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)")]]_,
    _out : zarr.core.buffer.NDBuffer_,
    _drop_axes : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), Ellipsis] = ()_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Async:

    

Reads chunk data from the store, decodes it and writes it into an output
array. Partial decoding may be utilized if the codecs and stores support it.

Parameters:

    

**batch_info** Iterable[tuple[ByteGetter, ArraySpec, SelectorTuple,
SelectorTuple]]

    

Ordered set of information about the chunks. The first slice selection
determines which parts of the chunk will be fetched. The second slice
selection determines where in the output array the chunk data will be written.
The ByteGetter is used to fetch the necessary bytes. The chunk spec contains
information about the construction of an array from the bytes.

**out** NDBuffer

    

_abstract _validate(

    _*_ ,
    _shape : zarr.core.common.ChunkCoords_,
    _dtype : zarr.core.dtype.wrapper.ZDType[zarr.core.dtype.wrapper.TBaseDType, zarr.core.dtype.wrapper.TBaseScalar]_,
    _chunk_grid : zarr.core.chunk_grids.ChunkGrid_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Validates that all codec configurations are compatible with the array
metadata. Raises errors when a codec configuration is not compatible.

Parameters:

    

**shape** ChunkCoords

    

The array shape

**dtype** np.dtype[Any]

    

The array data type

**chunk_grid** ChunkGrid

    

The array chunk grid

_abstract _write(

    _batch_info : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[zarr.abc.store.ByteSetter, zarr.core.array_spec.ArraySpec, zarr.core.indexing.SelectorTuple, zarr.core.indexing.SelectorTuple, [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)")]]_,
    _value : zarr.core.buffer.NDBuffer_,
    _drop_axes : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), Ellipsis] = ()_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Async:

    

Encodes chunk data and writes it to the store. Merges with existing chunk data
by reading first, if necessary. Partial encoding may be utilized if the codecs
and stores support it.

Parameters:

    

**batch_info** Iterable[tuple[ByteSetter, ArraySpec, SelectorTuple,
SelectorTuple]]

    

Ordered set of information about the chunks. The first slice selection
determines which parts of the chunk will be encoded. The second slice
selection determines where in the value array the chunk data is located. The
ByteSetter is used to fetch and write the necessary bytes. The chunk spec
contains information about the chunk.

**value** NDBuffer

    

_property _supports_partial_decode _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Abstractmethod:

    

_property _supports_partial_encode _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Abstractmethod:

    

zarr.abc.codec.CodecInput#

    

zarr.abc.codec.CodecOutput#

    

###### zarr.abc.metadata#

###### Classes#

`Metadata` |   
---|---  
  
###### Module Contents#

_class _zarr.abc.metadata.Metadata#

    

_classmethod _from_dict(_data :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), zarr.core.common.JSON]_) -> Self#

    

Create an instance of the model from a dictionary

to_dict() -> [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"), zarr.core.common.JSON]#

    

Recursively serialize this model to a dictionary. This method inspects the
fields of self and calls x.to_dict() for any fields that are instances of
Metadata. Sequences of Metadata are similarly recursed into, and the output of
that recursion is collected in a list.

###### zarr.abc.store#

###### Classes#

`ByteGetter` | Base class for protocol classes.  
---|---  
`ByteSetter` | Base class for protocol classes.  
`Store` | Abstract base class for Zarr stores.  
  
###### Functions#

`set_or_delete`(→ None) | Set or delete a value in a byte setter  
---|---  
  
###### Module Contents#

_class _zarr.abc.store.ByteGetter#

    

Bases: `Protocol`

Base class for protocol classes.

Protocol classes are defined as:

    
    
    class Proto(Protocol):
        def meth(self) -> int:
            ...
    

Such classes are primarily used with static type checkers that recognize
structural subtyping (static duck-typing).

For example:

    
    
    class C:
        def meth(self) -> int:
            return 0
    
    def func(x: Proto) -> int:
        return x.meth()
    
    func(C())  # Passes static type check
    

See PEP 544 for details. Protocol classes decorated with
@typing.runtime_checkable act as simple-minded runtime protocols that check
only the presence of given attributes, ignoring their type signatures.
Protocol classes can be generic, they are defined as:

    
    
    class GenProto[T](Protocol):
        def meth(self) -> T:
            ...
    

_async _get(

    _prototype : zarr.core.buffer.BufferPrototype_,
    _byte_range : ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")#
    

_class _zarr.abc.store.ByteSetter#

    

Bases: `Protocol`

Base class for protocol classes.

Protocol classes are defined as:

    
    
    class Proto(Protocol):
        def meth(self) -> int:
            ...
    

Such classes are primarily used with static type checkers that recognize
structural subtyping (static duck-typing).

For example:

    
    
    class C:
        def meth(self) -> int:
            return 0
    
    def func(x: Proto) -> int:
        return x.meth()
    
    func(C())  # Passes static type check
    

See PEP 544 for details. Protocol classes decorated with
@typing.runtime_checkable act as simple-minded runtime protocols that check
only the presence of given attributes, ignoring their type signatures.
Protocol classes can be generic, they are defined as:

    
    
    class GenProto[T](Protocol):
        def meth(self) -> T:
            ...
    

_async _delete() ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_async _get(

    _prototype : zarr.core.buffer.BufferPrototype_,
    _byte_range : ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")#
    

_async _set(

    _value : zarr.core.buffer.Buffer_,
    _byte_range : ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_async _set_if_not_exists(_default : zarr.core.buffer.Buffer_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_class _zarr.abc.store.Store(_*_ , _read_only :
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)") = False_)#

    

Bases: [`abc.ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "\(in
Python v3.13\)")

Abstract base class for Zarr stores.

_async _clear() ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Clear the store.

Remove all keys and values from the store.

close() -> [None](https://docs.python.org/3/library/constants.html#None "\(in
Python v3.13\)")#

    

Close the store.

_abstract _delete(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Async:

    

Remove a key from the store

Parameters:

    

**key** str

    

_async _delete_dir(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Remove all keys and prefixes in the store that begin with a given prefix.

_abstract _exists(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")#

    

Async:

    

Check if a key exists in the store.

Parameters:

    

**key** str

    
Returns:

    

bool

    

_abstract _get(

    _key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _prototype : zarr.core.buffer.BufferPrototype_,
    _byte_range : ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")#
    

Async:

    

Retrieve the value associated with a given key.

Parameters:

    

**key** str

    
**prototype** BufferPrototype

    

The prototype of the output buffer. Stores may support a default buffer
prototype.

**byte_range** ByteRequest, optional

    

ByteRequest may be one of the following. If not provided, all data associated
with the key is retrieved. \- RangeByteRequest(int, int): Request a specific
range of bytes in the form (start, end). The end is exclusive. If the given
range is zero-length or starts after the end of the object, an error will be
returned. Additionally, if the range ends after the end of the object, the
entire remainder of the object will be returned. Otherwise, the exact
requested range will be returned. \- OffsetByteRequest(int): Request all bytes
starting from a given byte offset. This is equivalent to bytes={int}- as an
HTTP header. \- SuffixByteRequest(int): Request the last int bytes. Note that
here, int is the size of the request, not the byte offset. This is equivalent
to bytes=-{int} as an HTTP header.

Returns:

    

Buffer

    

_abstract _get_partial_values(

    _prototype : zarr.core.buffer.BufferPrototype_,
    _key_ranges : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]]_,
) -> [list](https://docs.python.org/3/library/stdtypes.html#list "\(in Python v3.13\)")[zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Async:

    

Retrieve possibly partial values from given key_ranges.

Parameters:

    

**prototype** BufferPrototype

    

The prototype of the output buffer. Stores may support a default buffer
prototype.

**key_ranges** Iterable[tuple[str, tuple[int | None, int | None]]]
    

Ordered set of key, range pairs, a key may occur multiple times with different
ranges

Returns:

    

list of values, in the order of the key_ranges, may contain null/none for
missing keys

    

_async _getsize(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")#

    

Return the size, in bytes, of a value in a Store.

Parameters:

    

**key** str

    
Returns:

    

**nbytes** int

    

The size of the value (in bytes).

Raises:

    

FileNotFoundError

    

When the given key does not exist in the store.

_async _getsize_prefix(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")#

    

Return the size, in bytes, of all values under a prefix.

Parameters:

    

**prefix** str

    

The prefix of the directory to measure.

Returns:

    

**nbytes** int

    

The sum of the sizes of the values in the directory (in bytes).

See also

`zarr.Array.nbytes_stored`

    
`Store.getsize`

    

Notes

`getsize_prefix` is just provided as a potentially faster alternative to
listing all the keys under a prefix calling `Store.getsize()` on each.

In general, `prefix` should be the path of an Array or Group in the Store.
Implementations may differ on the behavior when some other `prefix` is
provided.

_async _is_empty(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")#

    

Check if the directory is empty.

Parameters:

    

**prefix** str

    

Prefix of keys to check.

Returns:

    

bool

    

True if the store is empty, False otherwise.

_abstract _list() ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys in the store.

Returns:

    

AsyncIterator[str]

    

_abstract _list_dir(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys and prefixes with a given prefix and which do not contain
the character “/” after the given prefix.

Parameters:

    

**prefix** str

    
Returns:

    

AsyncIterator[str]

    

_abstract _list_prefix(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys in the store that begin with a given prefix. Keys are
returned relative to the root of the store.

Parameters:

    

**prefix** str

    
Returns:

    

AsyncIterator[str]

    

_classmethod _open(_* args: Any_, _** kwargs: Any_) -> Self#

    

Async:

    

Create and open the store.

Parameters:

    

***args** Any

    

Positional arguments to pass to the store constructor.

****kwargs** Any

    

Keyword arguments to pass to the store constructor.

Returns:

    

Store

    

The opened store instance.

_abstract _set(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_, _value : zarr.core.buffer.Buffer_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Async:

    

Store a (key, value) pair.

Parameters:

    

**key** str

    
**value** Buffer

    

_async _set_if_not_exists(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_, _value : zarr.core.buffer.Buffer_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store a key to `value` if the key is not already present.

Parameters:

    

**key** str

    
**value** Buffer

    

_abstract _set_partial_values(

    _key_start_values : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), zarr.core.common.BytesLike]]_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Async:

    

Store values at a given key, starting at byte range_start.

Parameters:

    

**key_start_values** list[tuple[str, int, BytesLike]]

    

set of key, range_start, values triples, a key may occur multiple times with
different range_starts, range_starts (considering the length of the respective
values) must not specify overlapping ranges for the same key

_abstract _with_read_only(_read_only :
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)") = False_) -> Store#

    

Return a new store with a new read_only setting.

The new store points to the same location with the specified new read_only
state. The returned Store is not automatically opened, and this store is not
automatically closed.

Parameters:

    

**read_only**

    

If True, the store will be created in read-only mode. Defaults to False.

Returns:

    

A new store of the same type with the new read only attribute.

    

_property _read_only _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Is the store read-only?

_property _supports_consolidated_metadata _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support consolidated metadata?.

If it doesn’t an error will be raised on requests to consolidate the metadata.
Returning False can be useful for stores which implement their own
consolidation mechanism outside of the zarr-python implementation.

_property _supports_deletes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Abstractmethod:

    

Does the store support deletes?

_property _supports_listing _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Abstractmethod:

    

Does the store support listing?

_property _supports_partial_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Abstractmethod:

    

Does the store support partial writes?

_property _supports_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Abstractmethod:

    

Does the store support writes?

_async _zarr.abc.store.set_or_delete(

    _byte_setter : ByteSetter_,
    _value : zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Set or delete a value in a byte setter

Parameters:

    

**byte_setter** ByteSetter

    
**value** Buffer | None
    

Notes

If value is None, the key will be deleted.

#### zarr.api#

##### Submodules#

###### zarr.api.asynchronous#

###### Functions#

`array`(...) | Create an array filled with data.  
---|---  
`consolidate_metadata`(→ zarr.core.group.AsyncGroup) | Consolidate the metadata of all nodes in a hierarchy.  
`copy`(→ tuple[int, int, int]) |   
`copy_all`(→ tuple[int, int, int]) |   
`copy_store`(→ tuple[int, int, int]) |   
`create`(...) | Create an array.  
`create_array`(...) | Create an array.  
`create_hierarchy`(...) | Create a complete zarr hierarchy from a collection of metadata objects.  
`empty`(...) | Create an empty array with the specified shape. The contents will be filled with the  
`empty_like`(...) | Create an empty array like a. The contents will be filled with the  
`from_array`(...) | Create an array from an existing array or array-like.  
`full`(...) | Create an array, with fill_value being used as the default value for  
`full_like`(...) | Create a filled array like a.  
`group`(→ zarr.core.group.AsyncGroup) | Create a group.  
`load`(...) | Load data from an array or group into memory.  
`ones`(...) | Create an array, with one being used as the default value for  
`ones_like`(...) | Create an array of ones like a.  
`open`(...) | Convenience function to open a group or array using file-mode-like semantics.  
`open_array`(...) | Open an array using file-mode-like semantics.  
`open_consolidated`(→ zarr.core.group.AsyncGroup) | Alias for `open_group()` with `use_consolidated=True`.  
`open_group`(→ zarr.core.group.AsyncGroup) | Open a group using file-mode-like semantics.  
`open_like`(...) | Open a persistent array like a.  
`save`(→ None) | Convenience function to save an array or group of arrays to the local file system.  
`save_array`(→ None) | Convenience function to save a NumPy array to the local file system, following a  
`save_group`(→ None) | Convenience function to save several NumPy arrays to the local file system, following a  
`tree`(→ Any) | Provide a rich display of the hierarchy.  
`zeros`(...) | Create an array, with zero being used as the default value for  
`zeros_like`(...) | Create an array of zeros like a.  
  
###### Module Contents#

_async _zarr.api.asynchronous.array(

    _data : numpy.typing.ArrayLike | zarr.core.array.Array_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]#
    

Create an array filled with data.

Parameters:

    

**data** array_like

    

The data to fill the array with.

****kwargs**

    

Passed through to `create()`.

Returns:

    

**array** array

    

The new array.

_async _zarr.api.asynchronous.consolidate_metadata(

    _store : zarr.storage.StoreLike_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.group.AsyncGroup#

    

Consolidate the metadata of all nodes in a hierarchy.

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

Parameters:

    

**store** StoreLike

    

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

**path** str, optional

    

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

By default, the root node is used so all the metadata in the store is
consolidated.

**zarr_format**{2, 3, None}, optional

    

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

Returns:

    

group: AsyncGroup

    

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

_async _zarr.api.asynchronous.copy(_* args: Any_, _** kwargs: Any_) ->
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)"),
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")]#

    

_async _zarr.api.asynchronous.copy_all(_* args: Any_, _** kwargs: Any_) ->
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)"),
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")]#

    

_async _zarr.api.asynchronous.copy_store(_* args: Any_, _** kwargs: Any_) ->
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)"),
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")]#

    

_async _zarr.api.asynchronous.create(

    _shape : zarr.core.common.ChunkCoords | [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")_,
    _*_ ,
    _chunks : zarr.core.common.ChunkCoords | [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dtype : zarr.core.dtype.ZDTypeLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _compressor : zarr.core.array.CompressorLike = 'auto'_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = DEFAULT_FILL_VALUE_,
    _order : zarr.core.common.MemoryOrder | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _store : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _synchronizer : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _path : PathLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _filters : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [numcodecs.abc.Codec](https://numcodecs.readthedocs.io/en/stable/abc.html#numcodecs.abc.Codec "\(in numcodecs v0.16.1\)")] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _cache_metadata : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _cache_attrs : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _read_only : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _object_codec : zarr.abc.codec.Codec | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_separator : Literal['.', '/'] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _write_empty_chunks : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _meta_array : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_shape : zarr.core.common.ChunkCoords | [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_key_encoding : zarr.core.chunk_key_encodings.ChunkKeyEncoding | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[Literal['default'], Literal['.', '/']] | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[Literal['v2'], Literal['.', '/']] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _codecs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[zarr.abc.codec.Codec | [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON]] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_names : zarr.core.common.DimensionNames = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _config : zarr.core.array_spec.ArrayConfigLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]#
    

Create an array.

Parameters:

    

**shape** int or tuple of ints

    

Array shape.

**chunks** int or tuple of ints, optional

    

The shape of the array’s chunks. Zarr format 2 only. Zarr format 3 arrays
should use chunk_shape instead. If not specified, default values are guessed
based on the shape and dtype.

**dtype** str or dtype, optional

    

NumPy dtype.

**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. The elements of this
collection 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:

  * For numeric arrays, the default is `BytesCodec` and `ZstdCodec`.

  * For Unicode strings, the default is `VLenUTF8Codec` and `ZstdCodec`.

  * For bytes or objects, the default is `VLenBytesCodec` and `ZstdCodec`.

These defaults can be changed by modifying the value of
`array.v3_default_filters`, `array.v3_default_serializer` and
`array.v3_default_compressors` in `zarr.core.config`.

**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, a default compressor will
be used:

  * For numeric arrays, the default is `ZstdCodec`.

  * For Unicode strings, the default is `VLenUTF8Codec`.

  * For bytes or objects, the default is `VLenBytesCodec`.

These defaults can be changed by modifying the value of
`array.v2_default_compressor` in `zarr.core.config`.

**fill_value** object

    

Default value to use for uninitialized portions of 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** Store or str

    

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** MutableMapping, optional

    

Separate storage for chunks. If not provided, store will be used for storage
of both chunks and metadata.

**filters** sequence of Codecs, optional

    

Sequence of filters to use to encode chunk data prior to compression. Zarr
format 2 only. If no `filters` are provided, a default set of filters will be
used. These defaults can be changed by modifying the value of
`array.v2_default_filters` in `zarr.core.config`.

**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. Default is “.”.

**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 saving. Default is 3.

**meta_array** array-like, optional

    

An array instance to use for determining arrays to create and return to users.
Use numpy.empty(()) by default.

**storage_options** dict

    

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

**config** ArrayConfig or ArrayConfigLike, optional

    

Runtime configuration of the array. If provided, will override the default
values from zarr.config.array.

Returns:

    

**z** array

    

The array.

_async _zarr.api.asynchronous.create_array(

    _store : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | zarr.storage.StoreLike_,
    _*_ ,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _shape : zarr.core.common.ShapeLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dtype : zarr.core.dtype.ZDTypeLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _data : [numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "\(in NumPy v2.3\)")[Any, [numpy.dtype](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype "\(in NumPy v2.3\)")[Any]] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunks : zarr.core.common.ChunkCoords | Literal['auto'] = 'auto'_,
    _shards : ShardsLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _filters : FiltersLike = 'auto'_,
    _compressors : CompressorsLike = 'auto'_,
    _serializer : SerializerLike = 'auto'_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = DEFAULT_FILL_VALUE_,
    _order : zarr.core.common.MemoryOrder | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 3_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_key_encoding : zarr.core.chunk_key_encodings.ChunkKeyEncodingLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_names : zarr.core.common.DimensionNames = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _config : zarr.core.array_spec.ArrayConfigLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _write_data : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = True_,
) -> AsyncArray[zarr.core.metadata.ArrayV2Metadata] | AsyncArray[zarr.core.metadata.ArrayV3Metadata]#
    

Create an array.

Parameters:

    

**store** str or Store

    

Store or path to directory in file system or name of zip file.

**name** str or None, optional

    

The name of the array within the store. If `name` is `None`, the array will be
located at the root of the store.

**shape** ChunkCoords, optional

    

Shape of the array. Can be `None` if `data` is provided.

**dtype** ZDTypeLike | None
    

Data type of the array. Can 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 identical to `data.shape` and
`data.dtype`, or `None`.

**chunks** ChunkCoords, optional

    

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

**shards** ChunkCoords, optional

    

Shard shape of the array. The default value of `None` results in no sharding
at all.

**filters** Iterable[Codec], 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 `ArrayArrayCodec`, or dict
representations of `ArrayArrayCodec`. If no `filters` are provided, a default
set of filters will be used. These defaults can be changed by modifying the
value of `array.v3_default_filters` in `zarr.core.config`. Use `None` to omit
default filters.

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. If no `filters` are provided, a default set of filters will be used.
These defaults can be changed by modifying the value of
`array.v2_default_filters` in `zarr.core.config`. Use `None` to omit default
filters.

**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.core.config`. Use `None` to omit
default compressors.

For Zarr format 2, a “compressor” can be any numcodecs codec. Only a single
compressor may be provided for Zarr format 2. If no `compressor` is provided,
a default compressor will be used. in `zarr.core.config`. Use `None` to omit
the default compressor.

**serializer** dict[str, JSON] | ArrayBytesCodec, optional
    

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

**fill_value** Any, optional

    

Fill value for the array.

**order**{“C”, “F”}, optional

    

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

**zarr_format**{2, 3}, optional

    

The zarr format to use when saving.

**attributes** dict, optional

    

Attributes for the array.

**chunk_key_encoding** ChunkKeyEncodingLike, optional

    

A specification of how the chunk keys are represented in storage. For Zarr
format 3, the default is `{"name": "default", "separator": "/"}}`. For Zarr
format 2, the default is `{"name": "v2", "separator": "."}}`.

**dimension_names** Iterable[str], optional

    

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

**storage_options** dict, optional

    

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

**overwrite** bool, default False

    

Whether to overwrite an array with the same name in the store, if one exists.

**config** ArrayConfigLike, optional

    

Runtime configuration for the array.

**write_data** bool

    

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

Returns:

    

AsyncArray

    

The array.

Examples

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

_async _zarr.api.asynchronous.create_hierarchy(

    _*_ ,
    _store : zarr.abc.store.Store_,
    _nodes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), GroupMetadata | zarr.core.metadata.ArrayV2Metadata | zarr.core.metadata.ArrayV3Metadata]_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
) -> [collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), AsyncGroup | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]]]#
    

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

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

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

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

Parameters:

    

**store** Store

    

The storage backend to use.

**nodes** dict[str, GroupMetadata | ArrayV3Metadata | ArrayV2Metadata]
    

A dictionary defining the hierarchy. The keys are the paths of the nodes in
the hierarchy, relative to the root of the `Store`. The root of the store can
be specified with the empty string `''`. The values are instances of
`GroupMetadata` or `ArrayMetadata`. Note that all values must have the same
`zarr_format` – it is an error to mix zarr versions in the same hierarchy.

Leading “/” characters from keys will be removed.

**overwrite** bool

    

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

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

Yields:

    

tuple[str, AsyncGroup | AsyncArray]
    

This function yields (path, node) pairs, in the order the nodes were created.

Examples

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

_async _zarr.api.asynchronous.empty(

    _shape : zarr.core.common.ChunkCoords_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]#
    

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

_async _zarr.api.asynchronous.empty_like(

    _a : ArrayLike_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]#
    

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

Parameters:

    

**a** array-like

    

The array to create an empty array like.

****kwargs**

    

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

_async _zarr.api.asynchronous.from_array(

    _store : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | zarr.storage.StoreLike_,
    _*_ ,
    _data : Array | numpy.typing.ArrayLike_,
    _write_data : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = True_,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunks : Literal['auto', 'keep'] | zarr.core.common.ChunkCoords = 'keep'_,
    _shards : ShardsLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") | Literal['keep'] = 'keep'_,
    _filters : FiltersLike | Literal['keep'] = 'keep'_,
    _compressors : CompressorsLike | Literal['keep'] = 'keep'_,
    _serializer : SerializerLike | Literal['keep'] = 'keep'_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = DEFAULT_FILL_VALUE_,
    _order : zarr.core.common.MemoryOrder | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_key_encoding : zarr.core.chunk_key_encodings.ChunkKeyEncodingLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_names : zarr.core.common.DimensionNames = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _config : zarr.core.array_spec.ArrayConfig | zarr.core.array_spec.ArrayConfigLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> AsyncArray[zarr.core.metadata.ArrayV2Metadata] | AsyncArray[zarr.core.metadata.ArrayV3Metadata]#
    

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

Parameters:

    

**store** str or Store

    

Store or path to directory in file system or name of zip file for the new
array.

**data** Array | array-like
    

The array to copy.

**write_data** bool, default True

    

Whether to copy the data from the input array to the new array. If
`write_data` is `False`, the new array will be created with the same metadata
as the input array, but without any data.

**name** str or None, optional

    

The name of the array within the store. If `name` is `None`, the array will be
located at the root of the store.

**chunks** ChunkCoords or “auto” or “keep”, optional

    

Chunk shape of the array. Following values are supported:

  * “auto”: Automatically determine the chunk shape based on the array’s shape and dtype.

  * “keep”: Retain the chunk shape of the data array if it is a zarr Array.

  * ChunkCoords: A tuple of integers representing the chunk shape.

If not specified, defaults to “keep” if data is a zarr Array, otherwise
“auto”.

**shards** ChunkCoords, optional

    

Shard shape of the array. Following values are supported:

  * “auto”: Automatically determine the shard shape based on the array’s shape and chunk shape.

  * “keep”: Retain the shard shape of the data array if it is a zarr Array.

  * ChunkCoords: A tuple of integers representing the shard shape.

  * None: No sharding.

If not specified, defaults to “keep” if data is a zarr Array, otherwise None.

**filters** Iterable[Codec] or “auto” or “keep”, optional

    

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

For Zarr format 3, a “filter” is a codec that takes an array and returns an
array, and these values must be instances of `ArrayArrayCodec`, or dict
representations of `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.

Following values are supported:

  * Iterable[Codec]: List of filters to apply to the array.

  * “auto”: Automatically determine the filters based on the array’s dtype.

  * “keep”: Retain the filters of the data array if it is a zarr Array.

If no `filters` are provided, defaults to “keep” if data is a zarr Array,
otherwise “auto”.

**compressors** Iterable[Codec] or “auto” or “keep”, optional

    

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

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

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

Following values are supported:

  * Iterable[Codec]: List of compressors to apply to the array.

  * “auto”: Automatically determine the compressors based on the array’s dtype.

  * “keep”: Retain the compressors of the input array if it is a zarr Array.

If no `compressors` are provided, defaults to “keep” if data is a zarr Array,
otherwise “auto”.

**serializer** dict[str, JSON] | ArrayBytesCodec or “auto” or “keep”, optional
    

Array-to-bytes codec to use for encoding the array data. Zarr format 3 only.
Zarr format 2 arrays use implicit array-to-bytes conversion.

Following values are supported:

  * dict[str, JSON]: A dict representation of an `ArrayBytesCodec`.

  * ArrayBytesCodec: An instance of `ArrayBytesCodec`.

  * “auto”: a default serializer will be used. These defaults can be changed by modifying the value of `array.v3_default_serializer` in `zarr.core.config`.

  * “keep”: Retain the serializer of the input array if it is a zarr Array.

**fill_value** Any, optional

    

Fill value for the array. If not specified, defaults to the fill value of the
data array.

**order**{“C”, “F”}, optional

    

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

**zarr_format**{2, 3}, optional

    

The zarr format to use when saving. If not specified, defaults to the zarr
format of the data array.

**attributes** dict, optional

    

Attributes for the array. If not specified, defaults to the attributes of the
data array.

**chunk_key_encoding** ChunkKeyEncoding, optional

    

A specification of how the chunk keys are represented in storage. For Zarr
format 3, the default is `{"name": "default", "separator": "/"}}`. For Zarr
format 2, the default is `{"name": "v2", "separator": "."}}`. If not specified
and the data array has the same zarr format as the target array, the chunk key
encoding of the data array is used.

**dimension_names** Iterable[str | None], optional
    

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

**storage_options** dict, optional

    

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

**overwrite** bool, default False

    

Whether to overwrite an array with the same name in the store, if one exists.

**config** ArrayConfig or ArrayConfigLike, optional

    

Runtime configuration for the array.

Returns:

    

AsyncArray

    

The array.

Examples

Create an array from an existing Array:

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

Create an array from an existing NumPy array:

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

Create an array from any array-like object:

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

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

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

_async _zarr.api.asynchronous.full(

    _shape : zarr.core.common.ChunkCoords_,
    _fill_value : Any_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]#
    

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

Parameters:

    

**shape** int or tuple of int

    

Shape of the empty array.

**fill_value** scalar

    

Fill value.

****kwargs**

    

Keyword arguments passed to `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

_async _zarr.api.asynchronous.full_like(

    _a : ArrayLike_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]#
    

Create a filled array like a.

Parameters:

    

**a** array-like

    

The array to create an empty array like.

****kwargs**

    

Keyword arguments passed to `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

_async _zarr.api.asynchronous.group(

    _*_ ,
    _store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _chunk_store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _cache_attrs : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _synchronizer : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _meta_array : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.group.AsyncGroup#

    

Create a group.

Parameters:

    

**store** Store or str, optional

    

Store or path to directory in file system.

**overwrite** bool, optional

    

If True, delete any pre-existing data in store at path before creating the
group.

**chunk_store** Store, optional

    

Separate storage for chunks. If not provided, store will be used for storage
of both chunks and metadata.

**cache_attrs** bool, optional

    

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

**synchronizer** object, optional

    

Array synchronizer.

**path** str, optional

    

Group path within store.

**meta_array** array-like, optional

    

An array instance to use for determining arrays to create and return to users.
Use numpy.empty(()) by default.

**zarr_format**{2, 3, None}, optional

    

The zarr format to use when saving.

**storage_options** dict

    

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

Returns:

    

**g** group

    

The new group.

_async _zarr.api.asynchronous.load(

    _*_ ,
    _store : zarr.storage.StoreLike_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.NDArrayLikeOrScalar | [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.buffer.NDArrayLikeOrScalar]#
    

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.

See also

`save`, `savez`

    

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.

_async _zarr.api.asynchronous.ones(

    _shape : zarr.core.common.ChunkCoords_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]#
    

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

Parameters:

    

**shape** int or tuple of int

    

Shape of the empty array.

****kwargs**

    

Keyword arguments passed to `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

_async _zarr.api.asynchronous.ones_like(

    _a : ArrayLike_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]#
    

Create an array of ones like a.

Parameters:

    

**a** array-like

    

The array to create an empty array like.

****kwargs**

    

Keyword arguments passed to `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

_async _zarr.api.asynchronous.open(

    _*_ ,
    _store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _mode : zarr.core.common.AccessModeLiteral | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata] | zarr.core.group.AsyncGroup#
    

Convenience function to 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). If the store is
read-only, the default is ‘r’; otherwise, it is ‘a’.

**zarr_format**{2, 3, None}, optional

    

The zarr format to use when saving.

**path** str or None, optional

    

The path within the store to open.

**storage_options** dict

    

If the store is backed by an fsspec-based implementation, then this dict will
be passed to the Store constructor for that implementation. Ignored otherwise.

****kwargs**

    

Additional parameters are passed through to `zarr.creation.open_array()` or
`zarr.hierarchy.open_group()`.

Returns:

    

**z** array or group

    

Return type depends on what exists in the given store.

_async _zarr.api.asynchronous.open_array(

    _*_ ,
    _store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : PathLike = ''_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]#
    

Open an array using file-mode-like semantics.

Parameters:

    

**store** Store or str

    

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 `create()`.

Returns:

    

AsyncArray

    

The opened array.

_async _zarr.api.asynchronous.open_consolidated(

    _* args: Any_,
    _use_consolidated : Literal[True] = True_,
    _** kwargs: Any_,
) -> zarr.core.group.AsyncGroup#

    

Alias for `open_group()` with `use_consolidated=True`.

_async _zarr.api.asynchronous.open_group(

    _store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _*_ ,
    _mode : zarr.core.common.AccessModeLiteral = 'a'_,
    _cache_attrs : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _synchronizer : Any = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _meta_array : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _use_consolidated : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.group.AsyncGroup#

    

Open a group using file-mode-like semantics.

Parameters:

    

**store** Store, str, or mapping, optional

    

Store or path to directory in file system or name of zip file.

Strings are interpreted as paths on the local file system and used as the
`root` argument to `zarr.storage.LocalStore`.

Dictionaries are used as the `store_dict` argument in
`zarr.storage.MemoryStore``.

By default (`store=None`) a new `zarr.storage.MemoryStore` is created.

**mode**{‘r’, ‘r+’, ‘a’, ‘w’, ‘w-‘}, optional

    

Persistence mode: ‘r’ means read only (must exist); ‘r+’ means read/write
(must exist); ‘a’ means read/write (create if doesn’t exist); ‘w’ means create
(overwrite if exists); ‘w-’ means create (fail if exists).

**cache_attrs** bool, optional

    

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

**synchronizer** object, optional

    

Array synchronizer.

**path** str, optional

    

Group path within store.

**chunk_store** Store or str, optional

    

Store or path to directory in file system or name of zip file.

**storage_options** dict

    

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

**meta_array** array-like, optional

    

An array instance to use for determining arrays to create and return to users.
Use numpy.empty(()) by default.

**attributes** dict

    

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

**use_consolidated** bool or str, default None

    

Whether to use consolidated metadata.

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

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

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

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

Returns:

    

**g** group

    

The new group.

_async _zarr.api.asynchronous.open_like(

    _a : ArrayLike_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata]#
    

Open a persistent array like a.

Parameters:

    

**a** Array

    

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

**path** str

    

The path to the new array.

****kwargs**

    

Any keyword arguments to pass to the array constructor.

Returns:

    

AsyncArray

    

The opened array.

_async _zarr.api.asynchronous.save(

    _store : zarr.storage.StoreLike_,
    _* args: zarr.core.buffer.NDArrayLike_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _** kwargs: Any_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Convenience function to 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.

_async _zarr.api.asynchronous.save_array(

    _store : zarr.storage.StoreLike_,
    _arr : zarr.core.buffer.NDArrayLike_,
    _*_ ,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _** kwargs: Any_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Convenience function to save a NumPy array to the local file system, following
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 (default is 3 if not specified).

**path** str or None, optional

    

The path within the store where the array will be saved.

**storage_options** dict

    

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

****kwargs**

    

Passed through to `create()`, e.g., compressor.

_async _zarr.api.asynchronous.save_group(

    _store : zarr.storage.StoreLike_,
    _* args: zarr.core.buffer.NDArrayLike_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _** kwargs: zarr.core.buffer.NDArrayLike_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

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

Parameters:

    

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

_async _zarr.api.asynchronous.tree(

    _grp : zarr.core.group.AsyncGroup_,
    _expand : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _level : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> Any#

    

Provide a rich display of the hierarchy.

Deprecated since version 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.

_async _zarr.api.asynchronous.zeros(

    _shape : zarr.core.common.ChunkCoords_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]#
    

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

Parameters:

    

**shape** int or tuple of int

    

Shape of the empty array.

****kwargs**

    

Keyword arguments passed to `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

_async _zarr.api.asynchronous.zeros_like(

    _a : ArrayLike_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]#
    

Create an array of zeros like a.

Parameters:

    

**a** array-like

    

The array to create an empty array like.

****kwargs**

    

Keyword arguments passed to `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

###### zarr.api.synchronous#

###### Functions#

`array`(→ zarr.core.array.Array) | Create an array filled with data.  
---|---  
`consolidate_metadata`(→ zarr.core.group.Group) | Consolidate the metadata of all nodes in a hierarchy.  
`copy`(→ tuple[int, int, int]) |   
`copy_all`(→ tuple[int, int, int]) |   
`copy_store`(→ tuple[int, int, int]) |   
`create`(→ zarr.core.array.Array) | Create an array.  
`create_array`(→ zarr.core.array.Array) | Create an array.  
`create_hierarchy`(→ collections.abc.Iterator[tuple[str, ...) | Create a complete zarr hierarchy from a collection of metadata objects.  
`empty`(→ zarr.core.array.Array) | Create an empty array with the specified shape. The contents will be filled with the  
`empty_like`(→ zarr.core.array.Array) | Create an empty array like another array. The contents will be filled with the  
`from_array`(→ zarr.core.array.Array) | Create an array from an existing array or array-like.  
`full`(→ zarr.core.array.Array) | Create an array with a default fill value.  
`full_like`(→ zarr.core.array.Array) | Create a filled array like another array.  
`group`(→ zarr.core.group.Group) | Create a group.  
`load`(...) | Load data from an array or group into memory.  
`ones`(→ zarr.core.array.Array) | Create an array with a fill value of one.  
`ones_like`(→ zarr.core.array.Array) | Create an array of ones like another array.  
`open`(→ zarr.core.array.Array | zarr.core.group.Group) | Open a group or array using file-mode-like semantics.  
`open_array`(→ zarr.core.array.Array) | Open an array using file-mode-like semantics.  
`open_consolidated`(→ zarr.core.group.Group) | Alias for `open_group()` with `use_consolidated=True`.  
`open_group`(→ zarr.core.group.Group) | Open a group using file-mode-like semantics.  
`open_like`(→ zarr.core.array.Array) | Open a persistent array like another array.  
`save`(→ None) | Save an array or group of arrays to the local file system.  
`save_array`(→ None) | Save a NumPy array to the local file system.  
`save_group`(→ None) | Save several NumPy arrays to the local file system.  
`tree`(→ Any) | Provide a rich display of the hierarchy.  
`zeros`(→ zarr.core.array.Array) | Create an array with a fill value of zero.  
`zeros_like`(→ zarr.core.array.Array) | Create an array of zeros like another array.  
  
###### Module Contents#

zarr.api.synchronous.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 `create()`.

Returns:

    

**array** Array

    

The new array.

zarr.api.synchronous.consolidate_metadata(

    _store : zarr.storage.StoreLike_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 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. For Stores that do not use
consolidated metadata, this operation raises a TypeError.

Parameters:

    

**store** StoreLike

    

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

**path** str, optional

    

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

By default, the root node is used so all the metadata in the store is
consolidated.

**zarr_format**{2, 3, None}, optional

    

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

Returns:

    

group: Group

    

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

zarr.api.synchronous.copy(_* args: Any_, _** kwargs: Any_) ->
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)"),
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")]#

    

zarr.api.synchronous.copy_all(_* args: Any_, _** kwargs: Any_) ->
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)"),
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")]#

    

zarr.api.synchronous.copy_store(_* args: Any_, _** kwargs: Any_) ->
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)"),
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")]#

    

zarr.api.synchronous.create(

    _shape : zarr.core.common.ChunkCoords | [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")_,
    _*_ ,
    _chunks : zarr.core.common.ChunkCoords | [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dtype : zarr.core.dtype.ZDTypeLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _compressor : zarr.core.array.CompressorLike = 'auto'_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = DEFAULT_FILL_VALUE_,
    _order : zarr.core.common.MemoryOrder | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _store : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _synchronizer : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _path : zarr.api.asynchronous.PathLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _filters : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [numcodecs.abc.Codec](https://numcodecs.readthedocs.io/en/stable/abc.html#numcodecs.abc.Codec "\(in numcodecs v0.16.1\)")] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _cache_metadata : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _cache_attrs : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _read_only : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _object_codec : zarr.abc.codec.Codec | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_separator : Literal['.', '/'] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _write_empty_chunks : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _meta_array : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_shape : zarr.core.common.ChunkCoords | [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_key_encoding : zarr.core.chunk_key_encodings.ChunkKeyEncoding | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[Literal['default'], Literal['.', '/']] | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[Literal['v2'], Literal['.', '/']] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _codecs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[zarr.abc.codec.Codec | [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON]] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_names : zarr.core.common.DimensionNames = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _config : zarr.core.array_spec.ArrayConfigLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 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.

**fill_value** object

    

Default value to use for uninitialized portions of 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** Store or str

    

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** MutableMapping, optional

    

Separate storage for chunks. If not provided, store will be used for storage
of both chunks and metadata.

**filters** sequence of Codecs, optional

    

Sequence of filters to use to encode chunk data prior to compression.

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

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

**meta_array** array-like, optional

    

An array instance to use for determining arrays to create and return to users.
Use numpy.empty(()) by default.

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

zarr.api.synchronous.create_array(

    _store : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | zarr.storage.StoreLike_,
    _*_ ,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _shape : zarr.core.common.ShapeLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dtype : zarr.core.dtype.ZDTypeLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _data : [numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "\(in NumPy v2.3\)")[Any, [numpy.dtype](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype "\(in NumPy v2.3\)")[Any]] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunks : zarr.core.common.ChunkCoords | Literal['auto'] = 'auto'_,
    _shards : zarr.core.array.ShardsLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _filters : zarr.core.array.FiltersLike = 'auto'_,
    _compressors : zarr.core.array.CompressorsLike = 'auto'_,
    _serializer : zarr.core.array.SerializerLike = 'auto'_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = DEFAULT_FILL_VALUE_,
    _order : zarr.core.common.MemoryOrder | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 3_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_key_encoding : zarr.core.chunk_key_encodings.ChunkKeyEncodingLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_names : zarr.core.common.DimensionNames = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _config : zarr.core.array_spec.ArrayConfigLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _write_data : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = True_,
) -> zarr.core.array.Array#

    

Create an array.

This function wraps `zarr.core.array.create_array()`.

Parameters:

    

**store** str or Store

    

Store or path to directory in file system or name of zip file.

**name** str or None, optional

    

The name of the array within the store. If `name` is `None`, the array will be
located at the root of the store.

**shape** ChunkCoords, optional

    

Shape of the array. Can be `None` if `data` is provided.

**dtype** ZDTypeLike, optional

    

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

**data** np.ndarray, optional

    

Array-like data to use for initializing the array. If this parameter is
provided, the `shape` and `dtype` parameters must be identical to `data.shape`
and `data.dtype`, or `None`.

**chunks** ChunkCoords, optional

    

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

**shards** ChunkCoords, optional

    

Shard shape of the array. The default value of `None` results in no sharding
at all.

**filters** Iterable[Codec], 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 `ArrayArrayCodec`, or dict
representations of `ArrayArrayCodec`. If no `filters` are provided, a default
set of filters will be used. These defaults can be changed by modifying the
value of `array.v3_default_filters` in `zarr.core.config`. Use `None` to omit
default filters.

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. If no `filters` are provided, a default set of filters will be used.
These defaults can be changed by modifying the value of
`array.v2_default_filters` in `zarr.core.config`. Use `None` to omit default
filters.

**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.core.config`. Use `None` to omit
default compressors.

For Zarr format 2, a “compressor” can be any numcodecs codec. Only a single
compressor may be provided for Zarr format 2. If no `compressor` is provided,
a default compressor will be used. in `zarr.core.config`. Use `None` to omit
the default compressor.

**serializer** dict[str, JSON] | ArrayBytesCodec, optional
    

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

**fill_value** Any, optional

    

Fill value for the array.

**order**{“C”, “F”}, optional

    

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

**zarr_format**{2, 3}, optional

    

The zarr format to use when saving.

**attributes** dict, optional

    

Attributes for the array.

**chunk_key_encoding** 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.
If True, all existing paths in the store will be deleted.

**config** ArrayConfigLike, optional

    

Runtime configuration for the array.

**write_data** bool

    

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

Returns:

    

Array

    

The array.

Examples

    
    
    >>> import zarr
    >>> store = zarr.storage.MemoryStore()
    >>> arr = await zarr.create_array(
    >>>     store=store,
    >>>     shape=(100,100),
    >>>     chunks=(10,10),
    >>>     dtype='i4',
    >>>     fill_value=0)
    <Array memory://140349042942400 shape=(100, 100) dtype=int32>
    

zarr.api.synchronous.create_hierarchy(

    _*_ ,
    _store : zarr.abc.store.Store_,
    _nodes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.group.GroupMetadata | zarr.core.metadata.ArrayV2Metadata | zarr.core.metadata.ArrayV3Metadata]_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
) -> [collections.abc.Iterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterator "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.group.Group | zarr.core.array.Array]]#
    

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

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

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

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

Parameters:

    

**store** Store

    

The storage backend to use.

**nodes** dict[str, GroupMetadata | ArrayV3Metadata | ArrayV2Metadata]
    

A dictionary defining the hierarchy. The keys are the paths of the nodes in
the hierarchy, relative to the root of the `Store`. The root of the store can
be specified with the empty string `''`. The values are instances of
`GroupMetadata` or `ArrayMetadata`. Note that all values must have the same
`zarr_format` – it is an error to mix zarr versions in the same hierarchy.

Leading “/” characters from keys will be removed.

**overwrite** bool

    

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

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

Yields:

    

tuple[str, Group | Array]
    

This function yields (path, node) pairs, in the order the nodes were created.

Examples

    
    
    >>> from zarr import create_hierarchy
    >>> from zarr.storage import MemoryStore
    >>> from zarr.core.group import GroupMetadata
    
    
    
    >>> store = MemoryStore()
    >>> nodes = {'a': GroupMetadata(attributes={'name': 'leaf'})}
    >>> nodes_created = dict(create_hierarchy(store=store, nodes=nodes))
    >>> print(nodes)
    # {'a': GroupMetadata(attributes={'name': 'leaf'}, zarr_format=3, consolidated_metadata=None, node_type='group')}
    

zarr.api.synchronous.empty(

    _shape : zarr.core.common.ChunkCoords_,
    _** 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 `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.

zarr.api.synchronous.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 `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.

zarr.api.synchronous.from_array(

    _store : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | zarr.storage.StoreLike_,
    _*_ ,
    _data : zarr.core.array.Array | numpy.typing.ArrayLike_,
    _write_data : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = True_,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunks : Literal['auto', 'keep'] | zarr.core.common.ChunkCoords = 'keep'_,
    _shards : zarr.core.array.ShardsLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") | Literal['keep'] = 'keep'_,
    _filters : zarr.core.array.FiltersLike | Literal['keep'] = 'keep'_,
    _compressors : zarr.core.array.CompressorsLike | Literal['keep'] = 'keep'_,
    _serializer : zarr.core.array.SerializerLike | Literal['keep'] = 'keep'_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = DEFAULT_FILL_VALUE_,
    _order : zarr.core.common.MemoryOrder | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_key_encoding : zarr.core.chunk_key_encodings.ChunkKeyEncodingLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_names : zarr.core.common.DimensionNames = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _config : zarr.core.array_spec.ArrayConfigLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.array.Array#

    

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

Parameters:

    

**store** str or Store

    

Store or path to directory in file system or name of zip file for the new
array.

**data** Array | array-like
    

The array to copy.

**write_data** bool, default True

    

Whether to copy the data from the input array to the new array. If
`write_data` is `False`, the new array will be created with the same metadata
as the input array, but without any data.

**name** str or None, optional

    

The name of the array within the store. If `name` is `None`, the array will be
located at the root of the store.

**chunks** ChunkCoords or “auto” or “keep”, optional

    

Chunk shape of the array. Following values are supported:

  * “auto”: Automatically determine the chunk shape based on the array’s shape and dtype.

  * “keep”: Retain the chunk shape of the data array if it is a zarr Array.

  * ChunkCoords: A tuple of integers representing the chunk shape.

If not specified, defaults to “keep” if data is a zarr Array, otherwise
“auto”.

**shards** ChunkCoords, optional

    

Shard shape of the array. Following values are supported:

  * “auto”: Automatically determine the shard shape based on the array’s shape and chunk shape.

  * “keep”: Retain the shard shape of the data array if it is a zarr Array.

  * ChunkCoords: A tuple of integers representing the shard shape.

  * None: No sharding.

If not specified, defaults to “keep” if data is a zarr Array, otherwise None.

**filters** Iterable[Codec] or “auto” or “keep”, optional

    

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

For Zarr format 3, a “filter” is a codec that takes an array and returns an
array, and these values must be instances of `ArrayArrayCodec`, or dict
representations of `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.

Following values are supported:

  * Iterable[Codec]: List of filters to apply to the array.

  * “auto”: Automatically determine the filters based on the array’s dtype.

  * “keep”: Retain the filters of the data array if it is a zarr Array.

If no `filters` are provided, defaults to “keep” if data is a zarr Array,
otherwise “auto”.

**compressors** Iterable[Codec] or “auto” or “keep”, optional

    

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

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

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

Following values are supported:

  * Iterable[Codec]: List of compressors to apply to the array.

  * “auto”: Automatically determine the compressors based on the array’s dtype.

  * “keep”: Retain the compressors of the input array if it is a zarr Array.

If no `compressors` are provided, defaults to “keep” if data is a zarr Array,
otherwise “auto”.

**serializer** dict[str, JSON] | ArrayBytesCodec or “auto” or “keep”, optional
    

Array-to-bytes codec to use for encoding the array data. Zarr format 3 only.
Zarr format 2 arrays use implicit array-to-bytes conversion.

Following values are supported:

  * dict[str, JSON]: A dict representation of an `ArrayBytesCodec`.

  * ArrayBytesCodec: An instance of `ArrayBytesCodec`.

  * “auto”: a default serializer will be used. These defaults can be changed by modifying the value of `array.v3_default_serializer` in `zarr.core.config`.

  * “keep”: Retain the serializer of the input array if it is a zarr Array.

**fill_value** Any, optional

    

Fill value for the array. If not specified, defaults to the fill value of the
data array.

**order**{“C”, “F”}, optional

    

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

**zarr_format**{2, 3}, optional

    

The zarr format to use when saving. If not specified, defaults to the zarr
format of the data array.

**attributes** dict, optional

    

Attributes for the array. If not specified, defaults to the attributes of the
data array.

**chunk_key_encoding** ChunkKeyEncoding, optional

    

A specification of how the chunk keys are represented in storage. For Zarr
format 3, the default is `{"name": "default", "separator": "/"}}`. For Zarr
format 2, the default is `{"name": "v2", "separator": "."}}`. If not specified
and the data array has the same zarr format as the target array, the chunk key
encoding of the data array is used.

**dimension_names** Iterable[str], optional

    

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

**storage_options** dict, optional

    

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

**overwrite** bool, default False

    

Whether to overwrite an array with the same name in the store, if one exists.

**config** ArrayConfig or ArrayConfigLike, optional

    

Runtime configuration for the array.

Returns:

    

Array

    

The array.

Examples

Create an array from an existing Array:

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

Create an array from an existing NumPy array:

    
    
    >>> import numpy as np
    >>> arr3 = zarr.from_array(
            zarr.storage.MemoryStore(),
    >>>     data=np.arange(10000, dtype='i4').reshape(100, 100),
    >>> )
    <Array memory://125477403529984 shape=(100, 100) dtype=int32>
    

Create an array from any array-like object:

    
    
    >>> arr4 = zarr.from_array(
    >>>     zarr.storage.MemoryStore(),
    >>>     data=[[1, 2], [3, 4]],
    >>> )
    <Array memory://125477392154368 shape=(2, 2) dtype=int64>
    >>> arr4[...]
    array([[1, 2],[3, 4]])
    

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

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

zarr.api.synchronous.full(

    _shape : zarr.core.common.ChunkCoords_,
    _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 `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

zarr.api.synchronous.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 `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

zarr.api.synchronous.group(

    _store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _*_ ,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _chunk_store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _cache_attrs : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _synchronizer : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _meta_array : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.group.Group#

    

Create a group.

Parameters:

    

**store** Store or str, optional

    

Store or path to directory in file system.

**overwrite** bool, optional

    

If True, delete any pre-existing data in store at path before creating the
group.

**chunk_store** Store, optional

    

Separate storage for chunks. If not provided, store will be used for storage
of both chunks and metadata.

**cache_attrs** bool, optional

    

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

**synchronizer** object, optional

    

Array synchronizer.

**path** str, optional

    

Group path within store.

**meta_array** array-like, optional

    

An array instance to use for determining arrays to create and return to users.
Use numpy.empty(()) by default.

**zarr_format**{2, 3, None}, optional

    

The zarr format to use when saving.

**storage_options** dict

    

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

Returns:

    

**g** Group

    

The new group.

zarr.api.synchronous.load(

    _store : zarr.storage.StoreLike_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.NDArrayLikeOrScalar | [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.buffer.NDArrayLikeOrScalar]#
    

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.

See also

`save`, `savez`

    

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.

zarr.api.synchronous.ones(

    _shape : zarr.core.common.ChunkCoords_,
    _** 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 `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

zarr.api.synchronous.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 `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

zarr.api.synchronous.open(

    _store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _*_ ,
    _mode : zarr.core.common.AccessModeLiteral | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 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). If the store is
read-only, the default is ‘r’; otherwise, it is ‘a’.

**zarr_format**{2, 3, None}, optional

    

The zarr format to use when saving.

**path** str or None, optional

    

The path within the store to open.

**storage_options** dict

    

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

****kwargs**

    

Additional parameters are passed through to
`zarr.api.asynchronous.open_array()` or `zarr.api.asynchronous.open_group()`.

Returns:

    

**z** array or group

    

Return type depends on what exists in the given store.

zarr.api.synchronous.open_array(

    _store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _*_ ,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : zarr.api.asynchronous.PathLike = ''_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _** kwargs: Any_,
) -> zarr.core.array.Array#

    

Open an array using file-mode-like semantics.

Parameters:

    

**store** Store or str

    

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.

**path** str, optional

    

Path in store to array.

**storage_options** dict

    

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

****kwargs**

    

Any keyword arguments to pass to `create`.

Returns:

    

AsyncArray

    

The opened array.

zarr.api.synchronous.open_consolidated(

    _* args: Any_,
    _use_consolidated : Literal[True] = True_,
    _** kwargs: Any_,
) -> zarr.core.group.Group#

    

Alias for `open_group()` with `use_consolidated=True`.

zarr.api.synchronous.open_group(

    _store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _*_ ,
    _mode : zarr.core.common.AccessModeLiteral = 'a'_,
    _cache_attrs : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _synchronizer : Any = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _meta_array : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _use_consolidated : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.group.Group#

    

Open a group using file-mode-like semantics.

Parameters:

    

**store** Store, str, or mapping, optional

    

Store or path to directory in file system or name of zip file.

Strings are interpreted as paths on the local file system and used as the
`root` argument to `zarr.storage.LocalStore`.

Dictionaries are used as the `store_dict` argument in
`zarr.storage.MemoryStore``.

By default (`store=None`) a new `zarr.storage.MemoryStore` is created.

**mode**{‘r’, ‘r+’, ‘a’, ‘w’, ‘w-‘}, optional

    

Persistence mode: ‘r’ means read only (must exist); ‘r+’ means read/write
(must exist); ‘a’ means read/write (create if doesn’t exist); ‘w’ means create
(overwrite if exists); ‘w-’ means create (fail if exists).

**cache_attrs** bool, optional

    

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

**synchronizer** object, optional

    

Array synchronizer.

**path** str, optional

    

Group path within store.

**chunk_store** Store or str, optional

    

Store or path to directory in file system or name of zip file.

**storage_options** dict

    

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

**meta_array** array-like, optional

    

An array instance to use for determining arrays to create and return to users.
Use numpy.empty(()) by default.

**attributes** dict

    

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

**use_consolidated** bool or str, default None

    

Whether to use consolidated metadata.

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

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

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

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

Returns:

    

**g** Group

    

The new group.

zarr.api.synchronous.open_like(

    _a : zarr.api.asynchronous.ArrayLike_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _** 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.

zarr.api.synchronous.save(

    _store : zarr.storage.StoreLike_,
    _* args: zarr.core.buffer.NDArrayLike_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _** kwargs: Any_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

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.

zarr.api.synchronous.save_array(

    _store : zarr.storage.StoreLike_,
    _arr : zarr.core.buffer.NDArrayLike_,
    _*_ ,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _** kwargs: Any_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

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 `create()`, e.g., compressor.

zarr.api.synchronous.save_group(

    _store : zarr.storage.StoreLike_,
    _* args: zarr.core.buffer.NDArrayLike_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _** kwargs: zarr.core.buffer.NDArrayLike_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

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.

zarr.api.synchronous.tree(

    _grp : zarr.core.group.Group_,
    _expand : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _level : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> Any#

    

Provide a rich display of the hierarchy.

Deprecated since version 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.

zarr.api.synchronous.zeros(

    _shape : zarr.core.common.ChunkCoords_,
    _** 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 `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

zarr.api.synchronous.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 `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

#### zarr.buffer#

Implementations of the Zarr Buffer interface.

See also

`zarr.abc.buffer`

    

Abstract base class for the Zarr Buffer interface.

##### Submodules#

###### zarr.buffer.cpu#

###### Attributes#

`buffer_prototype` |   
---|---  
  
###### Classes#

`Buffer` | A flat contiguous memory block  
---|---  
`NDBuffer` | An n-dimensional memory block  
  
###### Functions#

`as_numpy_array_wrapper`(→ zarr.core.buffer.core.Buffer) | Converts the input of func to a numpy array and the output back to Buffer.  
---|---  
`numpy_buffer_prototype`(...) |   
  
###### Module Contents#

_class _zarr.buffer.cpu.Buffer(_array_like :
zarr.core.buffer.core.ArrayLike_)#

    

Bases: `zarr.core.buffer.core.Buffer`

A flat contiguous memory block

We use Buffer throughout Zarr to represent a contiguous block of memory.

A Buffer is backed by a underlying array-like instance that represents the
memory. The memory type is unspecified; can be regular host memory, CUDA
device memory, or something else. The only requirement is that the array-like
instance can be copied/converted to a regular Numpy array (host memory).

Parameters:

    

**array_like**

    

array-like object that must be 1-dim, contiguous, and byte dtype.

Notes

This buffer is untyped, so all indexing and sizes are in bytes.

as_array_like() -> ArrayLike#

    

Returns the underlying array (host or device memory) of this buffer

This will never copy data.

Returns:

    

The underlying 1d array such as a NumPy or CuPy array.

    

as_buffer_like() -> zarr.core.common.BytesLike#

    

Returns the buffer as an object that implements the Python buffer protocol.

Returns:

    

An object that implements the Python buffer protocol

    

Notes

Might have to copy data, since the implementation uses .as_numpy_array().

as_numpy_array() -> numpy.typing.NDArray[Any]#

    

Returns the buffer as a NumPy array (host memory).

Returns:

    

NumPy array of this buffer (might be a data copy)

    

Notes

Might have to copy data, consider using .as_array_like() instead.

_classmethod _create_zero_length() -> Self#

    

Create an empty buffer with length zero

Returns:

    

New empty 0-length buffer

    

_classmethod _from_array_like(_array_like : ArrayLike_) -> Self#

    

Create a new buffer of an array-like object

Parameters:

    

**array_like**

    

array-like object that must be 1-dim, contiguous, and byte dtype.

Returns:

    

New buffer representing array_like

    

_classmethod _from_buffer(_buffer : zarr.core.buffer.core.Buffer_) -> Self#

    

Create a new buffer of an existing Buffer

This is useful if you want to ensure that an existing buffer is of the correct
subclass of Buffer. E.g., MemoryStore uses this to return a buffer instance of
the subclass specified by its BufferPrototype argument.

Typically, this only copies data if the data has to be moved between memory
types, such as from host to device memory.

Parameters:

    

**buffer**

    

buffer object.

Returns:

    

A new buffer representing the content of the input buffer

    

Notes

Subclasses of Buffer must override this method to implement more optimal
conversions that avoid copies where possible

_classmethod _from_bytes(_bytes_like : zarr.core.common.BytesLike_) -> Self#

    

Create a new buffer of a bytes-like object (host memory)

Parameters:

    

**bytes_like**

    

bytes-like object

Returns:

    

New buffer representing bytes_like

    

to_bytes() -> [bytes](https://docs.python.org/3/library/stdtypes.html#bytes
"\(in Python v3.13\)")#

    

Returns the buffer as bytes (host memory).

Returns:

    

bytes of this buffer (data copy)

    

Warning

Will always copy data, only use this method for small buffers such as metadata
buffers. If possible, use .as_numpy_array() or .as_array_like() instead.

_class _zarr.buffer.cpu.NDBuffer(_array : zarr.core.buffer.core.NDArrayLike_)#

    

Bases: `zarr.core.buffer.core.NDBuffer`

An n-dimensional memory block

We use NDBuffer throughout Zarr to represent a n-dimensional memory block.

A NDBuffer is backed by a underlying ndarray-like instance that represents the
memory. The memory type is unspecified; can be regular host memory, CUDA
device memory, or something else. The only requirement is that the ndarray-
like instance can be copied/converted to a regular Numpy array (host memory).

Parameters:

    

**array**

    

ndarray-like object that is convertible to a regular Numpy array.

Notes

The two buffer classes Buffer and NDBuffer are very similar. In fact, Buffer
is a special case of NDBuffer where dim=1, stride=1, and dtype=”B”. However,
in order to use Python’s type system to differentiate between the contiguous
Buffer and the n-dim (non-contiguous) NDBuffer, we keep the definition of the
two classes separate.

all_equal(_other : Any_, _equal_nan :
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)") = True_) ->
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")#

    

Compare to other using np.array_equal.

as_ndarray_like() -> NDArrayLike#

    

Returns the underlying array (host or device memory) of this buffer

This will never copy data.

Returns:

    

The underlying array such as a NumPy or CuPy array.

    

as_numpy_array() -> numpy.typing.NDArray[Any]#

    

Returns the buffer as a NumPy array (host memory).

Returns:

    

NumPy array of this buffer (might be a data copy)

    

Warning

Might have to copy data, consider using .as_ndarray_like() instead.

as_scalar() -> ScalarType#

    

Returns the buffer as a scalar value

astype(

    _dtype : numpy.typing.DTypeLike_,
    _order : Literal['K', 'A', 'C', 'F'] = 'K'_,
) -> Self#

    

copy() -> Self#

    

_classmethod _create(

    _*_ ,
    _shape : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")]_,
    _dtype : numpy.typing.DTypeLike_,
    _order : Literal['C', 'F'] = 'C'_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> Self#

    

Create a new buffer and its underlying ndarray-like object

Parameters:

    

**shape**

    

The shape of the buffer and its underlying ndarray-like object

**dtype**

    

The datatype of the buffer and its underlying ndarray-like object

**order**

    

Whether to store multi-dimensional data in row-major (C-style) or column-major
(Fortran-style) order in memory.

**fill_value**

    

If not None, fill the new buffer with a scalar value.

Returns:

    

New buffer representing a new ndarray_like object

    

Notes

A subclass can overwrite this method to create a ndarray-like object other
then the default Numpy array.

_classmethod _empty(

    _shape : zarr.core.common.ChunkCoords_,
    _dtype : numpy.typing.DTypeLike_,
    _order : Literal['C', 'F'] = 'C'_,
) -> Self#

    

Create an empty buffer with the given shape, dtype, and order.

This method can be faster than `NDBuffer.create` because it doesn’t have to
initialize the memory used by the underlying ndarray-like object.

Parameters:

    

**shape**

    

The shape of the buffer and its underlying ndarray-like object

**dtype**

    

The datatype of the buffer and its underlying ndarray-like object

**order**

    

Whether to store multi-dimensional data in row-major (C-style) or column-major
(Fortran-style) order in memory.

Returns:

    

buffer

    

New buffer representing a new ndarray_like object with empty data.

See also

`NDBuffer.create`

    

Create a new buffer with some initial fill value.

fill(_value : Any_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_classmethod _from_ndarray_like(_ndarray_like : NDArrayLike_) -> Self#

    

Create a new buffer of a ndarray-like object

Parameters:

    

**ndarray_like**

    

ndarray-like object

Returns:

    

New buffer representing ndarray_like

    

_classmethod _from_numpy_array(_array_like : numpy.typing.ArrayLike_) -> Self#

    

Create a new buffer of Numpy array-like object

Parameters:

    

**array_like**

    

Object that can be coerced into a Numpy array

Returns:

    

New buffer representing array_like

    

reshape(_newshape : zarr.core.common.ChunkCoords | Literal[-1]_) -> Self#
    

squeeze(_axis : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple
"\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), Ellipsis]_) -> Self#

    

transpose(

    _axes : SupportsIndex | [collections.abc.Sequence](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "\(in Python v3.13\)")[SupportsIndex] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")_,
) -> Self#

    

_property _byteorder _: zarr.codecs.bytes.Endian_#

    

_property _dtype _:
[numpy.dtype](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype
"\(in NumPy v2.3\)")[Any]_#

    

_property _shape _:
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), Ellipsis]_#

    

zarr.buffer.cpu.as_numpy_array_wrapper(

    _func : [collections.abc.Callable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "\(in Python v3.13\)")[[numpy.typing.NDArray[Any]], [bytes](https://docs.python.org/3/library/stdtypes.html#bytes "\(in Python v3.13\)")]_,
    _buf : zarr.core.buffer.core.Buffer_,
    _prototype : zarr.core.buffer.core.BufferPrototype_,
) -> zarr.core.buffer.core.Buffer#

    

Converts the input of func to a numpy array and the output back to Buffer.

This function is useful when calling a func that only support host memory such
as GZip.decode and Blosc.decode. In this case, use this wrapper to convert the
input buf to a Numpy array and convert the result back into a Buffer.

Parameters:

    

**func**

    

The callable that will be called with the converted buf as input. func must
return bytes, which will be converted into a Buffer before returned.

**buf**

    

The buffer that will be converted to a Numpy array before given as input to
func.

**prototype**

    

The prototype of the output buffer.

Returns:

    

The result of func converted to a Buffer

    

zarr.buffer.cpu.numpy_buffer_prototype() ->
zarr.core.buffer.core.BufferPrototype#

    

zarr.buffer.cpu.buffer_prototype#

    

###### zarr.buffer.gpu#

###### Attributes#

`buffer_prototype` |   
---|---  
  
###### Classes#

`Buffer` | A flat contiguous memory block on the GPU  
---|---  
`NDBuffer` | A n-dimensional memory block on the GPU  
  
###### Module Contents#

_class _zarr.buffer.gpu.Buffer(_array_like :
zarr.core.buffer.core.ArrayLike_)#

    

Bases: `zarr.core.buffer.core.Buffer`

A flat contiguous memory block on the GPU

We use Buffer throughout Zarr to represent a contiguous block of memory.

A Buffer is backed by a underlying array-like instance that represents the
memory. The memory type is unspecified; can be regular host memory, CUDA
device memory, or something else. The only requirement is that the array-like
instance can be copied/converted to a regular Numpy array (host memory).

Parameters:

    

**array_like**

    

array-like object that must be 1-dim, contiguous, and byte dtype.

Notes

This buffer is untyped, so all indexing and sizes are in bytes.

as_array_like() -> ArrayLike#

    

Returns the underlying array (host or device memory) of this buffer

This will never copy data.

Returns:

    

The underlying 1d array such as a NumPy or CuPy array.

    

as_buffer_like() -> zarr.core.common.BytesLike#

    

Returns the buffer as an object that implements the Python buffer protocol.

Returns:

    

An object that implements the Python buffer protocol

    

Notes

Might have to copy data, since the implementation uses .as_numpy_array().

as_numpy_array() -> numpy.typing.NDArray[Any]#

    

Returns the buffer as a NumPy array (host memory).

Returns:

    

NumPy array of this buffer (might be a data copy)

    

Notes

Might have to copy data, consider using .as_array_like() instead.

_classmethod _create_zero_length() -> Self#

    

Create an empty buffer with length zero

Returns:

    

New empty 0-length buffer

    

_classmethod _from_array_like(_array_like : ArrayLike_) -> Self#

    

Create a new buffer of an array-like object

Parameters:

    

**array_like**

    

array-like object that must be 1-dim, contiguous, and byte dtype.

Returns:

    

New buffer representing array_like

    

_classmethod _from_buffer(_buffer : zarr.core.buffer.core.Buffer_) -> Self#

    

Create an GPU Buffer given an arbitrary Buffer This will try to be zero-copy
if buffer is already on the GPU and will trigger a copy if not.

Returns:

    

New GPU Buffer constructed from buffer

    

_classmethod _from_bytes(_bytes_like : zarr.core.common.BytesLike_) -> Self#

    

Create a new buffer of a bytes-like object (host memory)

Parameters:

    

**bytes_like**

    

bytes-like object

Returns:

    

New buffer representing bytes_like

    

to_bytes() -> [bytes](https://docs.python.org/3/library/stdtypes.html#bytes
"\(in Python v3.13\)")#

    

Returns the buffer as bytes (host memory).

Returns:

    

bytes of this buffer (data copy)

    

Warning

Will always copy data, only use this method for small buffers such as metadata
buffers. If possible, use .as_numpy_array() or .as_array_like() instead.

_class _zarr.buffer.gpu.NDBuffer(_array : zarr.core.buffer.core.NDArrayLike_)#

    

Bases: `zarr.core.buffer.core.NDBuffer`

A n-dimensional memory block on the GPU

We use NDBuffer throughout Zarr to represent a n-dimensional memory block.

A NDBuffer is backed by a underlying ndarray-like instance that represents the
memory. The memory type is unspecified; can be regular host memory, CUDA
device memory, or something else. The only requirement is that the ndarray-
like instance can be copied/converted to a regular Numpy array (host memory).

Parameters:

    

**array**

    

ndarray-like object that is convertible to a regular Numpy array.

Notes

The two buffer classes Buffer and NDBuffer are very similar. In fact, Buffer
is a special case of NDBuffer where dim=1, stride=1, and dtype=”B”. However,
in order to use Python’s type system to differentiate between the contiguous
Buffer and the n-dim (non-contiguous) NDBuffer, we keep the definition of the
two classes separate.

all_equal(_other : Any_, _equal_nan :
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)") = True_) ->
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")#

    

Compare to other using np.array_equal.

as_ndarray_like() -> NDArrayLike#

    

Returns the underlying array (host or device memory) of this buffer

This will never copy data.

Returns:

    

The underlying array such as a NumPy or CuPy array.

    

as_numpy_array() -> numpy.typing.NDArray[Any]#

    

Returns the buffer as a NumPy array (host memory).

Returns:

    

NumPy array of this buffer (might be a data copy)

    

Warning

Might have to copy data, consider using .as_ndarray_like() instead.

as_scalar() -> ScalarType#

    

Returns the buffer as a scalar value

astype(

    _dtype : numpy.typing.DTypeLike_,
    _order : Literal['K', 'A', 'C', 'F'] = 'K'_,
) -> Self#

    

copy() -> Self#

    

_classmethod _create(

    _*_ ,
    _shape : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")]_,
    _dtype : numpy.typing.DTypeLike_,
    _order : Literal['C', 'F'] = 'C'_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> Self#

    

Create a new buffer and its underlying ndarray-like object

Parameters:

    

**shape**

    

The shape of the buffer and its underlying ndarray-like object

**dtype**

    

The datatype of the buffer and its underlying ndarray-like object

**order**

    

Whether to store multi-dimensional data in row-major (C-style) or column-major
(Fortran-style) order in memory.

**fill_value**

    

If not None, fill the new buffer with a scalar value.

Returns:

    

New buffer representing a new ndarray_like object

    

Notes

A subclass can overwrite this method to create a ndarray-like object other
then the default Numpy array.

_classmethod _empty(

    _shape : zarr.core.common.ChunkCoords_,
    _dtype : numpy.typing.DTypeLike_,
    _order : Literal['C', 'F'] = 'C'_,
) -> Self#

    

Create an empty buffer with the given shape, dtype, and order.

This method can be faster than `NDBuffer.create` because it doesn’t have to
initialize the memory used by the underlying ndarray-like object.

Parameters:

    

**shape**

    

The shape of the buffer and its underlying ndarray-like object

**dtype**

    

The datatype of the buffer and its underlying ndarray-like object

**order**

    

Whether to store multi-dimensional data in row-major (C-style) or column-major
(Fortran-style) order in memory.

Returns:

    

buffer

    

New buffer representing a new ndarray_like object with empty data.

See also

`NDBuffer.create`

    

Create a new buffer with some initial fill value.

fill(_value : Any_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_classmethod _from_ndarray_like(_ndarray_like : NDArrayLike_) -> Self#

    

Create a new buffer of a ndarray-like object

Parameters:

    

**ndarray_like**

    

ndarray-like object

Returns:

    

New buffer representing ndarray_like

    

_classmethod _from_numpy_array(_array_like : numpy.typing.ArrayLike_) -> Self#

    

Create a new buffer of Numpy array-like object

Parameters:

    

**array_like**

    

Object that can be coerced into a Numpy array

Returns:

    

New buffer representing array_like

    

reshape(_newshape : zarr.core.common.ChunkCoords | Literal[-1]_) -> Self#
    

squeeze(_axis : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple
"\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), Ellipsis]_) -> Self#

    

transpose(

    _axes : SupportsIndex | [collections.abc.Sequence](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "\(in Python v3.13\)")[SupportsIndex] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")_,
) -> Self#

    

_property _byteorder _: zarr.codecs.bytes.Endian_#

    

_property _dtype _:
[numpy.dtype](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype
"\(in NumPy v2.3\)")[Any]_#

    

_property _shape _:
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), Ellipsis]_#

    

zarr.buffer.gpu.buffer_prototype#

    

##### Functions#

`default_buffer_prototype`(→ BufferPrototype) |   
---|---  
  
##### Package Contents#

zarr.buffer.default_buffer_prototype() -> BufferPrototype#

    

#### zarr.codecs#

##### Classes#

`BloscCname` | Enum for compression library used by blosc.  
---|---  
`BloscCodec` | blosc codec  
`BloscShuffle` | Enum for shuffle filter used by blosc.  
`BytesCodec` | bytes codec  
`Crc32cCodec` | crc32c codec  
`Endian` | Enum for endian type used by bytes codec.  
`GzipCodec` | gzip codec  
`ShardingCodec` | Sharding codec  
`ShardingCodecIndexLocation` | Enum for index location used by the sharding codec.  
`TransposeCodec` | Transpose codec  
`VLenBytesCodec` | Base class for array-to-bytes codecs.  
`VLenUTF8Codec` | Variable-length UTF8 codec  
`ZstdCodec` | zstd codec  
  
##### Package Contents#

_class _zarr.codecs.BloscCname(_* args_, _** kwds_)#

    

Bases: [`enum.Enum`](https://docs.python.org/3/library/enum.html#enum.Enum
"\(in Python v3.13\)")

Enum for compression library used by blosc.

blosclz _ = 'blosclz'_#

    

lz4 _ = 'lz4'_#

    

lz4hc _ = 'lz4hc'_#

    

snappy _ = 'snappy'_#

    

zlib _ = 'zlib'_#

    

zstd _ = 'zstd'_#

    

_class _zarr.codecs.BloscCodec(

    _*_ ,
    _typesize : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _cname : BloscCname | [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") = BloscCname.zstd_,
    _clevel : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") = 5_,
    _shuffle : BloscShuffle | [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _blocksize : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") = 0_,
)#

    

Bases: `zarr.abc.codec.BytesBytesCodec`

blosc codec

_abstract _compute_encoded_size(

    __input_byte_length : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")_,
    __chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> [int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Given an input byte length, this method returns the output byte length. Raises
a NotImplementedError for codecs with variable-sized outputs (e.g.
compressors).

Parameters:

    

**input_byte_length** int

    
**chunk_spec** ArraySpec

    
Returns:

    

int

    

_async _decode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Decodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecOutput | None, ArraySpec]]
    

Ordered set of encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecInput | None]
    

_async _encode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Encodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecInput | None, ArraySpec]]
    

Ordered set of to-be-encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecOutput | None]
    

evolve_from_array_spec(_array_spec : zarr.core.array_spec.ArraySpec_) -> Self#

    

Fills in codec configuration parameters that can be automatically inferred
from the array metadata.

Parameters:

    

**array_spec** ArraySpec

    
Returns:

    

Self

    

_classmethod _from_dict(_data :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), zarr.core.common.JSON]_) -> Self#

    

Create an instance of the model from a dictionary

resolve_metadata(

    _chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> zarr.core.array_spec.ArraySpec#

    

Computed the spec of the chunk after it has been encoded by the codec. This is
important for codecs that change the shape, data type or fill value of a
chunk. The spec will then be used for subsequent codecs in the pipeline.

Parameters:

    

**chunk_spec** ArraySpec

    
Returns:

    

ArraySpec

    

to_dict() -> [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"), zarr.core.common.JSON]#

    

Recursively serialize this model to a dictionary. This method inspects the
fields of self and calls x.to_dict() for any fields that are instances of
Metadata. Sequences of Metadata are similarly recursed into, and the output of
that recursion is collected in a list.

validate(

    _*_ ,
    _shape : zarr.core.common.ChunkCoords_,
    _dtype : zarr.core.dtype.wrapper.ZDType[zarr.core.dtype.wrapper.TBaseDType, zarr.core.dtype.wrapper.TBaseScalar]_,
    _chunk_grid : zarr.core.chunk_grids.ChunkGrid_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Validates that the codec configuration is compatible with the array metadata.
Raises errors when the codec configuration is not compatible.

Parameters:

    

**shape** ChunkCoords

    

The array shape

**dtype** np.dtype[Any]

    

The array data type

**chunk_grid** ChunkGrid

    

The array chunk grid

blocksize _: [int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)")_ _ = 0_#

    

clevel _: [int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)")_ _ = 5_#

    

cname _: BloscCname_#

    

is_fixed_size _ = False_#

    

shuffle _: BloscShuffle | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")_#
    

typesize _: [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")_#
    

_class _zarr.codecs.BloscShuffle(_* args_, _** kwds_)#

    

Bases: [`enum.Enum`](https://docs.python.org/3/library/enum.html#enum.Enum
"\(in Python v3.13\)")

Enum for shuffle filter used by blosc.

_classmethod _from_int(_num :
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_) -> BloscShuffle#

    

bitshuffle _ = 'bitshuffle'_#

    

noshuffle _ = 'noshuffle'_#

    

shuffle _ = 'shuffle'_#

    

_class _zarr.codecs.BytesCodec(_*_ , _endian : Endian | [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = default_system_endian_)#
    

Bases: `zarr.abc.codec.ArrayBytesCodec`

bytes codec

compute_encoded_size(

    _input_byte_length : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")_,
    __chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> [int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Given an input byte length, this method returns the output byte length. Raises
a NotImplementedError for codecs with variable-sized outputs (e.g.
compressors).

Parameters:

    

**input_byte_length** int

    
**chunk_spec** ArraySpec

    
Returns:

    

int

    

_async _decode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Decodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecOutput | None, ArraySpec]]
    

Ordered set of encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecInput | None]
    

_async _encode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Encodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecInput | None, ArraySpec]]
    

Ordered set of to-be-encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecOutput | None]
    

evolve_from_array_spec(_array_spec : zarr.core.array_spec.ArraySpec_) -> Self#

    

Fills in codec configuration parameters that can be automatically inferred
from the array metadata.

Parameters:

    

**array_spec** ArraySpec

    
Returns:

    

Self

    

_classmethod _from_dict(_data :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), zarr.core.common.JSON]_) -> Self#

    

Create an instance of the model from a dictionary

resolve_metadata(

    _chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> zarr.core.array_spec.ArraySpec#

    

Computed the spec of the chunk after it has been encoded by the codec. This is
important for codecs that change the shape, data type or fill value of a
chunk. The spec will then be used for subsequent codecs in the pipeline.

Parameters:

    

**chunk_spec** ArraySpec

    
Returns:

    

ArraySpec

    

to_dict() -> [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"), zarr.core.common.JSON]#

    

Recursively serialize this model to a dictionary. This method inspects the
fields of self and calls x.to_dict() for any fields that are instances of
Metadata. Sequences of Metadata are similarly recursed into, and the output of
that recursion is collected in a list.

validate(

    _*_ ,
    _shape : zarr.core.common.ChunkCoords_,
    _dtype : zarr.core.dtype.wrapper.ZDType[zarr.core.dtype.wrapper.TBaseDType, zarr.core.dtype.wrapper.TBaseScalar]_,
    _chunk_grid : zarr.core.chunk_grids.ChunkGrid_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Validates that the codec configuration is compatible with the array metadata.
Raises errors when the codec configuration is not compatible.

Parameters:

    

**shape** ChunkCoords

    

The array shape

**dtype** np.dtype[Any]

    

The array data type

**chunk_grid** ChunkGrid

    

The array chunk grid

endian _: Endian | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")_#
    

is_fixed_size _ = True_#

    

_class _zarr.codecs.Crc32cCodec#

    

Bases: `zarr.abc.codec.BytesBytesCodec`

crc32c codec

compute_encoded_size(

    _input_byte_length : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")_,
    __chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> [int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Given an input byte length, this method returns the output byte length. Raises
a NotImplementedError for codecs with variable-sized outputs (e.g.
compressors).

Parameters:

    

**input_byte_length** int

    
**chunk_spec** ArraySpec

    
Returns:

    

int

    

_async _decode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Decodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecOutput | None, ArraySpec]]
    

Ordered set of encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecInput | None]
    

_async _encode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Encodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecInput | None, ArraySpec]]
    

Ordered set of to-be-encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecOutput | None]
    

evolve_from_array_spec(_array_spec : zarr.core.array_spec.ArraySpec_) -> Self#

    

Fills in codec configuration parameters that can be automatically inferred
from the array metadata.

Parameters:

    

**array_spec** ArraySpec

    
Returns:

    

Self

    

_classmethod _from_dict(_data :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), zarr.core.common.JSON]_) -> Self#

    

Create an instance of the model from a dictionary

resolve_metadata(

    _chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> zarr.core.array_spec.ArraySpec#

    

Computed the spec of the chunk after it has been encoded by the codec. This is
important for codecs that change the shape, data type or fill value of a
chunk. The spec will then be used for subsequent codecs in the pipeline.

Parameters:

    

**chunk_spec** ArraySpec

    
Returns:

    

ArraySpec

    

to_dict() -> [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"), zarr.core.common.JSON]#

    

Recursively serialize this model to a dictionary. This method inspects the
fields of self and calls x.to_dict() for any fields that are instances of
Metadata. Sequences of Metadata are similarly recursed into, and the output of
that recursion is collected in a list.

validate(

    _*_ ,
    _shape : zarr.core.common.ChunkCoords_,
    _dtype : zarr.core.dtype.wrapper.ZDType[zarr.core.dtype.wrapper.TBaseDType, zarr.core.dtype.wrapper.TBaseScalar]_,
    _chunk_grid : zarr.core.chunk_grids.ChunkGrid_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Validates that the codec configuration is compatible with the array metadata.
Raises errors when the codec configuration is not compatible.

Parameters:

    

**shape** ChunkCoords

    

The array shape

**dtype** np.dtype[Any]

    

The array data type

**chunk_grid** ChunkGrid

    

The array chunk grid

is_fixed_size _ = True_#

    

_class _zarr.codecs.Endian(_* args_, _** kwds_)#

    

Bases: [`enum.Enum`](https://docs.python.org/3/library/enum.html#enum.Enum
"\(in Python v3.13\)")

Enum for endian type used by bytes codec.

big _ = 'big'_#

    

little _ = 'little'_#

    

_class _zarr.codecs.GzipCodec(_*_ , _level :
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)") = 5_)#

    

Bases: `zarr.abc.codec.BytesBytesCodec`

gzip codec

_abstract _compute_encoded_size(

    __input_byte_length : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")_,
    __chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> [int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Given an input byte length, this method returns the output byte length. Raises
a NotImplementedError for codecs with variable-sized outputs (e.g.
compressors).

Parameters:

    

**input_byte_length** int

    
**chunk_spec** ArraySpec

    
Returns:

    

int

    

_async _decode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Decodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecOutput | None, ArraySpec]]
    

Ordered set of encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecInput | None]
    

_async _encode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Encodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecInput | None, ArraySpec]]
    

Ordered set of to-be-encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecOutput | None]
    

evolve_from_array_spec(_array_spec : zarr.core.array_spec.ArraySpec_) -> Self#

    

Fills in codec configuration parameters that can be automatically inferred
from the array metadata.

Parameters:

    

**array_spec** ArraySpec

    
Returns:

    

Self

    

_classmethod _from_dict(_data :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), zarr.core.common.JSON]_) -> Self#

    

Create an instance of the model from a dictionary

resolve_metadata(

    _chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> zarr.core.array_spec.ArraySpec#

    

Computed the spec of the chunk after it has been encoded by the codec. This is
important for codecs that change the shape, data type or fill value of a
chunk. The spec will then be used for subsequent codecs in the pipeline.

Parameters:

    

**chunk_spec** ArraySpec

    
Returns:

    

ArraySpec

    

to_dict() -> [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"), zarr.core.common.JSON]#

    

Recursively serialize this model to a dictionary. This method inspects the
fields of self and calls x.to_dict() for any fields that are instances of
Metadata. Sequences of Metadata are similarly recursed into, and the output of
that recursion is collected in a list.

validate(

    _*_ ,
    _shape : zarr.core.common.ChunkCoords_,
    _dtype : zarr.core.dtype.wrapper.ZDType[zarr.core.dtype.wrapper.TBaseDType, zarr.core.dtype.wrapper.TBaseScalar]_,
    _chunk_grid : zarr.core.chunk_grids.ChunkGrid_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Validates that the codec configuration is compatible with the array metadata.
Raises errors when the codec configuration is not compatible.

Parameters:

    

**shape** ChunkCoords

    

The array shape

**dtype** np.dtype[Any]

    

The array data type

**chunk_grid** ChunkGrid

    

The array chunk grid

is_fixed_size _ = False_#

    

level _: [int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)")_ _ = 5_#

    

_class _zarr.codecs.ShardingCodec(

    _*_ ,
    _chunk_shape : zarr.core.common.ChunkCoordsLike_,
    _codecs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[zarr.abc.codec.Codec | [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON]] = (BytesCodec(),)_,
    _index_codecs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[zarr.abc.codec.Codec | [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON]] = (BytesCodec(), Crc32cCodec())_,
    _index_location : ShardingCodecIndexLocation | [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") = ShardingCodecIndexLocation.end_,
)#

    

Bases: `zarr.abc.codec.ArrayBytesCodec`,
`zarr.abc.codec.ArrayBytesCodecPartialDecodeMixin`,
`zarr.abc.codec.ArrayBytesCodecPartialEncodeMixin`

Sharding codec

compute_encoded_size(

    _input_byte_length : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")_,
    _shard_spec : zarr.core.array_spec.ArraySpec_,
) -> [int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Given an input byte length, this method returns the output byte length. Raises
a NotImplementedError for codecs with variable-sized outputs (e.g.
compressors).

Parameters:

    

**input_byte_length** int

    
**chunk_spec** ArraySpec

    
Returns:

    

int

    

_async _decode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Decodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecOutput | None, ArraySpec]]
    

Ordered set of encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecInput | None]
    

_async _decode_partial(

    _batch_info : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[zarr.abc.store.ByteGetter, zarr.core.indexing.SelectorTuple, zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[zarr.core.buffer.NDBuffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Partially decodes a batch of chunks. This method determines parts of a chunk
from the slice selection, fetches these parts from the store (via ByteGetter)
and decodes them.

Parameters:

    

**batch_info** Iterable[tuple[ByteGetter, SelectorTuple, ArraySpec]]

    

Ordered set of information about slices of encoded chunks. The slice selection
determines which parts of the chunk will be fetched. The ByteGetter is used to
fetch the necessary bytes. The chunk spec contains information about the
construction of an array from the bytes.

Returns:

    

Iterable[NDBuffer | None]
    

_async _encode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Encodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecInput | None, ArraySpec]]
    

Ordered set of to-be-encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecOutput | None]
    

_async _encode_partial(

    _batch_info : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[zarr.abc.store.ByteSetter, zarr.core.buffer.NDBuffer, zarr.core.indexing.SelectorTuple, zarr.core.array_spec.ArraySpec]]_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Partially encodes a batch of chunks. This method determines parts of a chunk
from the slice selection, encodes them and writes these parts to the store
(via ByteSetter). If merging with existing chunk data in the store is
necessary, this method will read from the store first and perform the merge.

Parameters:

    

**batch_info** Iterable[tuple[ByteSetter, NDBuffer, SelectorTuple, ArraySpec]]

    

Ordered set of information about slices of to-be-encoded chunks. The slice
selection determines which parts of the chunk will be encoded. The ByteSetter
is used to write the necessary bytes and fetch bytes for existing chunk data.
The chunk spec contains information about the chunk.

evolve_from_array_spec(_array_spec : zarr.core.array_spec.ArraySpec_) -> Self#

    

Fills in codec configuration parameters that can be automatically inferred
from the array metadata.

Parameters:

    

**array_spec** ArraySpec

    
Returns:

    

Self

    

_classmethod _from_dict(_data :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), zarr.core.common.JSON]_) -> Self#

    

Create an instance of the model from a dictionary

resolve_metadata(

    _chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> zarr.core.array_spec.ArraySpec#

    

Computed the spec of the chunk after it has been encoded by the codec. This is
important for codecs that change the shape, data type or fill value of a
chunk. The spec will then be used for subsequent codecs in the pipeline.

Parameters:

    

**chunk_spec** ArraySpec

    
Returns:

    

ArraySpec

    

to_dict() -> [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"), zarr.core.common.JSON]#

    

Recursively serialize this model to a dictionary. This method inspects the
fields of self and calls x.to_dict() for any fields that are instances of
Metadata. Sequences of Metadata are similarly recursed into, and the output of
that recursion is collected in a list.

validate(

    _*_ ,
    _shape : zarr.core.common.ChunkCoords_,
    _dtype : zarr.core.dtype.wrapper.ZDType[zarr.core.dtype.wrapper.TBaseDType, zarr.core.dtype.wrapper.TBaseScalar]_,
    _chunk_grid : zarr.core.chunk_grids.ChunkGrid_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Validates that the codec configuration is compatible with the array metadata.
Raises errors when the codec configuration is not compatible.

Parameters:

    

**shape** ChunkCoords

    

The array shape

**dtype** np.dtype[Any]

    

The array data type

**chunk_grid** ChunkGrid

    

The array chunk grid

chunk_shape _: zarr.core.common.ChunkCoords_#

    

_property _codec_pipeline _: zarr.abc.codec.CodecPipeline_#

    

codecs _: [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in
Python v3.13\)")[zarr.abc.codec.Codec, Ellipsis]_#

    

index_codecs _: [tuple](https://docs.python.org/3/library/stdtypes.html#tuple
"\(in Python v3.13\)")[zarr.abc.codec.Codec, Ellipsis]_#

    

index_location _: ShardingCodecIndexLocation_#

    

is_fixed_size _: [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")_#

    

_class _zarr.codecs.ShardingCodecIndexLocation(_* args_, _** kwds_)#

    

Bases: [`enum.Enum`](https://docs.python.org/3/library/enum.html#enum.Enum
"\(in Python v3.13\)")

Enum for index location used by the sharding codec.

end _ = 'end'_#

    

start _ = 'start'_#

    

_class _zarr.codecs.TransposeCodec(_*_ , _order :
zarr.core.common.ChunkCoordsLike_)#

    

Bases: `zarr.abc.codec.ArrayArrayCodec`

Transpose codec

compute_encoded_size(

    _input_byte_length : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")_,
    __chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> [int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Given an input byte length, this method returns the output byte length. Raises
a NotImplementedError for codecs with variable-sized outputs (e.g.
compressors).

Parameters:

    

**input_byte_length** int

    
**chunk_spec** ArraySpec

    
Returns:

    

int

    

_async _decode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Decodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecOutput | None, ArraySpec]]
    

Ordered set of encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecInput | None]
    

_async _encode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Encodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecInput | None, ArraySpec]]
    

Ordered set of to-be-encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecOutput | None]
    

evolve_from_array_spec(_array_spec : zarr.core.array_spec.ArraySpec_) -> Self#

    

Fills in codec configuration parameters that can be automatically inferred
from the array metadata.

Parameters:

    

**array_spec** ArraySpec

    
Returns:

    

Self

    

_classmethod _from_dict(_data :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), zarr.core.common.JSON]_) -> Self#

    

Create an instance of the model from a dictionary

resolve_metadata(

    _chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> zarr.core.array_spec.ArraySpec#

    

Computed the spec of the chunk after it has been encoded by the codec. This is
important for codecs that change the shape, data type or fill value of a
chunk. The spec will then be used for subsequent codecs in the pipeline.

Parameters:

    

**chunk_spec** ArraySpec

    
Returns:

    

ArraySpec

    

to_dict() -> [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"), zarr.core.common.JSON]#

    

Recursively serialize this model to a dictionary. This method inspects the
fields of self and calls x.to_dict() for any fields that are instances of
Metadata. Sequences of Metadata are similarly recursed into, and the output of
that recursion is collected in a list.

validate(

    _shape : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), Ellipsis]_,
    _dtype : zarr.core.dtype.wrapper.ZDType[zarr.core.dtype.wrapper.TBaseDType, zarr.core.dtype.wrapper.TBaseScalar]_,
    _chunk_grid : zarr.core.chunk_grids.ChunkGrid_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Validates that the codec configuration is compatible with the array metadata.
Raises errors when the codec configuration is not compatible.

Parameters:

    

**shape** ChunkCoords

    

The array shape

**dtype** np.dtype[Any]

    

The array data type

**chunk_grid** ChunkGrid

    

The array chunk grid

is_fixed_size _ = True_#

    

order _: [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in
Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)"), Ellipsis]_#

    

_class _zarr.codecs.VLenBytesCodec#

    

Bases: `zarr.abc.codec.ArrayBytesCodec`

Base class for array-to-bytes codecs.

_abstract _compute_encoded_size(

    _input_byte_length : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")_,
    __chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> [int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Given an input byte length, this method returns the output byte length. Raises
a NotImplementedError for codecs with variable-sized outputs (e.g.
compressors).

Parameters:

    

**input_byte_length** int

    
**chunk_spec** ArraySpec

    
Returns:

    

int

    

_async _decode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Decodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecOutput | None, ArraySpec]]
    

Ordered set of encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecInput | None]
    

_async _encode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Encodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecInput | None, ArraySpec]]
    

Ordered set of to-be-encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecOutput | None]
    

evolve_from_array_spec(_array_spec : zarr.core.array_spec.ArraySpec_) -> Self#

    

Fills in codec configuration parameters that can be automatically inferred
from the array metadata.

Parameters:

    

**array_spec** ArraySpec

    
Returns:

    

Self

    

_classmethod _from_dict(_data :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), zarr.core.common.JSON]_) -> Self#

    

Create an instance of the model from a dictionary

resolve_metadata(

    _chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> zarr.core.array_spec.ArraySpec#

    

Computed the spec of the chunk after it has been encoded by the codec. This is
important for codecs that change the shape, data type or fill value of a
chunk. The spec will then be used for subsequent codecs in the pipeline.

Parameters:

    

**chunk_spec** ArraySpec

    
Returns:

    

ArraySpec

    

to_dict() -> [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"), zarr.core.common.JSON]#

    

Recursively serialize this model to a dictionary. This method inspects the
fields of self and calls x.to_dict() for any fields that are instances of
Metadata. Sequences of Metadata are similarly recursed into, and the output of
that recursion is collected in a list.

validate(

    _*_ ,
    _shape : zarr.core.common.ChunkCoords_,
    _dtype : zarr.core.dtype.wrapper.ZDType[zarr.core.dtype.wrapper.TBaseDType, zarr.core.dtype.wrapper.TBaseScalar]_,
    _chunk_grid : zarr.core.chunk_grids.ChunkGrid_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Validates that the codec configuration is compatible with the array metadata.
Raises errors when the codec configuration is not compatible.

Parameters:

    

**shape** ChunkCoords

    

The array shape

**dtype** np.dtype[Any]

    

The array data type

**chunk_grid** ChunkGrid

    

The array chunk grid

is_fixed_size _: [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")_#

    

_class _zarr.codecs.VLenUTF8Codec#

    

Bases: `zarr.abc.codec.ArrayBytesCodec`

Variable-length UTF8 codec

_abstract _compute_encoded_size(

    _input_byte_length : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")_,
    __chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> [int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Given an input byte length, this method returns the output byte length. Raises
a NotImplementedError for codecs with variable-sized outputs (e.g.
compressors).

Parameters:

    

**input_byte_length** int

    
**chunk_spec** ArraySpec

    
Returns:

    

int

    

_async _decode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Decodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecOutput | None, ArraySpec]]
    

Ordered set of encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecInput | None]
    

_async _encode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Encodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecInput | None, ArraySpec]]
    

Ordered set of to-be-encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecOutput | None]
    

evolve_from_array_spec(_array_spec : zarr.core.array_spec.ArraySpec_) -> Self#

    

Fills in codec configuration parameters that can be automatically inferred
from the array metadata.

Parameters:

    

**array_spec** ArraySpec

    
Returns:

    

Self

    

_classmethod _from_dict(_data :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), zarr.core.common.JSON]_) -> Self#

    

Create an instance of the model from a dictionary

resolve_metadata(

    _chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> zarr.core.array_spec.ArraySpec#

    

Computed the spec of the chunk after it has been encoded by the codec. This is
important for codecs that change the shape, data type or fill value of a
chunk. The spec will then be used for subsequent codecs in the pipeline.

Parameters:

    

**chunk_spec** ArraySpec

    
Returns:

    

ArraySpec

    

to_dict() -> [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"), zarr.core.common.JSON]#

    

Recursively serialize this model to a dictionary. This method inspects the
fields of self and calls x.to_dict() for any fields that are instances of
Metadata. Sequences of Metadata are similarly recursed into, and the output of
that recursion is collected in a list.

validate(

    _*_ ,
    _shape : zarr.core.common.ChunkCoords_,
    _dtype : zarr.core.dtype.wrapper.ZDType[zarr.core.dtype.wrapper.TBaseDType, zarr.core.dtype.wrapper.TBaseScalar]_,
    _chunk_grid : zarr.core.chunk_grids.ChunkGrid_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Validates that the codec configuration is compatible with the array metadata.
Raises errors when the codec configuration is not compatible.

Parameters:

    

**shape** ChunkCoords

    

The array shape

**dtype** np.dtype[Any]

    

The array data type

**chunk_grid** ChunkGrid

    

The array chunk grid

is_fixed_size _: [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")_#

    

_class _zarr.codecs.ZstdCodec(_*_ , _level :
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)") = 0_, _checksum :
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)") = False_)#

    

Bases: `zarr.abc.codec.BytesBytesCodec`

zstd codec

_abstract _compute_encoded_size(

    __input_byte_length : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")_,
    __chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> [int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Given an input byte length, this method returns the output byte length. Raises
a NotImplementedError for codecs with variable-sized outputs (e.g.
compressors).

Parameters:

    

**input_byte_length** int

    
**chunk_spec** ArraySpec

    
Returns:

    

int

    

_async _decode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Decodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecOutput | None, ArraySpec]]
    

Ordered set of encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecInput | None]
    

_async _encode(

    _chunks_and_specs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[CodecInput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)"), zarr.core.array_spec.ArraySpec]]_,
) -> [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[CodecOutput | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Encodes a batch of chunks. Chunks can be None in which case they are ignored
by the codec.

Parameters:

    

**chunks_and_specs** Iterable[tuple[CodecInput | None, ArraySpec]]
    

Ordered set of to-be-encoded chunks with their accompanying chunk spec.

Returns:

    

Iterable[CodecOutput | None]
    

evolve_from_array_spec(_array_spec : zarr.core.array_spec.ArraySpec_) -> Self#

    

Fills in codec configuration parameters that can be automatically inferred
from the array metadata.

Parameters:

    

**array_spec** ArraySpec

    
Returns:

    

Self

    

_classmethod _from_dict(_data :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), zarr.core.common.JSON]_) -> Self#

    

Create an instance of the model from a dictionary

resolve_metadata(

    _chunk_spec : zarr.core.array_spec.ArraySpec_,
) -> zarr.core.array_spec.ArraySpec#

    

Computed the spec of the chunk after it has been encoded by the codec. This is
important for codecs that change the shape, data type or fill value of a
chunk. The spec will then be used for subsequent codecs in the pipeline.

Parameters:

    

**chunk_spec** ArraySpec

    
Returns:

    

ArraySpec

    

to_dict() -> [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"), zarr.core.common.JSON]#

    

Recursively serialize this model to a dictionary. This method inspects the
fields of self and calls x.to_dict() for any fields that are instances of
Metadata. Sequences of Metadata are similarly recursed into, and the output of
that recursion is collected in a list.

validate(

    _*_ ,
    _shape : zarr.core.common.ChunkCoords_,
    _dtype : zarr.core.dtype.wrapper.ZDType[zarr.core.dtype.wrapper.TBaseDType, zarr.core.dtype.wrapper.TBaseScalar]_,
    _chunk_grid : zarr.core.chunk_grids.ChunkGrid_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Validates that the codec configuration is compatible with the array metadata.
Raises errors when the codec configuration is not compatible.

Parameters:

    

**shape** ChunkCoords

    

The array shape

**dtype** np.dtype[Any]

    

The array data type

**chunk_grid** ChunkGrid

    

The array chunk grid

checksum _: [bool](https://docs.python.org/3/library/functions.html#bool "\(in
Python v3.13\)")_ _ = False_#

    

is_fixed_size _ = True_#

    

level _: [int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)")_ _ = 0_#

    

#### zarr.convenience#

Convenience helpers.

Warning

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

##### Functions#

`consolidate_metadata`(→ zarr.core.group.Group) | Consolidate the metadata of all nodes in a hierarchy.  
---|---  
`copy`(→ tuple[int, int, int]) |   
`copy_all`(→ tuple[int, int, int]) |   
`copy_store`(→ tuple[int, int, int]) |   
`load`(...) | Load data from an array or group into memory.  
`open`(→ zarr.core.array.Array | zarr.core.group.Group) | Open a group or array using file-mode-like semantics.  
`open_consolidated`(→ zarr.core.group.Group) | Alias for `open_group()` with `use_consolidated=True`.  
`save`(→ None) | Save an array or group of arrays to the local file system.  
`save_array`(→ None) | Save a NumPy array to the local file system.  
`save_group`(→ None) | Save several NumPy arrays to the local file system.  
`tree`(→ Any) | Provide a rich display of the hierarchy.  
  
##### Module Contents#

zarr.convenience.consolidate_metadata(

    _store : zarr.storage.StoreLike_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 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. For Stores that do not use
consolidated metadata, this operation raises a TypeError.

Parameters:

    

**store** StoreLike

    

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

**path** str, optional

    

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

By default, the root node is used so all the metadata in the store is
consolidated.

**zarr_format**{2, 3, None}, optional

    

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

Returns:

    

group: Group

    

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

zarr.convenience.copy(_* args: Any_, _** kwargs: Any_) ->
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)"),
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")]#

    

zarr.convenience.copy_all(_* args: Any_, _** kwargs: Any_) ->
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)"),
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")]#

    

zarr.convenience.copy_store(_* args: Any_, _** kwargs: Any_) ->
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)"),
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")]#

    

zarr.convenience.load(

    _store : zarr.storage.StoreLike_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.NDArrayLikeOrScalar | [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.buffer.NDArrayLikeOrScalar]#
    

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.

See also

`save`, `savez`

    

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.

zarr.convenience.open(

    _store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _*_ ,
    _mode : zarr.core.common.AccessModeLiteral | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 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). If the store is
read-only, the default is ‘r’; otherwise, it is ‘a’.

**zarr_format**{2, 3, None}, optional

    

The zarr format to use when saving.

**path** str or None, optional

    

The path within the store to open.

**storage_options** dict

    

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

****kwargs**

    

Additional parameters are passed through to
`zarr.api.asynchronous.open_array()` or `zarr.api.asynchronous.open_group()`.

Returns:

    

**z** array or group

    

Return type depends on what exists in the given store.

zarr.convenience.open_consolidated(

    _* args: Any_,
    _use_consolidated : Literal[True] = True_,
    _** kwargs: Any_,
) -> zarr.core.group.Group#

    

Alias for `open_group()` with `use_consolidated=True`.

zarr.convenience.save(

    _store : zarr.storage.StoreLike_,
    _* args: zarr.core.buffer.NDArrayLike_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _** kwargs: Any_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

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.

zarr.convenience.save_array(

    _store : zarr.storage.StoreLike_,
    _arr : zarr.core.buffer.NDArrayLike_,
    _*_ ,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _** kwargs: Any_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

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 `create()`, e.g., compressor.

zarr.convenience.save_group(

    _store : zarr.storage.StoreLike_,
    _* args: zarr.core.buffer.NDArrayLike_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _** kwargs: zarr.core.buffer.NDArrayLike_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

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.

zarr.convenience.tree(

    _grp : zarr.core.group.Group_,
    _expand : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _level : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> Any#

    

Provide a rich display of the hierarchy.

Deprecated since version 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.

#### zarr.creation#

Helpers for creating arrays.

Warning

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

##### Functions#

`array`(→ zarr.core.array.Array) | Create an array filled with data.  
---|---  
`create`(→ zarr.core.array.Array) | Create an array.  
`empty`(→ zarr.core.array.Array) | Create an empty array with the specified shape. The contents will be filled with the  
`empty_like`(→ zarr.core.array.Array) | Create an empty array like another array. The contents will be filled with the  
`full`(→ zarr.core.array.Array) | Create an array with a default fill value.  
`full_like`(→ zarr.core.array.Array) | Create a filled array like another array.  
`ones`(→ zarr.core.array.Array) | Create an array with a fill value of one.  
`ones_like`(→ zarr.core.array.Array) | Create an array of ones like another array.  
`open_array`(→ zarr.core.array.Array) | Open an array using file-mode-like semantics.  
`open_like`(→ zarr.core.array.Array) | Open a persistent array like another array.  
`zeros`(→ zarr.core.array.Array) | Create an array with a fill value of zero.  
`zeros_like`(→ zarr.core.array.Array) | Create an array of zeros like another array.  
  
##### Module Contents#

zarr.creation.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 `create()`.

Returns:

    

**array** Array

    

The new array.

zarr.creation.create(

    _shape : zarr.core.common.ChunkCoords | [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")_,
    _*_ ,
    _chunks : zarr.core.common.ChunkCoords | [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dtype : zarr.core.dtype.ZDTypeLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _compressor : zarr.core.array.CompressorLike = 'auto'_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = DEFAULT_FILL_VALUE_,
    _order : zarr.core.common.MemoryOrder | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _store : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _synchronizer : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _path : zarr.api.asynchronous.PathLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _filters : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [numcodecs.abc.Codec](https://numcodecs.readthedocs.io/en/stable/abc.html#numcodecs.abc.Codec "\(in numcodecs v0.16.1\)")] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _cache_metadata : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _cache_attrs : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _read_only : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _object_codec : zarr.abc.codec.Codec | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_separator : Literal['.', '/'] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _write_empty_chunks : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _meta_array : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_shape : zarr.core.common.ChunkCoords | [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_key_encoding : zarr.core.chunk_key_encodings.ChunkKeyEncoding | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[Literal['default'], Literal['.', '/']] | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[Literal['v2'], Literal['.', '/']] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _codecs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[zarr.abc.codec.Codec | [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON]] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_names : zarr.core.common.DimensionNames = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _config : zarr.core.array_spec.ArrayConfigLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 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.

**fill_value** object

    

Default value to use for uninitialized portions of 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** Store or str

    

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** MutableMapping, optional

    

Separate storage for chunks. If not provided, store will be used for storage
of both chunks and metadata.

**filters** sequence of Codecs, optional

    

Sequence of filters to use to encode chunk data prior to compression.

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

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

**meta_array** array-like, optional

    

An array instance to use for determining arrays to create and return to users.
Use numpy.empty(()) by default.

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

zarr.creation.empty(

    _shape : zarr.core.common.ChunkCoords_,
    _** 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 `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.

zarr.creation.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 `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.

zarr.creation.full(

    _shape : zarr.core.common.ChunkCoords_,
    _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 `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

zarr.creation.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 `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

zarr.creation.ones(

    _shape : zarr.core.common.ChunkCoords_,
    _** 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 `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

zarr.creation.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 `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

zarr.creation.open_array(

    _store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _*_ ,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : zarr.api.asynchronous.PathLike = ''_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _** kwargs: Any_,
) -> zarr.core.array.Array#

    

Open an array using file-mode-like semantics.

Parameters:

    

**store** Store or str

    

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.

**path** str, optional

    

Path in store to array.

**storage_options** dict

    

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

****kwargs**

    

Any keyword arguments to pass to `create`.

Returns:

    

AsyncArray

    

The opened array.

zarr.creation.open_like(

    _a : zarr.api.asynchronous.ArrayLike_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _** 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.

zarr.creation.zeros(

    _shape : zarr.core.common.ChunkCoords_,
    _** 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 `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

zarr.creation.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 `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

#### zarr.dtype#

##### Attributes#

`data_type_registry` |   
---|---  
  
##### Exceptions#

`DataTypeValidationError` | Inappropriate argument value (of correct type).  
---|---  
  
##### Classes#

`Bool` | A Zarr data type for arrays containing booleans.  
---|---  
`Complex128` | A Zarr data type for arrays containing 64 bit complex floats.  
`Complex64` | A Zarr data type for arrays containing 64 bit complex floats.  
`DateTime64` | A Zarr data type for arrays containing NumPy Datetime64 data.  
`DateTime64JSON_V2` | A wrapper around the JSON representation of the `DateTime64` data type in Zarr V2.  
`DateTime64JSON_V3` | The JSON representation of the `numpy.datetime64` data type in Zarr V3.  
`FixedLengthUTF32` | A Zarr data type for arrays containing fixed-length UTF-32 strings.  
`FixedLengthUTF32JSON_V2` | A wrapper around the JSON representation of the `FixedLengthUTF32` data type in Zarr V2.  
`FixedLengthUTF32JSON_V3` | The JSON representation of the `FixedLengthUTF32` data type in Zarr V3.  
`Float16` | A Zarr data type for arrays containing 16-bit floating point numbers.  
`Float32` | A Zarr data type for arrays containing 32-bit floating point numbers.  
`Float64` | A Zarr data type for arrays containing 64-bit floating point numbers.  
`Int16` | A Zarr data type for arrays containing 16-bit signed integers.  
`Int32` | A Zarr data type for arrays containing 32-bit signed integers.  
`Int64` | A Zarr data type for arrays containing 64-bit signed integers.  
`Int8` | A Zarr data type for arrays containing 8-bit signed integers.  
`NullTerminatedBytes` | A Zarr data type for arrays containing fixed-length null-terminated byte sequences.  
`NullTerminatedBytesJSON_V3` | The JSON representation of the `NullTerminatedBytes` data type in Zarr V3.  
`NullterminatedBytesJSON_V2` | A wrapper around the JSON representation of the `NullTerminatedBytes` data type in Zarr V2.  
`RawBytes` | A Zarr data type for arrays containing fixed-length sequences of raw bytes.  
`RawBytesJSON_V2` | A wrapper around the JSON representation of the `RawBytes` data type in Zarr V2.  
`RawBytesJSON_V3` | The JSON representation of the `RawBytes` data type in Zarr V3.  
`Structured` | A Zarr data type for arrays containing structured scalars, AKA "record arrays".  
`StructuredJSON_V2` | A wrapper around the JSON representation of the `Structured` data type in Zarr V2.  
`StructuredJSON_V3` | A JSON representation of a structured data type in Zarr V3.  
`TimeDelta64` | A Zarr data type for arrays containing NumPy TimeDelta64 data.  
`TimeDelta64JSON_V2` | A wrapper around the JSON representation of the `TimeDelta64` data type in Zarr V2.  
`TimeDelta64JSON_V3` | The JSON representation of the `TimeDelta64` data type in Zarr V3.  
`UInt16` | A Zarr data type for arrays containing 16-bit unsigned integers.  
`UInt32` | A Zarr data type for arrays containing 32-bit unsigned integers.  
`UInt64` | A Zarr data type for arrays containing 64-bit unsigned integers.  
`UInt8` | A Zarr data type for arrays containing 8-bit unsigned integers.  
`VariableLengthBytes` | A Zarr data type for arrays containing variable-length sequences of bytes.  
`VariableLengthBytesJSON_V2` | A wrapper around the JSON representation of the `VariableLengthBytes` data type in Zarr V2.  
`VariableLengthUTF8` | A Zarr data type for arrays containing variable-length UTF-8 strings.  
`VariableLengthUTF8JSON_V2` | A wrapper around the JSON representation of the `VariableLengthUTF8` data type in Zarr V2.  
`ZDType` | Abstract base class for wrapping native array data types, e.g. numpy dtypes  
  
##### Functions#

`parse_dtype`(→ wrapper.ZDType[wrapper.TBaseDType, ...) | Convert the input as a ZDType.  
---|---  
  
##### Module Contents#

_exception _zarr.dtype.DataTypeValidationError#

    

Bases:
[`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError
"\(in Python v3.13\)")

Inappropriate argument value (of correct type).

_class _zarr.dtype.Bool#

    

Bases:
`zarr.core.dtype.wrapper.ZDType`[[`numpy.dtypes.BoolDType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.BoolDType
"\(in NumPy v2.3\)"),
[`numpy.bool_`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.bool_
"\(in NumPy v2.3\)")], `zarr.core.dtype.common.HasItemSize`

A Zarr data type for arrays containing booleans.

Wraps the `np.dtypes.BoolDType` data type. Scalars for this data type are
instances of `np.bool_`.

Attributes:

    

**_zarr_v3_name** Literal[“bool”] = “bool”

    

The Zarr v3 name of the dtype.

**_zarr_v2_name**` Literal["|b1"]` = `"|b1"`

    

The Zarr v2 name of the dtype, which is also a string representation of the
boolean dtype used by NumPy.

**dtype_cls** ClassVar[type[np.dtypes.BoolDType]] = np.dtypes.BoolDType

    

The NumPy dtype class.

References

This class implements the boolean data type defined in Zarr V2 and V3.

See the [Zarr V2](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr
V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-
types/index.rst) specification documents for details.

cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) -> numpy.bool_#

    

Cast the input to a numpy boolean scalar.

Parameters:

    

**data** object

    

The data to cast.

Returns:

    

`np.bool_`

    

The numpy boolean scalar.

Raises:

    

TypeError

    

If the input cannot be converted to a numpy boolean.

default_scalar() -> numpy.bool_#

    

Get the default value for the boolean dtype.

Returns:

    

`np.bool_`

    

The default value.

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> numpy.bool_#

    

Read a JSON-serializable value as a numpy boolean scalar.

Parameters:

    

**data** JSON

    

The JSON-serializable value.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

`np.bool_`

    

The numpy boolean scalar.

Raises:

    

TypeError

    

If the input is not a valid boolean type.

_classmethod _from_native_dtype(_dtype : zarr.core.dtype.wrapper.TBaseDType_)
-> Self#

    

Create an instance of Bool from an instance of np.dtypes.BoolDType.

Parameters:

    

**dtype** TBaseDType

    

The NumPy boolean dtype instance to convert.

Returns:

    

Bool

    

An instance of Bool.

Raises:

    

DataTypeValidationError

    

If the provided dtype is not compatible with this ZDType.

to_json(

    _zarr_format : Literal[2]_,
) -> zarr.core.dtype.common.DTypeConfig_V2[Literal['|b1'],
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

to_json(_zarr_format : Literal[3]_) -> Literal['bool']

    

Serialize this Bool instance to JSON.

Parameters:

    

**zarr_format** ZarrFormat

    

The Zarr format version (2 or 3).

Returns:

    

`DTypeConfig_V2[Literal["|b1"], None] | Literal["bool"]`
    

The JSON representation of the Bool instance.

Raises:

    

ValueError

    

If the zarr_format is not 2 or 3.

to_json_scalar(

    _data : [object](https://docs.python.org/3/library/functions.html#object "\(in Python v3.13\)")_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")#

    

Convert a scalar to a python bool.

Parameters:

    

**data** object

    

The value to convert.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

bool

    

The JSON-serializable format.

to_native_dtype() -> numpy.dtypes.BoolDType#

    

Create a NumPy boolean dtype instance from this ZDType.

Returns:

    

np.dtypes.BoolDType

    

The NumPy boolean dtype.

dtype_cls#

    

_property _item_size _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The size of a single scalar in bytes.

Returns:

    

int

    

The size of a single scalar in bytes.

_class _zarr.dtype.Complex128#

    

Bases:
`BaseComplex`[[`numpy.dtypes.Complex128DType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.Complex128DType
"\(in NumPy v2.3\)"),
[`numpy.complex128`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.complex128
"\(in NumPy v2.3\)")], `zarr.core.dtype.common.HasEndianness`

A Zarr data type for arrays containing 64 bit complex floats.

Wraps the `np.dtypes.Complex128DType` data type. Scalars for this data type
are instances of `np.complex128`.

Attributes:

    

**dtype_cls** Type[np.dtypes.Complex128DType]

    

The numpy dtype class for this data type.

**_zarr_v3_name** ClassVar[Literal[“complex128”]]

    

The name of this data type in Zarr V3.

**_zarr_v2_names** ClassVar[tuple[Literal[“>c16”], Literal[“<c16”]]]

    

The names of this data type in Zarr V2.

cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) -> zarr.core.dtype.npy.common.TComplexScalar_co#

    

Attempt to cast a given object to a numpy complex scalar.

Parameters:

    

**data** object

    

The data to be cast to a numpy complex scalar.

Returns:

    

TComplexScalar_co

    

The data cast as a numpy complex scalar.

Raises:

    

TypeError

    

If the data cannot be converted to a numpy complex scalar.

default_scalar() -> zarr.core.dtype.npy.common.TComplexScalar_co#

    

Get the default value, which is 0 cast to this dtype

Returns:

    

Int scalar

    

The default value.

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> zarr.core.dtype.npy.common.TComplexScalar_co#

    

Read a JSON-serializable value as a numpy float.

Parameters:

    

**data** JSON

    

The JSON-serializable value.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

TScalar_co

    

The numpy float.

_classmethod _from_native_dtype(_dtype : zarr.core.dtype.wrapper.TBaseDType_)
-> Self#

    

Create an instance of this data type from a NumPy complex dtype.

Parameters:

    

**dtype** TBaseDType

    

The native dtype to convert.

Returns:

    

Self

    

An instance of this data type.

Raises:

    

DataTypeValidationError

    

If the dtype is not compatible with this data type.

to_json(

    _zarr_format : Literal[2]_,
) ->
zarr.core.dtype.common.DTypeConfig_V2[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"),
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

to_json(_zarr_format : Literal[3]_) ->
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")

    

Serialize this object to a JSON-serializable representation.

Parameters:

    

**zarr_format** ZarrFormat

    

The Zarr format version. Supported values are 2 and 3.

Returns:

    

DTypeConfig_V2[str, None] | str
    

If `zarr_format` is 2, a dictionary with `"name"` and `"object_codec_id"` keys
is returned. If `zarr_format` is 3, a string representation of the complex
data type is returned.

Raises:

    

ValueError

    

If zarr_format is not 2 or 3.

to_json_scalar(

    _data : [object](https://docs.python.org/3/library/functions.html#object "\(in Python v3.13\)")_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> zarr.core.common.JSON#

    

Convert an object to a JSON-serializable float.

Parameters:

    

**data** _BaseScalar

    

The value to convert.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

JSON

    

The JSON-serializable form of the complex number, which is a list of two
floats, each of which is encoding according to a zarr-format-specific
encoding.

to_native_dtype() -> zarr.core.dtype.npy.common.TComplexDType_co#

    

Convert this class to a NumPy complex dtype with the appropriate byte order.

Returns:

    

TComplexDType_co

    

A NumPy data type object representing the complex data type with the specified
byte order.

dtype_cls#

    

endianness _: EndiannessStr_ _ = 'little'_#

    

_property _item_size _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The size of a single scalar in bytes.

Returns:

    

int

    

The size of a single scalar in bytes.

_class _zarr.dtype.Complex64#

    

Bases:
`BaseComplex`[[`numpy.dtypes.Complex64DType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.Complex64DType
"\(in NumPy v2.3\)"),
[`numpy.complex64`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.complex64
"\(in NumPy v2.3\)")]

A Zarr data type for arrays containing 64 bit complex floats.

Wraps the `np.dtypes.Complex64DType` data type. Scalars for this data type are
instances of `np.complex64`.

Attributes:

    

**dtype_cls** Type[np.dtypes.Complex64DType]

    

The numpy dtype class for this data type.

**_zarr_v3_name** ClassVar[Literal[“complex64”]]

    

The name of this data type in Zarr V3.

**_zarr_v2_names** ClassVar[tuple[Literal[“>c8”], Literal[“<c8”]]]

    

The names of this data type in Zarr V2.

cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) -> zarr.core.dtype.npy.common.TComplexScalar_co#

    

Attempt to cast a given object to a numpy complex scalar.

Parameters:

    

**data** object

    

The data to be cast to a numpy complex scalar.

Returns:

    

TComplexScalar_co

    

The data cast as a numpy complex scalar.

Raises:

    

TypeError

    

If the data cannot be converted to a numpy complex scalar.

default_scalar() -> zarr.core.dtype.npy.common.TComplexScalar_co#

    

Get the default value, which is 0 cast to this dtype

Returns:

    

Int scalar

    

The default value.

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> zarr.core.dtype.npy.common.TComplexScalar_co#

    

Read a JSON-serializable value as a numpy float.

Parameters:

    

**data** JSON

    

The JSON-serializable value.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

TScalar_co

    

The numpy float.

_classmethod _from_native_dtype(_dtype : zarr.core.dtype.wrapper.TBaseDType_)
-> Self#

    

Create an instance of this data type from a NumPy complex dtype.

Parameters:

    

**dtype** TBaseDType

    

The native dtype to convert.

Returns:

    

Self

    

An instance of this data type.

Raises:

    

DataTypeValidationError

    

If the dtype is not compatible with this data type.

to_json(

    _zarr_format : Literal[2]_,
) ->
zarr.core.dtype.common.DTypeConfig_V2[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"),
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

to_json(_zarr_format : Literal[3]_) ->
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")

    

Serialize this object to a JSON-serializable representation.

Parameters:

    

**zarr_format** ZarrFormat

    

The Zarr format version. Supported values are 2 and 3.

Returns:

    

DTypeConfig_V2[str, None] | str
    

If `zarr_format` is 2, a dictionary with `"name"` and `"object_codec_id"` keys
is returned. If `zarr_format` is 3, a string representation of the complex
data type is returned.

Raises:

    

ValueError

    

If zarr_format is not 2 or 3.

to_json_scalar(

    _data : [object](https://docs.python.org/3/library/functions.html#object "\(in Python v3.13\)")_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> zarr.core.common.JSON#

    

Convert an object to a JSON-serializable float.

Parameters:

    

**data** _BaseScalar

    

The value to convert.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

JSON

    

The JSON-serializable form of the complex number, which is a list of two
floats, each of which is encoding according to a zarr-format-specific
encoding.

to_native_dtype() -> zarr.core.dtype.npy.common.TComplexDType_co#

    

Convert this class to a NumPy complex dtype with the appropriate byte order.

Returns:

    

TComplexDType_co

    

A NumPy data type object representing the complex data type with the specified
byte order.

dtype_cls#

    

endianness _: EndiannessStr_ _ = 'little'_#

    

_property _item_size _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The size of a single scalar in bytes.

Returns:

    

int

    

The size of a single scalar in bytes.

_class _zarr.dtype.DateTime64#

    

Bases:
`TimeDTypeBase`[[`numpy.dtypes.DateTime64DType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.DateTime64DType
"\(in NumPy v2.3\)"),
[`numpy.datetime64`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.datetime64
"\(in NumPy v2.3\)")], `zarr.core.dtype.common.HasEndianness`

A Zarr data type for arrays containing NumPy Datetime64 data.

Wraps the `np.dtypes.TimeDelta64DType` data type. Scalars for this data type
are instances of `np.datetime64`.

Attributes:

    

**dtype_cls** Type[np.dtypesTimeDelta64DType]

    

The numpy dtype class for this data type.

**unit** DateTimeUnit

    

The unit of time for this data type.

**scale_factor** int

    

The scale factor for the time unit.

References

The Zarr V2 representation of this data type is defined in the Zarr V2
[specification document](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).

The Zarr V3 representation of this data type is defined in the
`numpy.datetime64` [specification document](https://github.com/zarr-
developers/zarr-extensions/tree/main/data-types/numpy.datetime64)

cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) ->
[numpy.datetime64](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.datetime64
"\(in NumPy v2.3\)")#

    

Cast the input to a scalar of this data type after a type check.

Parameters:

    

**data** object

    

The scalar value to cast.

Returns:

    

numpy.datetime64

    

The input cast to a NumPy datetime scalar.

Raises:

    

TypeError

    

If the data cannot be converted to a numpy datetime scalar.

default_scalar() ->
[numpy.datetime64](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.datetime64
"\(in NumPy v2.3\)")#

    

Return the default scalar value for this data type.

Returns:

    

numpy.datetime64

    

The default scalar value, which is a ‘Not-a-Time’ (NaT) value

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) ->
[numpy.datetime64](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.datetime64
"\(in NumPy v2.3\)")#

    

Read a JSON-serializable value as a scalar.

Parameters:

    

**data** JSON

    

The JSON-serializable value.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

numpy.datetime64

    

The numpy datetime scalar.

Raises:

    

TypeError

    

If the input is not a valid integer type.

_classmethod _from_native_dtype(_dtype : zarr.core.dtype.wrapper.TBaseDType_)
-> Self#

    

Create an instance of this class from a native NumPy data type.

Parameters:

    

**dtype** TBaseDType

    

The native NumPy dtype to convert.

Returns:

    

Self

    

An instance of this data type.

Raises:

    

DataTypeValidationError

    

If the dtype is not a valid representation of this class.

to_json(_zarr_format : Literal[2]_) -> DateTime64JSON_V2#

to_json(_zarr_format : Literal[3]_) -> DateTime64JSON_V3

    

Serialize this data type to JSON.

Parameters:

    

**zarr_format** ZarrFormat

    

The Zarr format version (2 or 3).

Returns:

    

DateTime64JSON_V2 | DateTime64JSON_V3
    

The JSON representation of the data type.

Raises:

    

ValueError

    

If the zarr_format is not 2 or 3.

to_json_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_, _*_ , _zarr_format : zarr.core.common.ZarrFormat_) ->
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Convert a python object to a JSON representation of a datetime64 or
timedelta64 scalar.

Parameters:

    

**data** object

    

The python object to convert.

**zarr_format** ZarrFormat

    

The Zarr format version (2 or 3).

Returns:

    

int

    

The JSON representation of the scalar.

to_native_dtype() -> BaseTimeDType_co#

    

Convert this data type to a NumPy temporal data type with the appropriate unit
and scale factor.

Returns:

    

BaseTimeDType_co

    

A NumPy data type object representing the time data type with the specified
unit, scale factor, and byte order.

dtype_cls#

    

endianness _: EndiannessStr_ _ = 'little'_#

    

_property _item_size _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The size of a single scalar in bytes.

Returns:

    

int

    

The size of a single scalar in bytes.

scale_factor _: [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")_ _ = 1_#

    

unit _: zarr.core.dtype.npy.common.DateTimeUnit_ _ = 'generic'_#

    

_class _zarr.dtype.DateTime64JSON_V2#

    

Bases:
`zarr.core.dtype.common.DTypeConfig_V2`[[`str`](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"),
[`None`](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]

A wrapper around the JSON representation of the `DateTime64` data type in Zarr
V2.

The `name` field of this class contains the value that would appear under the
`dtype` field in Zarr V2 array metadata.

References

The structure of the `name` field is defined in the Zarr V2 [specification
document](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).

Examples

    
    
    {
        "name": "<M8[10s]",
        "object_codec_id": None
    }
    

name _: typing_extensions.ReadOnly[TDTypeNameV2_co]_#

    

object_codec_id _: typing_extensions.ReadOnly[TObjectCodecID_co]_#

    

_class _zarr.dtype.DateTime64JSON_V3#

    

Bases: `zarr.core.common.NamedConfig`[`Literal`[`'numpy.datetime64'`],
`TimeConfig`]

The JSON representation of the `numpy.datetime64` data type in Zarr V3.

References

This representation is defined in the `numpy.datetime64` [specification
document](https://zarr-
specs.readthedocs.io/en/latest/spec/v3/datatypes.html#numpy-datetime64).

Examples

    
    
    {
        "name": "numpy.datetime64",
        "configuration": {
            "unit": "ms",
            "scale_factor": 1
            }
    }
    

_class _zarr.dtype.FixedLengthUTF32#

    

Bases:
`zarr.core.dtype.wrapper.ZDType`[[`numpy.dtypes.StrDType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.StrDType
"\(in NumPy
v2.3\)")[[`int`](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)")],
[`numpy.str_`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.str_
"\(in NumPy v2.3\)")], `zarr.core.dtype.common.HasEndianness`,
`zarr.core.dtype.common.HasLength`, `zarr.core.dtype.common.HasItemSize`

A Zarr data type for arrays containing fixed-length UTF-32 strings.

Wraps the `np.dtypes.StrDType` data type. Scalars for this data type are
instances of `np.str_`.

Attributes:

    

**dtype_cls** Type[np.dtypes.StrDType]

    

The NumPy dtype class for this data type.

**_zarr_v3_name** ClassVar[Literal[“fixed_length_utf32”]]

    

The name of this data type in Zarr V3.

**code_point_bytes** ClassVar[int] = 4

    

The number of bytes per code point in UTF-32, which is 4.

cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) ->
[numpy.str_](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.str_
"\(in NumPy v2.3\)")#

    

Cast the scalar value to the native scalar value.

Parameters:

    

**data** object

    

The scalar value.

Returns:

    

`np.str_`

    

The native scalar value.

default_scalar() ->
[numpy.str_](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.str_
"\(in NumPy v2.3\)")#

    

Return the default scalar value for this data type.

Returns:

    

`np.str_`

    

The default scalar value.

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) ->
[numpy.str_](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.str_
"\(in NumPy v2.3\)")#

    

Convert the JSON representation of a scalar value to the native scalar value.

Parameters:

    

**data** JSON

    

The JSON data.

**zarr_format** ZarrFormat

    

The Zarr format to use.

Returns:

    

`np.str_`

    

The native scalar value.

_classmethod _from_native_dtype(_dtype : zarr.core.dtype.wrapper.TBaseDType_)
-> Self#

    

Create a FixedLengthUTF32 from a NumPy data type.

Parameters:

    

**dtype** TBaseDType

    

The NumPy data type.

Returns:

    

Self

    

An instance of this data type.

to_json(

    _zarr_format : Literal[2]_,
) ->
zarr.core.dtype.common.DTypeConfig_V2[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"),
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

to_json(_zarr_format : Literal[3]_) -> FixedLengthUTF32JSON_V3

    

Convert the FixedLengthUTF32 instance to a JSON representation.

Parameters:

    

**zarr_format** ZarrFormat

    

The Zarr format to use.

Returns:

    

DTypeConfig_V2[str, None] | FixedLengthUTF32JSON_V3
    

The JSON representation of the data type.

to_json_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_, _*_ , _zarr_format : zarr.core.common.ZarrFormat_) ->
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")#

    

Convert the scalar value to a JSON representation.

Parameters:

    

**data** object

    

The scalar value.

**zarr_format** ZarrFormat

    

The Zarr format to use.

Returns:

    

str

    

The JSON representation of the scalar value.

to_native_dtype() ->
numpy.dtypes.StrDType[[int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")]#

    

Convert the FixedLengthUTF32 instance to a NumPy data type.

Returns:

    

np.dtypes.StrDType[int]

    

The NumPy data type.

code_point_bytes _:
ClassVar[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)")]__ = 4_#

    

dtype_cls#

    

endianness _: EndiannessStr_ _ = 'little'_#

    

_property _item_size _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The size of a single scalar in bytes.

Returns:

    

int

    

The size of a single scalar in bytes.

length _: [int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)")_#

    

_class _zarr.dtype.FixedLengthUTF32JSON_V2#

    

Bases:
`zarr.core.dtype.common.DTypeConfig_V2`[[`str`](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"),
[`None`](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]

A wrapper around the JSON representation of the `FixedLengthUTF32` data type
in Zarr V2.

The `name` field of this class contains the value that would appear under the
`dtype` field in Zarr V2 array metadata.

References

The structure of the `name` field is defined in the Zarr V2 [specification
document](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).

Examples

    
    
    {
        "name": "<U12",
        "object_codec_id": None
    }
    

_class _zarr.dtype.FixedLengthUTF32JSON_V3#

    

Bases: `zarr.core.common.NamedConfig`[`Literal`[`'fixed_length_utf32'`],
`LengthBytesConfig`]

The JSON representation of the `FixedLengthUTF32` data type in Zarr V3.

References

This representation is not currently defined in an external specification.

Examples

    
    
    {
        "name": "fixed_length_utf32",
        "configuration": {
            "length_bytes": 12
    }
    

configuration _: typing_extensions.ReadOnly[TConfig]_#

    

The configuration of the object.

name _: typing_extensions.ReadOnly[TName]_#

    

The name of the object.

_class _zarr.dtype.Float16#

    

Bases:
`BaseFloat`[[`numpy.dtypes.Float16DType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.Float16DType
"\(in NumPy v2.3\)"),
[`numpy.float16`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.float16
"\(in NumPy v2.3\)")]

A Zarr data type for arrays containing 16-bit floating point numbers.

Wraps the `np.dtypes.Float16DType` data type. Scalars for this data type are
instances of `np.float16`.

Attributes:

    

**dtype_cls** Type[np.dtypes.Float16DType]

    

The NumPy dtype class for this data type.

References

This class implements the float16 data type defined in Zarr V2 and V3.

See the [Zarr V2](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr
V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-
types/index.rst) specification documents for details.

cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) -> zarr.core.dtype.npy.common.TFloatScalar_co#

    

Cast a scalar value to a NumPy float scalar.

Parameters:

    

**data** object

    

The scalar value to cast.

Returns:

    

TFloatScalar_co

    

The NumPy float scalar.

default_scalar() -> zarr.core.dtype.npy.common.TFloatScalar_co#

    

Get the default value, which is 0 cast to this zdtype.

Returns:

    

TFloatScalar_co

    

The default value.

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> zarr.core.dtype.npy.common.TFloatScalar_co#

    

Read a JSON-serializable value as a NumPy float scalar.

Parameters:

    

**data** JSON

    

The JSON-serializable value.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

TFloatScalar_co

    

The NumPy float scalar.

_classmethod _from_native_dtype(_dtype : zarr.core.dtype.wrapper.TBaseDType_)
-> Self#

    

Create an instance of this ZDType from a NumPy data type.

Parameters:

    

**dtype** TBaseDType

    

The NumPy data type.

Returns:

    

Self

    

An instance of this data type.

to_json(

    _zarr_format : Literal[2]_,
) ->
zarr.core.dtype.common.DTypeConfig_V2[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"),
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

to_json(_zarr_format : Literal[3]_) ->
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")

    

Convert the wrapped data type to a JSON-serializable form.

Parameters:

    

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

DTypeConfig_V2[str, None] or str

    

The JSON-serializable representation of the wrapped data type.

Raises:

    

ValueError

    

If zarr_format is not 2 or 3.

to_json_scalar(

    _data : [object](https://docs.python.org/3/library/functions.html#object "\(in Python v3.13\)")_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> [float](https://docs.python.org/3/library/functions.html#float "\(in Python v3.13\)") | [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")#
    

Convert an object to a JSON-serializable float.

Parameters:

    

**data** _BaseScalar

    

The value to convert.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

JSON

    

The JSON-serializable form of the float, which is potentially a number or a
string. See the zarr specifications for details on the JSON encoding for
floats.

to_native_dtype() -> zarr.core.dtype.npy.common.TFloatDType_co#

    

Convert the wrapped data type to a NumPy data type.

Returns:

    

TFloatDType_co

    

The NumPy data type.

dtype_cls#

    

endianness _: EndiannessStr_ _ = 'little'_#

    

_property _item_size _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The size of a single scalar in bytes.

Returns:

    

int

    

The size of a single scalar in bytes.

_class _zarr.dtype.Float32#

    

Bases:
`BaseFloat`[[`numpy.dtypes.Float32DType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.Float32DType
"\(in NumPy v2.3\)"),
[`numpy.float32`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.float32
"\(in NumPy v2.3\)")]

A Zarr data type for arrays containing 32-bit floating point numbers.

Wraps the `np.dtypes.Float32DType` data type. Scalars for this data type are
instances of `np.float32`.

Attributes:

    

**dtype_cls** Type[np.dtypes.Float32DType]

    

The NumPy dtype class for this data type.

References

This class implements the float32 data type defined in Zarr V2 and V3.

See the [Zarr V2](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr
V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-
types/index.rst) specification documents for details.

cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) -> zarr.core.dtype.npy.common.TFloatScalar_co#

    

Cast a scalar value to a NumPy float scalar.

Parameters:

    

**data** object

    

The scalar value to cast.

Returns:

    

TFloatScalar_co

    

The NumPy float scalar.

default_scalar() -> zarr.core.dtype.npy.common.TFloatScalar_co#

    

Get the default value, which is 0 cast to this zdtype.

Returns:

    

TFloatScalar_co

    

The default value.

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> zarr.core.dtype.npy.common.TFloatScalar_co#

    

Read a JSON-serializable value as a NumPy float scalar.

Parameters:

    

**data** JSON

    

The JSON-serializable value.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

TFloatScalar_co

    

The NumPy float scalar.

_classmethod _from_native_dtype(_dtype : zarr.core.dtype.wrapper.TBaseDType_)
-> Self#

    

Create an instance of this ZDType from a NumPy data type.

Parameters:

    

**dtype** TBaseDType

    

The NumPy data type.

Returns:

    

Self

    

An instance of this data type.

to_json(

    _zarr_format : Literal[2]_,
) ->
zarr.core.dtype.common.DTypeConfig_V2[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"),
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

to_json(_zarr_format : Literal[3]_) ->
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")

    

Convert the wrapped data type to a JSON-serializable form.

Parameters:

    

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

DTypeConfig_V2[str, None] or str

    

The JSON-serializable representation of the wrapped data type.

Raises:

    

ValueError

    

If zarr_format is not 2 or 3.

to_json_scalar(

    _data : [object](https://docs.python.org/3/library/functions.html#object "\(in Python v3.13\)")_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> [float](https://docs.python.org/3/library/functions.html#float "\(in Python v3.13\)") | [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")#
    

Convert an object to a JSON-serializable float.

Parameters:

    

**data** _BaseScalar

    

The value to convert.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

JSON

    

The JSON-serializable form of the float, which is potentially a number or a
string. See the zarr specifications for details on the JSON encoding for
floats.

to_native_dtype() -> zarr.core.dtype.npy.common.TFloatDType_co#

    

Convert the wrapped data type to a NumPy data type.

Returns:

    

TFloatDType_co

    

The NumPy data type.

dtype_cls#

    

endianness _: EndiannessStr_ _ = 'little'_#

    

_property _item_size _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The size of a single scalar in bytes.

Returns:

    

int

    

The size of a single scalar in bytes.

_class _zarr.dtype.Float64#

    

Bases:
`BaseFloat`[[`numpy.dtypes.Float64DType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.Float64DType
"\(in NumPy v2.3\)"),
[`numpy.float64`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.float64
"\(in NumPy v2.3\)")]

A Zarr data type for arrays containing 64-bit floating point numbers.

Wraps the `np.dtypes.Float64DType` data type. Scalars for this data type are
instances of `np.float64`.

Attributes:

    

**dtype_cls** Type[np.dtypes.Float64DType]

    

The NumPy dtype class for this data type.

References

This class implements the float64 data type defined in Zarr V2 and V3.

See the [Zarr V2](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr
V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-
types/index.rst) specification documents for details.

cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) -> zarr.core.dtype.npy.common.TFloatScalar_co#

    

Cast a scalar value to a NumPy float scalar.

Parameters:

    

**data** object

    

The scalar value to cast.

Returns:

    

TFloatScalar_co

    

The NumPy float scalar.

default_scalar() -> zarr.core.dtype.npy.common.TFloatScalar_co#

    

Get the default value, which is 0 cast to this zdtype.

Returns:

    

TFloatScalar_co

    

The default value.

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> zarr.core.dtype.npy.common.TFloatScalar_co#

    

Read a JSON-serializable value as a NumPy float scalar.

Parameters:

    

**data** JSON

    

The JSON-serializable value.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

TFloatScalar_co

    

The NumPy float scalar.

_classmethod _from_native_dtype(_dtype : zarr.core.dtype.wrapper.TBaseDType_)
-> Self#

    

Create an instance of this ZDType from a NumPy data type.

Parameters:

    

**dtype** TBaseDType

    

The NumPy data type.

Returns:

    

Self

    

An instance of this data type.

to_json(

    _zarr_format : Literal[2]_,
) ->
zarr.core.dtype.common.DTypeConfig_V2[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"),
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

to_json(_zarr_format : Literal[3]_) ->
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")

    

Convert the wrapped data type to a JSON-serializable form.

Parameters:

    

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

DTypeConfig_V2[str, None] or str

    

The JSON-serializable representation of the wrapped data type.

Raises:

    

ValueError

    

If zarr_format is not 2 or 3.

to_json_scalar(

    _data : [object](https://docs.python.org/3/library/functions.html#object "\(in Python v3.13\)")_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> [float](https://docs.python.org/3/library/functions.html#float "\(in Python v3.13\)") | [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")#
    

Convert an object to a JSON-serializable float.

Parameters:

    

**data** _BaseScalar

    

The value to convert.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

JSON

    

The JSON-serializable form of the float, which is potentially a number or a
string. See the zarr specifications for details on the JSON encoding for
floats.

to_native_dtype() -> zarr.core.dtype.npy.common.TFloatDType_co#

    

Convert the wrapped data type to a NumPy data type.

Returns:

    

TFloatDType_co

    

The NumPy data type.

dtype_cls#

    

endianness _: EndiannessStr_ _ = 'little'_#

    

_property _item_size _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The size of a single scalar in bytes.

Returns:

    

int

    

The size of a single scalar in bytes.

_class _zarr.dtype.Int16#

    

Bases:
`BaseInt`[[`numpy.dtypes.Int16DType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.Int16DType
"\(in NumPy v2.3\)"),
[`numpy.int16`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.int16
"\(in NumPy v2.3\)")], `zarr.core.dtype.common.HasEndianness`

A Zarr data type for arrays containing 16-bit signed integers.

Wraps the `np.dtypes.Int16DType` data type. Scalars for this data type are
instances of `np.int16`.

Attributes:

    

**dtype_cls** np.dtypes.Int16DType

    

The class of the underlying NumPy dtype.

References

This class implements the 16-bit signed integer data type defined in Zarr V2
and V3.

See the [Zarr V2](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr
V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-
types/index.rst) specification documents for details.

cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) -> TIntScalar_co#

    

Attempt to cast a given object to a NumPy integer scalar.

Parameters:

    

**data** object

    

The data to be cast to a NumPy integer scalar.

Returns:

    

TIntScalar_co

    

The data cast as a NumPy integer scalar.

Raises:

    

TypeError

    

If the data cannot be converted to a NumPy integer scalar.

default_scalar() -> TIntScalar_co#

    

Get the default value, which is 0 cast to this dtype.

Returns:

    

TIntScalar_co

    

The default value.

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> TIntScalar_co#

    

Read a JSON-serializable value as a NumPy int scalar.

Parameters:

    

**data** JSON

    

The JSON-serializable value.

**zarr_format** ZarrFormat

    

The Zarr format version.

Returns:

    

TIntScalar_co

    

The NumPy int scalar.

Raises:

    

TypeError

    

If the input is not a valid integer type.

_classmethod _from_native_dtype(_dtype : zarr.core.dtype.wrapper.TBaseDType_)
-> Self#

    

Create an instance of this data type from a np.dtype(‘int16’) instance.

Parameters:

    

**dtype** np.dtype

    

The instance of np.dtype(‘int16’) to create from.

Returns:

    

Self

    

An instance of this data type.

Raises:

    

DataTypeValidationError

    

If the input data type is not an instance of np.dtype(‘int16’).

to_json(

    _zarr_format : Literal[2]_,
) -> zarr.core.dtype.common.DTypeConfig_V2[Literal['>i2', '<i2'],
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

to_json(_zarr_format : Literal[3]_) -> Literal['int16']

    

Serialize this ZDType to v2- or v3-flavored JSON

Parameters:

    

**zarr_format** ZarrFormat

    

The Zarr format version (2 or 3).

Returns:

    

DTypeConfig_V2[Literal[“>i2”, “<i2”], None] or Literal[“int16”]

    

The JSON representation of the Int16 instance.

Raises:

    

ValueError

    

If the zarr_format is not 2 or 3.

to_json_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_, _*_ , _zarr_format : zarr.core.common.ZarrFormat_) ->
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Convert an object to a JSON serializable scalar. For the integer data types,
the JSON form is a plain integer.

Parameters:

    

**data** object

    

The value to convert.

**zarr_format** ZarrFormat

    

The Zarr format version.

Returns:

    

int

    

The JSON-serializable form of the scalar.

to_native_dtype() -> numpy.dtypes.Int16DType#

    

Convert the data type to a np.dtype(‘int16’) instance.

Returns:

    

np.dtype

    

The np.dtype(‘int16’) instance.

dtype_cls#

    

endianness _: EndiannessStr_ _ = 'little'_#

    

_property _item_size _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The size of a single scalar in bytes.

Returns:

    

int

    

The size of a single scalar in bytes.

_class _zarr.dtype.Int32#

    

Bases:
`BaseInt`[[`numpy.dtypes.Int32DType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.Int32DType
"\(in NumPy v2.3\)"),
[`numpy.int32`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.int32
"\(in NumPy v2.3\)")], `zarr.core.dtype.common.HasEndianness`

A Zarr data type for arrays containing 32-bit signed integers.

Wraps the `np.dtypes.Int32DType` data type. Scalars for this data type are
instances of `np.int32`.

Attributes:

    

**dtype_cls** np.dtypes.Int32DType

    

The class of the underlying NumPy dtype.

References

This class implements the 32-bit signed integer data type defined in Zarr V2
and V3.

See the [Zarr V2](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr
V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-
types/index.rst) specification documents for details.

cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) -> TIntScalar_co#

    

Attempt to cast a given object to a NumPy integer scalar.

Parameters:

    

**data** object

    

The data to be cast to a NumPy integer scalar.

Returns:

    

TIntScalar_co

    

The data cast as a NumPy integer scalar.

Raises:

    

TypeError

    

If the data cannot be converted to a NumPy integer scalar.

default_scalar() -> TIntScalar_co#

    

Get the default value, which is 0 cast to this dtype.

Returns:

    

TIntScalar_co

    

The default value.

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> TIntScalar_co#

    

Read a JSON-serializable value as a NumPy int scalar.

Parameters:

    

**data** JSON

    

The JSON-serializable value.

**zarr_format** ZarrFormat

    

The Zarr format version.

Returns:

    

TIntScalar_co

    

The NumPy int scalar.

Raises:

    

TypeError

    

If the input is not a valid integer type.

_classmethod _from_native_dtype(_dtype : zarr.core.dtype.wrapper.TBaseDType_)
-> Self#

    

Create an Int32 from a np.dtype(‘int32’) instance.

Parameters:

    

**dtype** TBaseDType

    

The np.dtype(‘int32’) instance.

Returns:

    

Self

    

An instance of this data type.

Raises:

    

DataTypeValidationError

    

If the input JSON is not a valid representation of this class Int32.

to_json(

    _zarr_format : Literal[2]_,
) -> zarr.core.dtype.common.DTypeConfig_V2[Literal['>i4', '<i4'],
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

to_json(_zarr_format : Literal[3]_) -> Literal['int32']

    

Serialize this ZDType to v2- or v3-flavored JSON

Parameters:

    

**zarr_format** ZarrFormat

    

The Zarr format version (2 or 3).

Returns:

    

DTypeConfig_V2[Literal[“>i4”, “<i4”], None] or Literal[“int32”]

    

The JSON representation of the Int32 instance.

Raises:

    

ValueError

    

If the zarr_format is not 2 or 3.

to_json_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_, _*_ , _zarr_format : zarr.core.common.ZarrFormat_) ->
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Convert an object to a JSON serializable scalar. For the integer data types,
the JSON form is a plain integer.

Parameters:

    

**data** object

    

The value to convert.

**zarr_format** ZarrFormat

    

The Zarr format version.

Returns:

    

int

    

The JSON-serializable form of the scalar.

to_native_dtype() -> numpy.dtypes.Int32DType#

    

Convert the Int32 instance to a np.dtype(‘int32’) instance.

Returns:

    

np.dtypes.Int32DType

    

The np.dtype(‘int32’) instance.

dtype_cls#

    

endianness _: EndiannessStr_ _ = 'little'_#

    

_property _item_size _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The size of a single scalar in bytes.

Returns:

    

int

    

The size of a single scalar in bytes.

_class _zarr.dtype.Int64#

    

Bases:
`BaseInt`[[`numpy.dtypes.Int64DType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.Int64DType
"\(in NumPy v2.3\)"),
[`numpy.int64`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.int64
"\(in NumPy v2.3\)")], `zarr.core.dtype.common.HasEndianness`

A Zarr data type for arrays containing 64-bit signed integers.

Wraps the `np.dtypes.Int64DType` data type. Scalars for this data type are
instances of `np.int64`.

Attributes:

    

**dtype_cls** np.dtypes.Int64DType

    

The class of the underlying NumPy dtype.

References

This class implements the 64-bit signed integer data type defined in Zarr V2
and V3.

See the [Zarr V2](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr
V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-
types/index.rst) specification documents for details.

cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) -> TIntScalar_co#

    

Attempt to cast a given object to a NumPy integer scalar.

Parameters:

    

**data** object

    

The data to be cast to a NumPy integer scalar.

Returns:

    

TIntScalar_co

    

The data cast as a NumPy integer scalar.

Raises:

    

TypeError

    

If the data cannot be converted to a NumPy integer scalar.

default_scalar() -> TIntScalar_co#

    

Get the default value, which is 0 cast to this dtype.

Returns:

    

TIntScalar_co

    

The default value.

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> TIntScalar_co#

    

Read a JSON-serializable value as a NumPy int scalar.

Parameters:

    

**data** JSON

    

The JSON-serializable value.

**zarr_format** ZarrFormat

    

The Zarr format version.

Returns:

    

TIntScalar_co

    

The NumPy int scalar.

Raises:

    

TypeError

    

If the input is not a valid integer type.

_classmethod _from_native_dtype(_dtype : zarr.core.dtype.wrapper.TBaseDType_)
-> Self#

    

Create an Int64 from a np.dtype(‘int64’) instance.

Parameters:

    

**dtype** TBaseDType

    

The NumPy data type.

Returns:

    

Self

    

An instance of this data type.

Raises:

    

DataTypeValidationError

    

If the input data type is not a valid representation of this class 64-bit
signed integer.

to_json(

    _zarr_format : Literal[2]_,
) -> zarr.core.dtype.common.DTypeConfig_V2[Literal['>i8', '<i8'],
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

to_json(_zarr_format : Literal[3]_) -> Literal['int64']

    

Convert the data type to a JSON-serializable form.

Parameters:

    

**zarr_format** ZarrFormat

    

The Zarr format version.

Returns:

    

DTypeConfig_V2[Literal[“>i8”, “<i8”], None] | Literal[“int64”]
    

The JSON-serializable representation of the data type.

to_json_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_, _*_ , _zarr_format : zarr.core.common.ZarrFormat_) ->
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Convert an object to a JSON serializable scalar. For the integer data types,
the JSON form is a plain integer.

Parameters:

    

**data** object

    

The value to convert.

**zarr_format** ZarrFormat

    

The Zarr format version.

Returns:

    

int

    

The JSON-serializable form of the scalar.

to_native_dtype() -> numpy.dtypes.Int64DType#

    

Create a NumPy signed 64-bit integer dtype instance from this Int64 ZDType.

Returns:

    

np.dtypes.Int64DType

    

The NumPy signed 64-bit integer dtype.

dtype_cls#

    

endianness _: EndiannessStr_ _ = 'little'_#

    

_property _item_size _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The size of a single scalar in bytes.

Returns:

    

int

    

The size of a single scalar in bytes.

_class _zarr.dtype.Int8#

    

Bases:
`BaseInt`[[`numpy.dtypes.Int8DType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.Int8DType
"\(in NumPy v2.3\)"),
[`numpy.int8`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.int8
"\(in NumPy v2.3\)")]

A Zarr data type for arrays containing 8-bit signed integers.

Wraps the `np.dtypes.Int8DType` data type. Scalars for this data type are
instances of `np.int8`.

Attributes:

    

**dtype_cls** np.dtypes.Int8DType

    

The class of the underlying NumPy dtype.

References

This class implements the 8-bit signed integer data type defined in Zarr V2
and V3.

See the [Zarr V2](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr
V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-
types/index.rst) specification documents for details.

cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) -> TIntScalar_co#

    

Attempt to cast a given object to a NumPy integer scalar.

Parameters:

    

**data** object

    

The data to be cast to a NumPy integer scalar.

Returns:

    

TIntScalar_co

    

The data cast as a NumPy integer scalar.

Raises:

    

TypeError

    

If the data cannot be converted to a NumPy integer scalar.

default_scalar() -> TIntScalar_co#

    

Get the default value, which is 0 cast to this dtype.

Returns:

    

TIntScalar_co

    

The default value.

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> TIntScalar_co#

    

Read a JSON-serializable value as a NumPy int scalar.

Parameters:

    

**data** JSON

    

The JSON-serializable value.

**zarr_format** ZarrFormat

    

The Zarr format version.

Returns:

    

TIntScalar_co

    

The NumPy int scalar.

Raises:

    

TypeError

    

If the input is not a valid integer type.

_classmethod _from_native_dtype(_dtype : zarr.core.dtype.wrapper.TBaseDType_)
-> Self#

    

Create an Int8 from a np.dtype(‘int8’) instance.

Parameters:

    

**dtype** TBaseDType

    

The np.dtype(‘int8’) instance.

Returns:

    

Self

    

An instance of this data type.

Raises:

    

DataTypeValidationError

    

If the input data type is not a valid representation of this class Int8.

to_json(

    _zarr_format : Literal[2]_,
) -> zarr.core.dtype.common.DTypeConfig_V2[Literal['|i1'],
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

to_json(_zarr_format : Literal[3]_) -> Literal['int8']

    

Convert the data type to a JSON-serializable form.

Parameters:

    

**zarr_format** ZarrFormat

    

The Zarr format version.

Returns:

    

`DTypeConfig_V2[Literal["|i1"], None] | Literal["int8"]`
    

The JSON-serializable representation of the data type.

Raises:

    

ValueError

    

If the zarr_format is not 2 or 3.

to_json_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_, _*_ , _zarr_format : zarr.core.common.ZarrFormat_) ->
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Convert an object to a JSON serializable scalar. For the integer data types,
the JSON form is a plain integer.

Parameters:

    

**data** object

    

The value to convert.

**zarr_format** ZarrFormat

    

The Zarr format version.

Returns:

    

int

    

The JSON-serializable form of the scalar.

to_native_dtype() -> numpy.dtypes.Int8DType#

    

Convert the Int8 instance to a np.dtype(‘int8’) instance.

Returns:

    

np.dtypes.Int8DType

    

The np.dtype(‘int8’) instance.

dtype_cls#

    

_property _item_size _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The size of a single scalar in bytes.

Returns:

    

int

    

The size of a single scalar in bytes.

_class _zarr.dtype.NullTerminatedBytes#

    

Bases:
`zarr.core.dtype.wrapper.ZDType`[[`numpy.dtypes.BytesDType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.BytesDType
"\(in NumPy
v2.3\)")[[`int`](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)")],
[`numpy.bytes_`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.bytes_
"\(in NumPy v2.3\)")], `zarr.core.dtype.common.HasLength`,
`zarr.core.dtype.common.HasItemSize`

A Zarr data type for arrays containing fixed-length null-terminated byte
sequences.

Wraps the `np.dtypes.BytesDType` data type. Scalars for this data type are
instances of `np.bytes_`.

This data type is parametrized by an integral length which specifies size in
bytes of each scalar. Because this data type uses null-terminated semantics,
indexing into NumPy arrays with this data type may return fewer than `length`
bytes.

Attributes:

    

**dtype_cls: ClassVar[type[np.dtypes.BytesDType[int]]] =
np.dtypes.BytesDType**

    

The NumPy data type wrapped by this ZDType.

**_zarr_v3_name** ClassVar[Literal[“null_terminated_bytes”]]

    
**length** int

    

The length of the bytes.

Notes

This data type is designed for compatibility with NumPy arrays that use the
NumPy `bytes` data type. It may not be desirable for usage outside of that
context. If compatibility with the NumPy `bytes` data type is not essential,
consider using the `RawBytes` or `VariableLengthBytes` data types instead.

cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) ->
[numpy.bytes_](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.bytes_
"\(in NumPy v2.3\)")#

    

Attempt to cast a given object to a NumPy bytes scalar.

This method first checks if the provided data is a valid scalar that can be
converted to a NumPy bytes scalar. If the check succeeds, the unchecked
casting operation is performed. If the data is not valid, a TypeError is
raised.

Parameters:

    

**data** object

    

The data to be cast to a NumPy bytes scalar.

Returns:

    

`np.bytes_`

    

The data cast as a NumPy bytes scalar.

Raises:

    

TypeError

    

If the data cannot be converted to a NumPy bytes scalar.

default_scalar() ->
[numpy.bytes_](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.bytes_
"\(in NumPy v2.3\)")#

    

Return a default scalar value, which for this data type is an empty byte
string.

Returns:

    

`np.bytes_`

    

The default scalar value.

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) ->
[numpy.bytes_](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.bytes_
"\(in NumPy v2.3\)")#

    

Read a JSON-serializable value as `np.bytes_`.

Parameters:

    

**data** JSON

    

The JSON-serializable base64-encoded string.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

`np.bytes_`

    

The NumPy bytes scalar obtained from decoding the base64 string.

Raises:

    

TypeError

    

If the input data is not a base64-encoded string.

_classmethod _from_native_dtype(_dtype : zarr.core.dtype.wrapper.TBaseDType_)
-> Self#

    

Create an instance of NullTerminatedBytes from an instance of
np.dtypes.BytesDType.

This method checks if the provided data type is an instance of
np.dtypes.BytesDType. If so, it returns a new instance of NullTerminatedBytes
with a length equal to the length of input data type.

Parameters:

    

**dtype** TBaseDType

    

The native dtype to convert.

Returns:

    

NullTerminatedBytes

    

An instance of NullTerminatedBytes with the specified length.

Raises:

    

DataTypeValidationError

    

If the dtype is not compatible with NullTerminatedBytes.

to_json(_zarr_format : Literal[2]_) -> NullterminatedBytesJSON_V2#

to_json(_zarr_format : Literal[3]_) -> NullTerminatedBytesJSON_V3

    

Generate a JSON representation of this data type.

Parameters:

    

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

NullterminatedBytesJSON_V2 | NullTerminatedBytesJSON_V3
    

The JSON-serializable representation of the data type

to_json_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_, _*_ , _zarr_format : zarr.core.common.ZarrFormat_) ->
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")#

    

Convert a scalar to a JSON-serializable string representation.

This method encodes the given scalar as a NumPy bytes scalar and then encodes
the bytes as a base64-encoded string.

Parameters:

    

**data** object

    

The scalar to convert.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

str

    

A string representation of the scalar.

to_native_dtype() ->
numpy.dtypes.BytesDType[[int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")]#

    

Create a NumPy bytes dtype from this NullTerminatedBytes ZDType.

Returns:

    

np.dtypes.BytesDType[int]

    

A NumPy data type object representing null-terminated bytes with a specified
length.

dtype_cls#

    

_property _item_size _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The size of a single scalar in bytes.

Returns:

    

int

    

The size of a single scalar in bytes.

length _: [int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)")_#

    

_class _zarr.dtype.NullTerminatedBytesJSON_V3#

    

Bases: `zarr.core.common.NamedConfig`[`Literal`[`'null_terminated_bytes'`],
`FixedLengthBytesConfig`]

The JSON representation of the `NullTerminatedBytes` data type in Zarr V3.

References

This representation is not currently defined in an external specification.

Examples

    
    
    {
        "name": "null_terminated_bytes",
        "configuration": {
            "length_bytes": 12
        }
    }
    

_class _zarr.dtype.NullterminatedBytesJSON_V2#

    

Bases:
`zarr.core.dtype.common.DTypeConfig_V2`[[`str`](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"),
[`None`](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]

A wrapper around the JSON representation of the `NullTerminatedBytes` data
type in Zarr V2.

The `name` field of this class contains the value that would appear under the
`dtype` field in Zarr V2 array metadata.

References

The structure of the `name` field is defined in the Zarr V2 [specification
document](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).

Examples

    
    
    {
        "name": "|S10",
        "object_codec_id": None
    }
    

_class _zarr.dtype.RawBytes#

    

Bases:
`zarr.core.dtype.wrapper.ZDType`[[`numpy.dtypes.VoidDType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.VoidDType
"\(in NumPy
v2.3\)")[[`int`](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)")],
[`numpy.void`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.void
"\(in NumPy v2.3\)")], `zarr.core.dtype.common.HasLength`,
`zarr.core.dtype.common.HasItemSize`

A Zarr data type for arrays containing fixed-length sequences of raw bytes.

Wraps the NumPy `void` data type. Scalars for this data type are instances of
`np.void`.

This data type is parametrized by an integral length which specifies size in
bytes of each scalar belonging to this data type.

Attributes:

    

**dtype_cls: ClassVar[type[np.dtypes.VoidDType[int]]] = np.dtypes.VoidDtype**

    

The NumPy data type wrapped by this ZDType.

**_zarr_v3_name** ClassVar[Literal[“raw_bytes”]]

    
**length** int

    

The length of the bytes.

Notes

Although the NumPy “Void” data type is used to create “structured” data types
in NumPy, this class does not support structured data types.

See the `Structured` data type for this functionality.

cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) ->
[numpy.void](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.void
"\(in NumPy v2.3\)")#

    

Attempt to cast a given object to a NumPy void scalar.

This method first checks if the provided data is a valid scalar that can be
converted to a NumPy void scalar. If the check succeeds, the unchecked casting
operation is performed. If the data is not valid, a TypeError is raised.

Parameters:

    

**data** object

    

The data to be cast to a NumPy void scalar.

Returns:

    

np.void

    

The data cast as a NumPy void scalar.

Raises:

    

TypeError

    

If the data cannot be converted to a NumPy void scalar.

default_scalar() ->
[numpy.void](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.void
"\(in NumPy v2.3\)")#

    

Return the default scalar value for this data type.

The default scalar is a NumPy void scalar of the same length as the data type,
filled with zero bytes.

Returns:

    

np.void

    

The default scalar value.

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) ->
[numpy.void](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.void
"\(in NumPy v2.3\)")#

    

Read a JSON-serializable value as a np.void.

Parameters:

    

**data** JSON

    

The JSON-serializable value.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

np.void

    

The NumPy void scalar.

Raises:

    

TypeError

    

If the data is not a string, or if the string is not a valid base64 encoding.

_classmethod _from_native_dtype(_dtype : zarr.core.dtype.wrapper.TBaseDType_)
-> Self#

    

Create an instance of RawBytes from an instance of np.dtypes.VoidDType.

This method checks if the provided data type is compatible with RawBytes. The
input must be an instance of np.dtypes.VoidDType, and have no fields. If the
input is compatible, this method returns an instance of RawBytes with the
specified length.

Parameters:

    

**dtype** TBaseDType

    

The native dtype to convert.

Returns:

    

RawBytes

    

An instance of RawBytes with the specified length.

Raises:

    

DataTypeValidationError

    

If the dtype is not compatible with RawBytes.

to_json(_zarr_format : Literal[2]_) -> RawBytesJSON_V2#

to_json(_zarr_format : Literal[3]_) -> RawBytesJSON_V3

    

Generate a JSON representation of this data type.

Parameters:

    

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

RawBytesJSON_V2 | RawBytesJSON_V3
    

The JSON-serializable representation of the data type.

to_json_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_, _*_ , _zarr_format : zarr.core.common.ZarrFormat_) ->
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")#

    

Convert a scalar to a JSON-serializable string representation.

This method converts the given scalar to bytes and then encodes the bytes as a
base64-encoded string.

Parameters:

    

**data** object

    

The scalar to convert.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

str

    

A string representation of the scalar.

to_native_dtype() ->
numpy.dtypes.VoidDType[[int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")]#

    

Create a NumPy void dtype from this RawBytes ZDType.

Returns:

    

np.dtypes.VoidDType[int]

    

A NumPy data type object representing raw bytes with a specified length.

dtype_cls#

    

_property _item_size _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The size of a single scalar in bytes.

Returns:

    

int

    

The size of a single scalar in bytes.

length _: [int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)")_#

    

_class _zarr.dtype.RawBytesJSON_V2#

    

Bases:
`zarr.core.dtype.common.DTypeConfig_V2`[[`str`](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"),
[`None`](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]

A wrapper around the JSON representation of the `RawBytes` data type in Zarr
V2.

The `name` field of this class contains the value that would appear under the
`dtype` field in Zarr V2 array metadata.

References

The structure of the `name` field is defined in the Zarr V2 [specification
document](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).

Examples

    
    
    {
        "name": "|V10",
        "object_codec_id": None
    }
    

name _: typing_extensions.ReadOnly[TDTypeNameV2_co]_#

    

object_codec_id _: typing_extensions.ReadOnly[TObjectCodecID_co]_#

    

_class _zarr.dtype.RawBytesJSON_V3#

    

Bases: `zarr.core.common.NamedConfig`[`Literal`[`'raw_bytes'`],
`FixedLengthBytesConfig`]

The JSON representation of the `RawBytes` data type in Zarr V3.

References

This representation is not currently defined in an external specification.

Examples

    
    
    {
        "name": "raw_bytes",
        "configuration": {
            "length_bytes": 12
    

configuration _: typing_extensions.ReadOnly[TConfig]_#

    

The configuration of the object.

name _: typing_extensions.ReadOnly[TName]_#

    

The name of the object.

_class _zarr.dtype.Structured#

    

Bases:
`zarr.core.dtype.wrapper.ZDType`[[`numpy.dtypes.VoidDType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.VoidDType
"\(in NumPy
v2.3\)")[[`int`](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)")],
[`numpy.void`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.void
"\(in NumPy v2.3\)")], `zarr.core.dtype.common.HasItemSize`

A Zarr data type for arrays containing structured scalars, AKA “record
arrays”.

Wraps the NumPy np.dtypes.VoidDType if the data type has fields. Scalars for
this data type are instances of np.void, with a `fields` attribute.

Attributes:

    

**fields** Sequence[tuple[str, ZDType]]

    

The fields of the structured dtype.

References

This data type does not have a Zarr V3 specification.

The Zarr V2 data type specification can be found
[here](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).

cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) ->
[numpy.void](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.void
"\(in NumPy v2.3\)")#

    

Cast a Python object to a NumPy structured scalar.

This function attempts to cast the provided data to a NumPy structured scalar.
If the data is compatible with the structured scalar type, it is cast without
type checking. Otherwise, a TypeError is raised.

Parameters:

    

**data** object

    

The data to be cast to a NumPy structured scalar.

Returns:

    

np.void

    

The data cast as a NumPy structured scalar.

Raises:

    

TypeError

    

If the data cannot be converted to a NumPy structured scalar.

default_scalar() ->
[numpy.void](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.void
"\(in NumPy v2.3\)")#

    

Get the default scalar value for this structured data type.

Returns:

    

np.void

    

The default scalar value, which is the scalar representation of 0 cast to this
structured data type.

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) ->
[numpy.void](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.void
"\(in NumPy v2.3\)")#

    

Read a JSON-serializable value as a NumPy structured scalar.

Parameters:

    

**data** JSON

    

The JSON-serializable value.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

np.void

    

The NumPy structured scalar.

Raises:

    

TypeError

    

If the input is not a base64-encoded string.

_classmethod _from_native_dtype(_dtype : zarr.core.dtype.wrapper.TBaseDType_)
-> Self#

    

Create a Structured ZDType from a native NumPy data type.

Parameters:

    

**dtype** TBaseDType

    

The native data type.

Returns:

    

Self

    

An instance of this data type.

Raises:

    

DataTypeValidationError

    

If the input data type is not an instance of np.dtypes.VoidDType with a non-
null `fields` attribute.

Notes

This method attempts to resolve the fields of the structured dtype using the
data type registry.

to_json(_zarr_format : Literal[2]_) -> StructuredJSON_V2#

to_json(_zarr_format : Literal[3]_) -> StructuredJSON_V3

    

Convert the structured data type to a JSON-serializable form.

Parameters:

    

**zarr_format** ZarrFormat

    

The Zarr format version. Accepted values are 2 and 3.

Returns:

    

StructuredJSON_V2 | StructuredJSON_V3
    

The JSON representation of the structured data type.

Raises:

    

ValueError

    

If the zarr_format is not 2 or 3.

to_json_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_, _*_ , _zarr_format : zarr.core.common.ZarrFormat_) ->
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")#

    

Convert a scalar to a JSON-serializable string representation.

Parameters:

    

**data** object

    

The scalar to convert.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

str

    

A string representation of the scalar, which is a base64-encoded string of the
bytes that make up the scalar.

to_native_dtype() ->
numpy.dtypes.VoidDType[[int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")]#

    

Convert the structured Zarr data type to a native NumPy void dtype.

This method constructs a NumPy dtype with fields corresponding to the fields
of the structured Zarr data type, by converting each field’s data type to its
native dtype representation.

Returns:

    

np.dtypes.VoidDType[int]

    

The native NumPy void dtype representing the structured data type.

dtype_cls#

    

fields _: [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in
Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"),
zarr.core.dtype.wrapper.ZDType[zarr.core.dtype.wrapper.TBaseDType,
zarr.core.dtype.wrapper.TBaseScalar]], Ellipsis]_#

    

_property _item_size _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The size of a single scalar in bytes.

Returns:

    

int

    

The size of a single scalar in bytes.

_class _zarr.dtype.StructuredJSON_V2#

    

Bases:
`zarr.core.dtype.common.DTypeConfig_V2`[`zarr.core.dtype.common.StructuredName_V2`,
[`None`](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]

A wrapper around the JSON representation of the `Structured` data type in Zarr
V2.

The `name` field is a sequence of sequences, where each inner sequence has two
values: the field name and the data type name for that field (which could be
another sequence). The data type names are strings, and the object codec ID is
always None.

References

The structure of the `name` field is defined in the Zarr V2 [specification
document](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).

Examples

    
    
    {
        "name": [
            ["f0", "<m8[10s]"],
            ["f1", "<m8[10s]"],
        ],
        "object_codec_id": None
    }
    

_class _zarr.dtype.StructuredJSON_V3#

    

Bases: `zarr.core.common.NamedConfig`[`Literal`[`'structured'`], [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[`str`](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), [`collections.abc.Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "\(in Python v3.13\)")[[`collections.abc.Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "\(in Python v3.13\)")[`str | zarr.core.dtype.common.DTypeJSON`]]]]

A JSON representation of a structured data type in Zarr V3.

References

This representation is not currently defined in an external specification.

Examples

    
    
    {
        "name": "structured",
        "configuration": {
            "fields": [
                ["f0", "int32],
                ["f1", "float64"],
            ]
        }
    }
    

_class _zarr.dtype.TimeDelta64#

    

Bases:
`TimeDTypeBase`[[`numpy.dtypes.TimeDelta64DType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.TimeDelta64DType
"\(in NumPy v2.3\)"),
[`numpy.timedelta64`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.timedelta64
"\(in NumPy v2.3\)")], `zarr.core.dtype.common.HasEndianness`

A Zarr data type for arrays containing NumPy TimeDelta64 data.

Wraps the `np.dtypesTimeDelta64DType` data type. Scalars for this data type
are instances of np.timedelta64.

Attributes:

    

**dtype_cls** Type[np.dtypesTimeDelta64DType]

    

The NumPy dtype class for this data type.

**scale_factor** int

    

The scale factor for this data type.

**unit** DateTimeUnit

    

The unit for this data type.

References

The Zarr V2 representation of this data type is defined in the Zarr V2
[specification document](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).

The Zarr V3 representation of this data type is defined in the
`numpy.timedelta64` [specification document](https://github.com/zarr-
developers/zarr-extensions/tree/main/data-types/numpy.timedelta64)

cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) ->
[numpy.timedelta64](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.timedelta64
"\(in NumPy v2.3\)")#

    

Cast the input to a numpy timedelta64 scalar. If the input is not a scalar of
this data type, raise a TypeError.

default_scalar() ->
[numpy.timedelta64](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.timedelta64
"\(in NumPy v2.3\)")#

    

Return a default scalar of this data type.

This method provides a default value for the timedelta64 scalar, which is a
‘Not-a-Time’ (NaT) value.

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) ->
[numpy.timedelta64](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.timedelta64
"\(in NumPy v2.3\)")#

    

Create a scalar of this data type from JSON input.

Parameters:

    

**data** JSON

    

The JSON representation of the scalar value.

**zarr_format** int

    

The zarr format to use for the JSON representation.

Returns:

    

numpy.timedelta64

    

The scalar value of this data type.

Raises:

    

TypeError

    

If the input JSON is not a valid representation of a scalar for this data
type.

_classmethod _from_native_dtype(_dtype : zarr.core.dtype.wrapper.TBaseDType_)
-> Self#

    

Create an instance of this class from a native NumPy data type.

Parameters:

    

**dtype** TBaseDType

    

The native NumPy dtype to convert.

Returns:

    

Self

    

An instance of this data type.

Raises:

    

DataTypeValidationError

    

If the dtype is not a valid representation of this class.

to_json(_zarr_format : Literal[2]_) -> TimeDelta64JSON_V2#

to_json(_zarr_format : Literal[3]_) -> TimeDelta64JSON_V3

    

Serialize this data type to JSON.

Parameters:

    

**zarr_format** ZarrFormat

    

The Zarr format version (2 or 3).

Returns:

    

TimeDelta64JSON_V2 | TimeDelta64JSON_V3
    

The JSON representation of the data type.

Raises:

    

ValueError

    

If the zarr_format is not 2 or 3.

to_json_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_, _*_ , _zarr_format : zarr.core.common.ZarrFormat_) ->
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Convert a python object to a JSON representation of a datetime64 or
timedelta64 scalar.

Parameters:

    

**data** object

    

The python object to convert.

**zarr_format** ZarrFormat

    

The Zarr format version (2 or 3).

Returns:

    

int

    

The JSON representation of the scalar.

to_native_dtype() -> BaseTimeDType_co#

    

Convert this data type to a NumPy temporal data type with the appropriate unit
and scale factor.

Returns:

    

BaseTimeDType_co

    

A NumPy data type object representing the time data type with the specified
unit, scale factor, and byte order.

dtype_cls#

    

endianness _: EndiannessStr_ _ = 'little'_#

    

_property _item_size _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The size of a single scalar in bytes.

Returns:

    

int

    

The size of a single scalar in bytes.

scale_factor _: [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")_ _ = 1_#

    

unit _: zarr.core.dtype.npy.common.DateTimeUnit_ _ = 'generic'_#

    

_class _zarr.dtype.TimeDelta64JSON_V2#

    

Bases:
`zarr.core.dtype.common.DTypeConfig_V2`[[`str`](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"),
[`None`](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]

A wrapper around the JSON representation of the `TimeDelta64` data type in
Zarr V2.

The `name` field of this class contains the value that would appear under the
`dtype` field in Zarr V2 array metadata.

References

The structure of the `name` field is defined in the Zarr V2 [specification
document](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).

Examples

    
    
    {
        "name": "<m8[1s]",
        "object_codec_id": None
    }
    

_class _zarr.dtype.TimeDelta64JSON_V3#

    

Bases: `zarr.core.common.NamedConfig`[`Literal`[`'numpy.timedelta64'`],
`TimeConfig`]

The JSON representation of the `TimeDelta64` data type in Zarr V3.

References

This representation is defined in the numpy.timedelta64 [specification
document](https://zarr-
specs.readthedocs.io/en/latest/spec/v3/datatypes.html#numpy-timedelta64).

Examples

    
    
    {
        "name": "numpy.timedelta64",
        "configuration": {
            "unit": "ms",
            "scale_factor": 1
            }
    }
    

configuration _: typing_extensions.ReadOnly[TConfig]_#

    

The configuration of the object.

name _: typing_extensions.ReadOnly[TName]_#

    

The name of the object.

_class _zarr.dtype.UInt16#

    

Bases:
`BaseInt`[[`numpy.dtypes.UInt16DType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.UInt16DType
"\(in NumPy v2.3\)"),
[`numpy.uint16`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.uint16
"\(in NumPy v2.3\)")], `zarr.core.dtype.common.HasEndianness`

A Zarr data type for arrays containing 16-bit unsigned integers.

Wraps the `np.dtypes.UInt16DType` data type. Scalars for this data type are
instances of `np.uint16`.

Attributes:

    

**dtype_cls** np.dtypes.UInt16DType

    

The class of the underlying NumPy dtype.

References

This class implements the unsigned 16-bit unsigned integer data type defined
in Zarr V2 and V3.

See the [Zarr V2](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr
V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-
types/index.rst) specification documents for details.

cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) -> TIntScalar_co#

    

Attempt to cast a given object to a NumPy integer scalar.

Parameters:

    

**data** object

    

The data to be cast to a NumPy integer scalar.

Returns:

    

TIntScalar_co

    

The data cast as a NumPy integer scalar.

Raises:

    

TypeError

    

If the data cannot be converted to a NumPy integer scalar.

default_scalar() -> TIntScalar_co#

    

Get the default value, which is 0 cast to this dtype.

Returns:

    

TIntScalar_co

    

The default value.

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> TIntScalar_co#

    

Read a JSON-serializable value as a NumPy int scalar.

Parameters:

    

**data** JSON

    

The JSON-serializable value.

**zarr_format** ZarrFormat

    

The Zarr format version.

Returns:

    

TIntScalar_co

    

The NumPy int scalar.

Raises:

    

TypeError

    

If the input is not a valid integer type.

_classmethod _from_native_dtype(_dtype : zarr.core.dtype.wrapper.TBaseDType_)
-> Self#

    

Create an instance of this data type from a np.dtype(‘uint16’) instance.

Parameters:

    

**dtype** np.dtype

    

The NumPy data type.

Returns:

    

Self

    

An instance of this data type.

Raises:

    

DataTypeValidationError

    

If the input data type is not an instance of np.dtype(‘uint16’).

to_json(

    _zarr_format : Literal[2]_,
) -> zarr.core.dtype.common.DTypeConfig_V2[Literal['>u2', '<u2'],
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

to_json(_zarr_format : Literal[3]_) -> Literal['uint16']

    

Serialize this ZDType to v2- or v3-flavored JSON

Parameters:

    

**zarr_format** ZarrFormat

    

The Zarr format version (2 or 3).

Returns:

    

DTypeConfig_V2[Literal[“>u2”, “<u2”], None] or Literal[“uint16”]

    

The JSON representation of the UInt16 instance.

Raises:

    

ValueError

    

If the zarr_format is not 2 or 3.

to_json_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_, _*_ , _zarr_format : zarr.core.common.ZarrFormat_) ->
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Convert an object to a JSON serializable scalar. For the integer data types,
the JSON form is a plain integer.

Parameters:

    

**data** object

    

The value to convert.

**zarr_format** ZarrFormat

    

The Zarr format version.

Returns:

    

int

    

The JSON-serializable form of the scalar.

to_native_dtype() -> numpy.dtypes.UInt16DType#

    

Convert the data type to a np.dtype(‘uint16’) instance.

Returns:

    

np.dtype

    

The np.dtype(‘uint16’) instance.

dtype_cls#

    

endianness _: EndiannessStr_ _ = 'little'_#

    

_property _item_size _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The size of a single scalar in bytes.

Returns:

    

int

    

The size of a single scalar in bytes.

_class _zarr.dtype.UInt32#

    

Bases:
`BaseInt`[[`numpy.dtypes.UInt32DType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.UInt32DType
"\(in NumPy v2.3\)"),
[`numpy.uint32`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.uint32
"\(in NumPy v2.3\)")], `zarr.core.dtype.common.HasEndianness`

A Zarr data type for arrays containing 32-bit unsigned integers.

Wraps the `np.dtypes.UInt32DType` data type. Scalars for this data type are
instances of `np.uint32`.

Attributes:

    

**dtype_cls** np.dtypes.UInt32DType

    

The class of the underlying NumPy dtype.

References

This class implements the 32-bit unsigned integer data type defined in Zarr V2
and V3.

See the [Zarr V2](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr
V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-
types/index.rst) specification documents for details.

cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) -> TIntScalar_co#

    

Attempt to cast a given object to a NumPy integer scalar.

Parameters:

    

**data** object

    

The data to be cast to a NumPy integer scalar.

Returns:

    

TIntScalar_co

    

The data cast as a NumPy integer scalar.

Raises:

    

TypeError

    

If the data cannot be converted to a NumPy integer scalar.

default_scalar() -> TIntScalar_co#

    

Get the default value, which is 0 cast to this dtype.

Returns:

    

TIntScalar_co

    

The default value.

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> TIntScalar_co#

    

Read a JSON-serializable value as a NumPy int scalar.

Parameters:

    

**data** JSON

    

The JSON-serializable value.

**zarr_format** ZarrFormat

    

The Zarr format version.

Returns:

    

TIntScalar_co

    

The NumPy int scalar.

Raises:

    

TypeError

    

If the input is not a valid integer type.

_classmethod _from_native_dtype(_dtype : zarr.core.dtype.wrapper.TBaseDType_)
-> Self#

    

Create a UInt32 from a np.dtype(‘uint32’) instance.

Parameters:

    

**dtype** TBaseDType

    

The NumPy data type.

Returns:

    

Self

    

An instance of this data type.

Raises:

    

DataTypeValidationError

    

If the input data type is not a valid representation of this class 32-bit
unsigned integer.

to_json(

    _zarr_format : Literal[2]_,
) -> zarr.core.dtype.common.DTypeConfig_V2[Literal['>u4', '<u4'],
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

to_json(_zarr_format : Literal[3]_) -> Literal['uint32']

    

Convert the data type to a JSON-serializable form.

Parameters:

    

**zarr_format** ZarrFormat

    

The Zarr format version.

Returns:

    

DTypeConfig_V2[Literal[“>u4”, “<u4”], None] | Literal[“uint32”]
    

The JSON-serializable representation of the data type

to_json_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_, _*_ , _zarr_format : zarr.core.common.ZarrFormat_) ->
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Convert an object to a JSON serializable scalar. For the integer data types,
the JSON form is a plain integer.

Parameters:

    

**data** object

    

The value to convert.

**zarr_format** ZarrFormat

    

The Zarr format version.

Returns:

    

int

    

The JSON-serializable form of the scalar.

to_native_dtype() -> numpy.dtypes.UInt32DType#

    

Create a NumPy unsigned 32-bit integer dtype instance from this UInt32 ZDType.

Returns:

    

np.dtypes.UInt32DType

    

The NumPy unsigned 32-bit integer dtype.

dtype_cls#

    

endianness _: EndiannessStr_ _ = 'little'_#

    

_property _item_size _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The size of a single scalar in bytes.

Returns:

    

int

    

The size of a single scalar in bytes.

_class _zarr.dtype.UInt64#

    

Bases:
`BaseInt`[[`numpy.dtypes.UInt64DType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.UInt64DType
"\(in NumPy v2.3\)"),
[`numpy.uint64`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.uint64
"\(in NumPy v2.3\)")], `zarr.core.dtype.common.HasEndianness`

A Zarr data type for arrays containing 64-bit unsigned integers.

Wraps the `np.dtypes.UInt64DType` data type. Scalars for this data type are
instances of `np.uint64`.

Attributes:

    

**dtype_cls: np.dtypes.UInt64DType**

    

The class of the underlying NumPy dtype.

References

This class implements the unsigned 64-bit integer data type defined in Zarr V2
and V3.

See the [Zarr V2](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr
V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-
types/index.rst) specification documents for details.

cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) -> TIntScalar_co#

    

Attempt to cast a given object to a NumPy integer scalar.

Parameters:

    

**data** object

    

The data to be cast to a NumPy integer scalar.

Returns:

    

TIntScalar_co

    

The data cast as a NumPy integer scalar.

Raises:

    

TypeError

    

If the data cannot be converted to a NumPy integer scalar.

default_scalar() -> TIntScalar_co#

    

Get the default value, which is 0 cast to this dtype.

Returns:

    

TIntScalar_co

    

The default value.

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> TIntScalar_co#

    

Read a JSON-serializable value as a NumPy int scalar.

Parameters:

    

**data** JSON

    

The JSON-serializable value.

**zarr_format** ZarrFormat

    

The Zarr format version.

Returns:

    

TIntScalar_co

    

The NumPy int scalar.

Raises:

    

TypeError

    

If the input is not a valid integer type.

_classmethod _from_native_dtype(_dtype : zarr.core.dtype.wrapper.TBaseDType_)
-> Self#

    

Create an instance of this data type from a native NumPy dtype.

Parameters:

    

**dtype** TBaseDType

    

The native NumPy dtype.

Returns:

    

Self

    

An instance of this data type.

Raises:

    

DataTypeValidationError

    

If the input dtype is not a valid representation of this class unsigned 64-bit
integer.

to_json(

    _zarr_format : Literal[2]_,
) -> zarr.core.dtype.common.DTypeConfig_V2[Literal['>u8', '<u8'],
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

to_json(_zarr_format : Literal[3]_) -> Literal['uint64']

    

Convert the data type to a JSON-serializable form.

Parameters:

    

**zarr_format** ZarrFormat

    

The Zarr format version.

Returns:

    

DTypeConfig_V2[Literal[“>u8”, “<u8”], None] | Literal[“uint64”]
    

The JSON-serializable representation of the data type.

to_json_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_, _*_ , _zarr_format : zarr.core.common.ZarrFormat_) ->
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Convert an object to a JSON serializable scalar. For the integer data types,
the JSON form is a plain integer.

Parameters:

    

**data** object

    

The value to convert.

**zarr_format** ZarrFormat

    

The Zarr format version.

Returns:

    

int

    

The JSON-serializable form of the scalar.

to_native_dtype() -> numpy.dtypes.UInt64DType#

    

Convert the data type to a native NumPy dtype.

Returns:

    

np.dtypes.UInt64DType

    

The native NumPy dtype.eeeeeeeeeeeeeeeee

dtype_cls#

    

endianness _: EndiannessStr_ _ = 'little'_#

    

_property _item_size _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The size of a single scalar in bytes.

Returns:

    

int

    

The size of a single scalar in bytes.

_class _zarr.dtype.UInt8#

    

Bases:
`BaseInt`[[`numpy.dtypes.UInt8DType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.UInt8DType
"\(in NumPy v2.3\)"),
[`numpy.uint8`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.uint8
"\(in NumPy v2.3\)")]

A Zarr data type for arrays containing 8-bit unsigned integers.

Wraps the `np.dtypes.UInt8DType` data type. Scalars for this data type are
instances of `np.uint8`.

Attributes:

    

**dtype_cls** np.dtypes.UInt8DType

    

The class of the underlying NumPy dtype.

References

This class implements the 8-bit unsigned integer data type defined in Zarr V2
and V3.

See the [Zarr V2](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr
V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-
types/index.rst) specification documents for details.

cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) -> TIntScalar_co#

    

Attempt to cast a given object to a NumPy integer scalar.

Parameters:

    

**data** object

    

The data to be cast to a NumPy integer scalar.

Returns:

    

TIntScalar_co

    

The data cast as a NumPy integer scalar.

Raises:

    

TypeError

    

If the data cannot be converted to a NumPy integer scalar.

default_scalar() -> TIntScalar_co#

    

Get the default value, which is 0 cast to this dtype.

Returns:

    

TIntScalar_co

    

The default value.

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> TIntScalar_co#

    

Read a JSON-serializable value as a NumPy int scalar.

Parameters:

    

**data** JSON

    

The JSON-serializable value.

**zarr_format** ZarrFormat

    

The Zarr format version.

Returns:

    

TIntScalar_co

    

The NumPy int scalar.

Raises:

    

TypeError

    

If the input is not a valid integer type.

_classmethod _from_native_dtype(_dtype : zarr.core.dtype.wrapper.TBaseDType_)
-> Self#

    

Create a UInt8 from a np.dtype(‘uint8’) instance.

to_json(

    _zarr_format : Literal[2]_,
) -> zarr.core.dtype.common.DTypeConfig_V2[Literal['|u1'],
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

to_json(_zarr_format : Literal[3]_) -> Literal['uint8']

    

Convert the data type to a JSON-serializable form.

Parameters:

    

**zarr_format** ZarrFormat

    

The Zarr format version. Supported values are 2 and 3.

Returns:

    

`DTypeConfig_V2[Literal["|u1"], None] | Literal["uint8"]`
    

The JSON-serializable representation of the data type.

Raises:

    

ValueError

    

If zarr_format is not 2 or 3.

to_json_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_, _*_ , _zarr_format : zarr.core.common.ZarrFormat_) ->
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Convert an object to a JSON serializable scalar. For the integer data types,
the JSON form is a plain integer.

Parameters:

    

**data** object

    

The value to convert.

**zarr_format** ZarrFormat

    

The Zarr format version.

Returns:

    

int

    

The JSON-serializable form of the scalar.

to_native_dtype() -> numpy.dtypes.UInt8DType#

    

Create a NumPy unsigned 8-bit integer dtype instance from this UInt8 ZDType.

Returns:

    

np.dtypes.UInt8DType

    

The NumPy unsigned 8-bit integer dtype.

dtype_cls#

    

_property _item_size _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The size of a single scalar in bytes.

Returns:

    

int

    

The size of a single scalar in bytes.

_class _zarr.dtype.VariableLengthBytes#

    

Bases:
`zarr.core.dtype.wrapper.ZDType`[[`numpy.dtypes.ObjectDType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.ObjectDType
"\(in NumPy v2.3\)"),
[`bytes`](https://docs.python.org/3/library/stdtypes.html#bytes "\(in Python
v3.13\)")], `zarr.core.dtype.common.HasObjectCodec`

A Zarr data type for arrays containing variable-length sequences of bytes.

Wraps the NumPy “object” data type. Scalars for this data type are instances
of `bytes`.

Attributes:

    

**dtype_cls: ClassVar[type[np.dtypes.ObjectDType]] = np.dtypes.ObjectDType**

    

The NumPy data type wrapped by this ZDType.

**_zarr_v3_name: ClassVar[Literal[“variable_length_bytes”]] =
“variable_length_bytes”**

    

The name of this data type in Zarr V3.

**object_codec_id: ClassVar[Literal[“vlen-bytes”]] = “vlen-bytes”**

    

The object codec ID for this data type.

Notes

Because this data type uses the NumPy “object” data type, it does not
guarantee a compact memory representation of array data. Therefore a “vlen-
bytes” codec is needed to ensure that the array data can be persisted to
storage.

cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) -> [bytes](https://docs.python.org/3/library/stdtypes.html#bytes
"\(in Python v3.13\)")#

    

Attempt to cast a given object to a bytes scalar.

This method first checks if the provided data is a valid scalar that can be
converted to a bytes scalar. If the check succeeds, the unchecked casting
operation is performed. If the data is not valid, a TypeError is raised.

Parameters:

    

**data** object

    

The data to be cast to a bytes scalar.

Returns:

    

bytes

    

The data cast as a bytes scalar.

Raises:

    

TypeError

    

If the data cannot be converted to a bytes scalar.

default_scalar() ->
[bytes](https://docs.python.org/3/library/stdtypes.html#bytes "\(in Python
v3.13\)")#

    

Return the default scalar value for the variable-length bytes data type.

Returns:

    

bytes

    

The default scalar value, which is an empty byte string.

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> [bytes](https://docs.python.org/3/library/stdtypes.html#bytes "\(in
Python v3.13\)")#

    

Decode a base64-encoded JSON string to bytes.

Parameters:

    

**data** JSON

    

The JSON-serializable base64-encoded string.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

bytes

    

The decoded bytes from the base64 string.

Raises:

    

TypeError

    

If the input data is not a base64-encoded string.

_classmethod _from_native_dtype(_dtype : zarr.core.dtype.wrapper.TBaseDType_)
-> Self#

    

Create an instance of VariableLengthBytes from an instance of
np.dtypes.ObjectDType.

This method checks if the provided data type is an instance of
np.dtypes.ObjectDType. If so, it returns an instance of VariableLengthBytes.

Parameters:

    

**dtype** TBaseDType

    

The native dtype to convert.

Returns:

    

VariableLengthBytes

    

An instance of VariableLengthBytes.

Raises:

    

DataTypeValidationError

    

If the dtype is not compatible with VariableLengthBytes.

to_json(_zarr_format : Literal[2]_) -> VariableLengthBytesJSON_V2#

to_json(_zarr_format : Literal[3]_) -> Literal['variable_length_bytes']

    

Convert the variable-length bytes data type to a JSON-serializable form.

Parameters:

    

**zarr_format** ZarrFormat

    

The zarr format version. Accepted values are 2 and 3.

Returns:

    

`DTypeConfig_V2[Literal["|O"], Literal["vlen-bytes"]] | Literal["variable_length_bytes"]`
    

The JSON-serializable representation of the variable-length bytes data type.
For zarr_format 2, returns a dictionary with “name” and “object_codec_id”. For
zarr_format 3, returns a string identifier “variable_length_bytes”.

Raises:

    

ValueError

    

If zarr_format is not 2 or 3.

to_json_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_, _*_ , _zarr_format : zarr.core.common.ZarrFormat_) ->
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")#

    

Convert a scalar to a JSON-serializable string representation.

This method encodes the given scalar as bytes and then encodes the bytes as a
base64-encoded string.

Parameters:

    

**data** object

    

The scalar to convert.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

str

    

A string representation of the scalar.

to_native_dtype() -> numpy.dtypes.ObjectDType#

    

Create a NumPy object dtype from this VariableLengthBytes ZDType.

Returns:

    

np.dtypes.ObjectDType

    

A NumPy data type object representing variable-length bytes.

dtype_cls#

    

object_codec_id _: ClassVar[Literal['vlen-bytes']]__ = 'vlen-bytes'_#

    

_class _zarr.dtype.VariableLengthBytesJSON_V2#

    

Bases: `zarr.core.dtype.common.DTypeConfig_V2`[`Literal`[`'|O'`],
`Literal`[`'vlen-bytes'`]]

A wrapper around the JSON representation of the `VariableLengthBytes` data
type in Zarr V2.

The `name` field of this class contains the value that would appear under the
`dtype` field in Zarr V2 array metadata. The `object_codec_id` field is always
`"vlen-bytes"`

References

The structure of the `name` field is defined in the Zarr V2 [specification
document](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).

Examples

    
    
    {
        "name": "|O",
        "object_codec_id": "vlen-bytes"
    }
    

name _: typing_extensions.ReadOnly[TDTypeNameV2_co]_#

    

object_codec_id _: typing_extensions.ReadOnly[TObjectCodecID_co]_#

    

_class _zarr.dtype.VariableLengthUTF8#

    

Bases:
`UTF8Base`[[`numpy.dtypes.StringDType`](https://numpy.org/doc/stable/reference/routines.dtypes.html#numpy.dtypes.StringDType
"\(in NumPy v2.3\)")]

A Zarr data type for arrays containing variable-length UTF-8 strings.

Wraps the `np.dtypes.StringDType` data type. Scalars for this data type are
instances of `str`.

Attributes:

    

**dtype_cls** Type[np.dtypes.StringDType]

    

The NumPy dtype class for this data type.

**_zarr_v3_name** ClassVar[Literal[“variable_length_utf8”]] =
“variable_length_utf8”

    

The name of this data type in Zarr V3.

**object_codec_id** ClassVar[Literal[“vlen-utf8”]] = “vlen-utf8”

    

The object codec ID for this data type.

to_native_dtype() -> numpy.dtypes.StringDType#

    

Create a NumPy string dtype from this VariableLengthUTF8 ZDType.

Returns:

    

np.dtypes.StringDType

    

The NumPy string dtype.

dtype_cls#

    

_class _zarr.dtype.VariableLengthUTF8JSON_V2#

    

Bases: `zarr.core.dtype.common.DTypeConfig_V2`[`Literal`[`'|O'`],
`Literal`[`'vlen-utf8'`]]

A wrapper around the JSON representation of the `VariableLengthUTF8` data type
in Zarr V2.

The `name` field of this class contains the value that would appear under the
`dtype` field in Zarr V2 array metadata. The `object_codec_id` field is always
`"vlen-utf8"`.

References

The structure of the `name` field is defined in the Zarr V2 [specification
document](https://github.com/zarr-developers/zarr-
specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).

Examples

    
    
    {
        "name": "|O",
        "object_codec_id": "vlen-utf8"
    }
    

name _: typing_extensions.ReadOnly[TDTypeNameV2_co]_#

    

object_codec_id _: typing_extensions.ReadOnly[TObjectCodecID_co]_#

    

_class _zarr.dtype.ZDType#

    

Bases: [`abc.ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "\(in
Python v3.13\)"), `Generic`[`TDType_co`, `TScalar_co`]

Abstract base class for wrapping native array data types, e.g. numpy dtypes

Attributes:

    

**dtype_cls** ClassVar[type[TDType]]

    

The wrapped dtype class. This is a class variable.

**_zarr_v3_name** ClassVar[str]

    

The name given to the data type by a Zarr v3 data type specification. This is
a class variable, and it should generally be unique across different data
types.

_abstract _cast_scalar(_data :
[object](https://docs.python.org/3/library/functions.html#object "\(in Python
v3.13\)")_) -> TScalar_co#

    

Cast a python object to the wrapped scalar type.

The type of the provided scalar is first checked for compatibility. If it’s
incompatible with the associated scalar type, a `TypeError` will be raised.

Parameters:

    

**data** object

    

The python object to cast.

Returns:

    

TScalar

    

The cast value.

_abstract _default_scalar() -> TScalar_co#

    

Get the default scalar value for the wrapped data type.

This is a method, rather than an attribute, because the default value for some
data types depends on parameters that are not known until a concrete data type
is wrapped. For example, data types parametrized by a length like fixed-length
strings or bytes will generate scalars consistent with that length.

Returns:

    

TScalar

    

The default value for this data type.

_classmethod _from_json(

    _data : zarr.core.dtype.common.DTypeJSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> Self#

    

Create an instance of this ZDType from JSON data.

Parameters:

    

**data** DTypeJSON

    

The JSON representation of the data type.

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

Self

    

An instance of this data type.

_abstract _from_json_scalar(

    _data : zarr.core.common.JSON_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> TScalar_co#

    

Read a JSON-serializable value as a scalar.

Parameters:

    

**data** JSON

    

A JSON representation of a scalar value.

**zarr_format** ZarrFormat

    

The zarr format version. This is specified because the JSON serialization of
scalars differs between Zarr V2 and Zarr V3.

Returns:

    

TScalar

    

The deserialized scalar value.

_classmethod _from_native_dtype(_dtype : TBaseDType_) -> Self#

    

Abstractmethod:

    

Create a ZDType instance from a native data type.

This method is used when taking a user-provided native data type, like a NumPy
data type, and creating the corresponding ZDType instance from them.

Parameters:

    

**dtype** TDType

    

The native data type object to wrap.

Returns:

    

Self

    

The ZDType that wraps the native data type.

Raises:

    

TypeError

    

If the native data type is not consistent with the wrapped data type.

to_json(_zarr_format : Literal[2]_) -> zarr.core.dtype.common.DTypeSpec_V2#

to_json(_zarr_format : Literal[3]_) -> zarr.core.dtype.common.DTypeSpec_V3

    

Serialize this ZDType to JSON.

Parameters:

    

**zarr_format** ZarrFormat

    

The zarr format version.

Returns:

    

DTypeJSON_V2 | DTypeJSON_V3
    

The JSON-serializable representation of the wrapped data type

_abstract _to_json_scalar(

    _data : [object](https://docs.python.org/3/library/functions.html#object "\(in Python v3.13\)")_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> zarr.core.common.JSON#

    

Serialize a python object to the JSON representation of a scalar.

The value will first be cast to the scalar type associated with this ZDType,
then serialized to JSON.

Parameters:

    

**data** object

    

The value to convert.

**zarr_format** ZarrFormat

    

The zarr format version. This is specified because the JSON serialization of
scalars differs between Zarr V2 and Zarr V3.

Returns:

    

JSON

    

The JSON-serialized scalar.

_abstract _to_native_dtype() -> TDType_co#

    

Return an instance of the wrapped data type. This operation inverts
`from_native_dtype`.

Returns:

    

TDType

    

The native data type wrapped by this ZDType.

dtype_cls _:
ClassVar[[type](https://docs.python.org/3/library/functions.html#type "\(in
Python v3.13\)")[TDType_co]]_#

    

zarr.dtype.parse_dtype(

    _dtype_spec : ZDTypeLike_,
    _*_ ,
    _zarr_format : zarr.core.common.ZarrFormat_,
) -> wrapper.ZDType[wrapper.TBaseDType, wrapper.TBaseScalar]#

    

Convert the input as a ZDType.

Parameters:

    

**dtype_spec** ZDTypeLike

    

The input to be converted to a ZDType. This could be a ZDType, which will be
returned directly, or a JSON representation of a ZDType, or a numpy dtype, or
a python object that can be converted into a native dtype.

**zarr_format** ZarrFormat

    

The Zarr format version. This parameter is required because this function will
attempt to parse the JSON representation of a data type, and the JSON
representation of data types varies between Zarr 2 and Zarr 3.

Returns:

    

ZDType[TBaseDType, TBaseScalar]

    

The ZDType corresponding to the input.

Examples

    
    
    >>> from zarr.dtype import parse_dtype
    >>> import numpy as np
    >>> parse_dtype("int32", zarr_format=2)
    Int32(endianness='little')
    >>> parse_dtype(np.dtype('S10'), zarr_format=2)
    NullTerminatedBytes(length=10)
    >>> parse_dtype({"name": "numpy.datetime64", "configuration": {"unit": "s", "scale_factor": 10}}, zarr_format=3)
    DateTime64(endianness='little', scale_factor=10, unit='s')
    

zarr.dtype.data_type_registry#

    

#### zarr.errors#

##### Exceptions#

`BaseZarrError` | Base error which all zarr errors are sub-classed from.  
---|---  
`ContainsArrayAndGroupError` | Raised when both array and group metadata are found at the same path.  
`ContainsArrayError` | Raised when an array already exists at a certain path.  
`ContainsGroupError` | Raised when a group already exists at a certain path.  
`GroupNotFoundError` | Raised when a group isn't found at a certain path.  
`MetadataValidationError` | Raised when the Zarr metadata is invalid in some way  
`NodeTypeValidationError` | Specialized exception when the node_type of the metadata document is incorrect..  
  
##### Module Contents#

_exception _zarr.errors.BaseZarrError(_* args: Any_)#

    

Bases:
[`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError
"\(in Python v3.13\)")

Base error which all zarr errors are sub-classed from.

_exception _zarr.errors.ContainsArrayAndGroupError(_* args: Any_)#

    

Bases: `BaseZarrError`

Raised when both array and group metadata are found at the same path.

_exception _zarr.errors.ContainsArrayError(_* args: Any_)#

    

Bases: `BaseZarrError`

Raised when an array already exists at a certain path.

_exception _zarr.errors.ContainsGroupError(_* args: Any_)#

    

Bases: `BaseZarrError`

Raised when a group already exists at a certain path.

_exception _zarr.errors.GroupNotFoundError(_* args: Any_)#

    

Bases: `BaseZarrError`,
[`FileNotFoundError`](https://docs.python.org/3/library/exceptions.html#FileNotFoundError
"\(in Python v3.13\)")

Raised when a group isn’t found at a certain path.

_exception _zarr.errors.MetadataValidationError(_* args: Any_)#

    

Bases: `BaseZarrError`

Raised when the Zarr metadata is invalid in some way

_exception _zarr.errors.NodeTypeValidationError(_* args: Any_)#

    

Bases: `MetadataValidationError`

Specialized exception when the node_type of the metadata document is
incorrect..

This can be raised when the value is invalid or unexpected given the context,
for example an ‘array’ node when we expected a ‘group’.

#### zarr.registry#

##### Classes#

`Registry` |   
---|---  
  
##### Functions#

`get_buffer_class`(→ type[zarr.core.buffer.Buffer]) |   
---|---  
`get_codec_class`(→ type[zarr.abc.codec.Codec]) |   
`get_ndbuffer_class`(→ type[zarr.core.buffer.NDBuffer]) |   
`get_pipeline_class`(→ type[zarr.abc.codec.CodecPipeline]) |   
`register_buffer`(→ None) |   
`register_codec`(→ None) |   
`register_ndbuffer`(→ None) |   
`register_pipeline`(→ None) |   
  
##### Module Contents#

_class _zarr.registry.Registry#

    

Bases: [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "\(in
Python v3.13\)")[[`str`](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"),
[`type`](https://docs.python.org/3/library/functions.html#type "\(in Python
v3.13\)")[`T`]], `Generic`[`T`]

lazy_load() -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

register(_cls : [type](https://docs.python.org/3/library/functions.html#type "\(in Python v3.13\)")[T]_, _qualname : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")#
    

lazy_load_list _: [list](https://docs.python.org/3/library/stdtypes.html#list
"\(in Python
v3.13\)")[[importlib.metadata.EntryPoint](https://docs.python.org/3/library/importlib.metadata.html#importlib.metadata.EntryPoint
"\(in Python v3.13\)")]__ = []_#

    

zarr.registry.get_buffer_class(_reload_config :
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)") = False_) ->
[type](https://docs.python.org/3/library/functions.html#type "\(in Python
v3.13\)")[zarr.core.buffer.Buffer]#

    

zarr.registry.get_codec_class(

    _key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _reload_config : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
) -> [type](https://docs.python.org/3/library/functions.html#type "\(in Python
v3.13\)")[zarr.abc.codec.Codec]#

    

zarr.registry.get_ndbuffer_class(

    _reload_config : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
) -> [type](https://docs.python.org/3/library/functions.html#type "\(in Python
v3.13\)")[zarr.core.buffer.NDBuffer]#

    

zarr.registry.get_pipeline_class(

    _reload_config : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
) -> [type](https://docs.python.org/3/library/functions.html#type "\(in Python
v3.13\)")[zarr.abc.codec.CodecPipeline]#

    

zarr.registry.register_buffer(

    _cls : [type](https://docs.python.org/3/library/functions.html#type "\(in Python v3.13\)")[zarr.core.buffer.Buffer]_,
    _qualname : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

zarr.registry.register_codec(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_, _codec_cls :
[type](https://docs.python.org/3/library/functions.html#type "\(in Python
v3.13\)")[zarr.abc.codec.Codec]_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

zarr.registry.register_ndbuffer(

    _cls : [type](https://docs.python.org/3/library/functions.html#type "\(in Python v3.13\)")[zarr.core.buffer.NDBuffer]_,
    _qualname : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

zarr.registry.register_pipeline(_pipe_cls :
[type](https://docs.python.org/3/library/functions.html#type "\(in Python
v3.13\)")[zarr.abc.codec.CodecPipeline]_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

#### zarr.storage#

##### Attributes#

`StoreLike` |   
---|---  
  
##### Classes#

`FsspecStore` | Store for remote data based on FSSpec.  
---|---  
`GpuMemoryStore` | Store for GPU memory.  
`LocalStore` | Store for the local file system.  
`LoggingStore` | Store that logs all calls to another wrapped store.  
`MemoryStore` | Store for local memory.  
`ObjectStore` | Store that uses obstore for fast read/write from AWS, GCP, Azure.  
`StorePath` | Path-like interface for a Store.  
`WrapperStore` | Store that wraps an existing Store.  
`ZipStore` | Store using a ZIP file.  
  
##### Package Contents#

_class _zarr.storage.FsspecStore(

    _fs : fsspec.asyn.AsyncFileSystem_,
    _read_only : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") = '/'_,
    _allowed_exceptions : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[type](https://docs.python.org/3/library/functions.html#type "\(in Python v3.13\)")[[Exception](https://docs.python.org/3/library/exceptions.html#Exception "\(in Python v3.13\)")], Ellipsis] = ALLOWED_EXCEPTIONS_,
)#

    

Bases: `zarr.abc.store.Store`

Store for remote data based on FSSpec.

Parameters:

    

**fs** AsyncFileSystem

    

The Async FSSpec filesystem to use with this store.

**read_only** bool

    

Whether the store is read-only

**path** str

    

The root path of the store. This should be a relative path and must not
include the filesystem scheme.

**allowed_exceptions** tuple[type[Exception], …]

    

When fetching data, these cases will be deemed to correspond to missing keys.

Attributes:

    

**fs**

    
**allowed_exceptions**

    
**supports_writes**

    
**supports_deletes**

    
**supports_partial_writes**

    
**supports_listing**

    
Raises:

    

TypeError

    

If the Filesystem does not support async operations.

ValueError

    

If the path argument includes a scheme.

Warns:

    

UserWarning

    

If the file system (fs) was not created with asynchronous=True.

See also

`FsspecStore.from_upath`

    
`FsspecStore.from_url`

    

_async _clear() ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Clear the store.

Remove all keys and values from the store.

close() -> [None](https://docs.python.org/3/library/constants.html#None "\(in
Python v3.13\)")#

    

Close the store.

_async _delete(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Remove a key from the store

Parameters:

    

**key** str

    

_async _delete_dir(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Remove all keys and prefixes in the store that begin with a given prefix.

_async _exists(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")#

    

Check if a key exists in the store.

Parameters:

    

**key** str

    
Returns:

    

bool

    

_classmethod _from_mapper(

    _fs_map : fsspec.mapping.FSMap_,
    _read_only : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _allowed_exceptions : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[type](https://docs.python.org/3/library/functions.html#type "\(in Python v3.13\)")[[Exception](https://docs.python.org/3/library/exceptions.html#Exception "\(in Python v3.13\)")], Ellipsis] = ALLOWED_EXCEPTIONS_,
) -> FsspecStore#

    

Create a FsspecStore from a FSMap object.

Parameters:

    

**fs_map** FSMap

    

Fsspec mutable mapping object.

**read_only** bool

    

Whether the store is read-only, defaults to False.

**allowed_exceptions** tuple, optional

    

The exceptions that are allowed to be raised when accessing the store.
Defaults to ALLOWED_EXCEPTIONS.

Returns:

    

FsspecStore

    

_classmethod _from_upath(

    _upath : Any_,
    _read_only : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _allowed_exceptions : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[type](https://docs.python.org/3/library/functions.html#type "\(in Python v3.13\)")[[Exception](https://docs.python.org/3/library/exceptions.html#Exception "\(in Python v3.13\)")], Ellipsis] = ALLOWED_EXCEPTIONS_,
) -> FsspecStore#

    

Create a FsspecStore from an upath object.

Parameters:

    

**upath** UPath

    

The upath to the root of the store.

**read_only** bool

    

Whether the store is read-only, defaults to False.

**allowed_exceptions** tuple, optional

    

The exceptions that are allowed to be raised when accessing the store.
Defaults to ALLOWED_EXCEPTIONS.

Returns:

    

FsspecStore

    

_classmethod _from_url(

    _url : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _read_only : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _allowed_exceptions : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[type](https://docs.python.org/3/library/functions.html#type "\(in Python v3.13\)")[[Exception](https://docs.python.org/3/library/exceptions.html#Exception "\(in Python v3.13\)")], Ellipsis] = ALLOWED_EXCEPTIONS_,
) -> FsspecStore#

    

Create a FsspecStore from a URL. The type of store is determined from the URL
scheme.

Parameters:

    

**url** str

    

The URL to the root of the store.

**storage_options** dict, optional

    

The options to pass to fsspec when creating the filesystem.

**read_only** bool

    

Whether the store is read-only, defaults to False.

**allowed_exceptions** tuple, optional

    

The exceptions that are allowed to be raised when accessing the store.
Defaults to ALLOWED_EXCEPTIONS.

Returns:

    

FsspecStore

    

_async _get(

    _key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _prototype : zarr.core.buffer.BufferPrototype_,
    _byte_range : zarr.abc.store.ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")#
    

Retrieve the value associated with a given key.

Parameters:

    

**key** str

    
**prototype** BufferPrototype

    

The prototype of the output buffer. Stores may support a default buffer
prototype.

**byte_range** ByteRequest, optional

    

ByteRequest may be one of the following. If not provided, all data associated
with the key is retrieved. \- RangeByteRequest(int, int): Request a specific
range of bytes in the form (start, end). The end is exclusive. If the given
range is zero-length or starts after the end of the object, an error will be
returned. Additionally, if the range ends after the end of the object, the
entire remainder of the object will be returned. Otherwise, the exact
requested range will be returned. \- OffsetByteRequest(int): Request all bytes
starting from a given byte offset. This is equivalent to bytes={int}- as an
HTTP header. \- SuffixByteRequest(int): Request the last int bytes. Note that
here, int is the size of the request, not the byte offset. This is equivalent
to bytes=-{int} as an HTTP header.

Returns:

    

Buffer

    

_async _get_partial_values(

    _prototype : zarr.core.buffer.BufferPrototype_,
    _key_ranges : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.abc.store.ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]]_,
) -> [list](https://docs.python.org/3/library/stdtypes.html#list "\(in Python v3.13\)")[zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Retrieve possibly partial values from given key_ranges.

Parameters:

    

**prototype** BufferPrototype

    

The prototype of the output buffer. Stores may support a default buffer
prototype.

**key_ranges** Iterable[tuple[str, tuple[int | None, int | None]]]
    

Ordered set of key, range pairs, a key may occur multiple times with different
ranges

Returns:

    

list of values, in the order of the key_ranges, may contain null/none for
missing keys

    

_async _getsize(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")#

    

Return the size, in bytes, of a value in a Store.

Parameters:

    

**key** str

    
Returns:

    

**nbytes** int

    

The size of the value (in bytes).

Raises:

    

FileNotFoundError

    

When the given key does not exist in the store.

_async _getsize_prefix(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")#

    

Return the size, in bytes, of all values under a prefix.

Parameters:

    

**prefix** str

    

The prefix of the directory to measure.

Returns:

    

**nbytes** int

    

The sum of the sizes of the values in the directory (in bytes).

See also

`zarr.Array.nbytes_stored`

    
`Store.getsize`

    

Notes

`getsize_prefix` is just provided as a potentially faster alternative to
listing all the keys under a prefix calling `Store.getsize()` on each.

In general, `prefix` should be the path of an Array or Group in the Store.
Implementations may differ on the behavior when some other `prefix` is
provided.

_async _is_empty(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")#

    

Check if the directory is empty.

Parameters:

    

**prefix** str

    

Prefix of keys to check.

Returns:

    

bool

    

True if the store is empty, False otherwise.

_async _list() ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys in the store.

Returns:

    

AsyncIterator[str]

    

_async _list_dir(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys and prefixes with a given prefix and which do not contain
the character “/” after the given prefix.

Parameters:

    

**prefix** str

    
Returns:

    

AsyncIterator[str]

    

_async _list_prefix(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys in the store that begin with a given prefix. Keys are
returned relative to the root of the store.

Parameters:

    

**prefix** str

    
Returns:

    

AsyncIterator[str]

    

_classmethod _open(_* args: Any_, _** kwargs: Any_) -> Self#

    

Async:

    

Create and open the store.

Parameters:

    

***args** Any

    

Positional arguments to pass to the store constructor.

****kwargs** Any

    

Keyword arguments to pass to the store constructor.

Returns:

    

Store

    

The opened store instance.

_async _set(

    _key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _value : zarr.core.buffer.Buffer_,
    _byte_range : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store a (key, value) pair.

Parameters:

    

**key** str

    
**value** Buffer

    

_async _set_if_not_exists(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_, _value : zarr.core.buffer.Buffer_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store a key to `value` if the key is not already present.

Parameters:

    

**key** str

    
**value** Buffer

    

_abstract _set_partial_values(

    _key_start_values : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), zarr.core.common.BytesLike]]_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Async:

    

Store values at a given key, starting at byte range_start.

Parameters:

    

**key_start_values** list[tuple[str, int, BytesLike]]

    

set of key, range_start, values triples, a key may occur multiple times with
different range_starts, range_starts (considering the length of the respective
values) must not specify overlapping ranges for the same key

with_read_only(_read_only :
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)") = False_) -> FsspecStore#

    

Return a new store with a new read_only setting.

The new store points to the same location with the specified new read_only
state. The returned Store is not automatically opened, and this store is not
automatically closed.

Parameters:

    

**read_only**

    

If True, the store will be created in read-only mode. Defaults to False.

Returns:

    

A new store of the same type with the new read only attribute.

    

allowed_exceptions _:
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[type](https://docs.python.org/3/library/functions.html#type "\(in
Python
v3.13\)")[[Exception](https://docs.python.org/3/library/exceptions.html#Exception
"\(in Python v3.13\)")], Ellipsis]_#

    

fs _: fsspec.asyn.AsyncFileSystem_#

    

path _: [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_#

    

_property _read_only _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Is the store read-only?

_property _supports_consolidated_metadata _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support consolidated metadata?.

If it doesn’t an error will be raised on requests to consolidate the metadata.
Returning False can be useful for stores which implement their own
consolidation mechanism outside of the zarr-python implementation.

supports_deletes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = True_#

    

Does the store support deletes?

supports_listing _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = True_#

    

Does the store support listing?

supports_partial_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = False_#

    

Does the store support partial writes?

supports_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = True_#

    

Does the store support writes?

_class _zarr.storage.GpuMemoryStore(

    _store_dict : [collections.abc.MutableMapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableMapping "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.buffer.gpu.Buffer] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _*_ ,
    _read_only : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
)#

    

Bases: `MemoryStore`

Store for GPU memory.

Stores every chunk in GPU memory irrespective of the original location.

The dictionary of buffers to initialize this memory store with _must_ be GPU
Buffers.

Writing data to this store through `.set` will move the buffer to the GPU if
necessary.

Parameters:

    

**store_dict** MutableMapping, optional

    

A mutable mapping with string keys and `zarr.core.buffer.gpu.Buffer` values.

**read_only** bool

    

Whether to open the store in read-only mode.

_async _clear() ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Clear the store.

Remove all keys and values from the store.

close() -> [None](https://docs.python.org/3/library/constants.html#None "\(in
Python v3.13\)")#

    

Close the store.

_async _delete(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Remove a key from the store

Parameters:

    

**key** str

    

_async _delete_dir(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Remove all keys and prefixes in the store that begin with a given prefix.

_async _exists(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")#

    

Check if a key exists in the store.

Parameters:

    

**key** str

    
Returns:

    

bool

    

_classmethod _from_dict(

    _store_dict : [collections.abc.MutableMapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableMapping "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.buffer.Buffer]_,
) -> Self#

    

Create a GpuMemoryStore from a dictionary of buffers at any location.

The dictionary backing the newly created `GpuMemoryStore` will not be the same
as `store_dict`.

Parameters:

    

**store_dict** mapping

    

A mapping of strings keys to arbitrary Buffers. The buffer data will be moved
into a `gpu.Buffer`.

Returns:

    

GpuMemoryStore

    

_async _get(

    _key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _prototype : zarr.core.buffer.BufferPrototype_,
    _byte_range : zarr.abc.store.ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")#
    

Retrieve the value associated with a given key.

Parameters:

    

**key** str

    
**prototype** BufferPrototype

    

The prototype of the output buffer. Stores may support a default buffer
prototype.

**byte_range** ByteRequest, optional

    

ByteRequest may be one of the following. If not provided, all data associated
with the key is retrieved. \- RangeByteRequest(int, int): Request a specific
range of bytes in the form (start, end). The end is exclusive. If the given
range is zero-length or starts after the end of the object, an error will be
returned. Additionally, if the range ends after the end of the object, the
entire remainder of the object will be returned. Otherwise, the exact
requested range will be returned. \- OffsetByteRequest(int): Request all bytes
starting from a given byte offset. This is equivalent to bytes={int}- as an
HTTP header. \- SuffixByteRequest(int): Request the last int bytes. Note that
here, int is the size of the request, not the byte offset. This is equivalent
to bytes=-{int} as an HTTP header.

Returns:

    

Buffer

    

_async _get_partial_values(

    _prototype : zarr.core.buffer.BufferPrototype_,
    _key_ranges : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.abc.store.ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]]_,
) -> [list](https://docs.python.org/3/library/stdtypes.html#list "\(in Python v3.13\)")[zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Retrieve possibly partial values from given key_ranges.

Parameters:

    

**prototype** BufferPrototype

    

The prototype of the output buffer. Stores may support a default buffer
prototype.

**key_ranges** Iterable[tuple[str, tuple[int | None, int | None]]]
    

Ordered set of key, range pairs, a key may occur multiple times with different
ranges

Returns:

    

list of values, in the order of the key_ranges, may contain null/none for
missing keys

    

_async _getsize(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")#

    

Return the size, in bytes, of a value in a Store.

Parameters:

    

**key** str

    
Returns:

    

**nbytes** int

    

The size of the value (in bytes).

Raises:

    

FileNotFoundError

    

When the given key does not exist in the store.

_async _getsize_prefix(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")#

    

Return the size, in bytes, of all values under a prefix.

Parameters:

    

**prefix** str

    

The prefix of the directory to measure.

Returns:

    

**nbytes** int

    

The sum of the sizes of the values in the directory (in bytes).

See also

`zarr.Array.nbytes_stored`

    
`Store.getsize`

    

Notes

`getsize_prefix` is just provided as a potentially faster alternative to
listing all the keys under a prefix calling `Store.getsize()` on each.

In general, `prefix` should be the path of an Array or Group in the Store.
Implementations may differ on the behavior when some other `prefix` is
provided.

_async _is_empty(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")#

    

Check if the directory is empty.

Parameters:

    

**prefix** str

    

Prefix of keys to check.

Returns:

    

bool

    

True if the store is empty, False otherwise.

_async _list() ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys in the store.

Returns:

    

AsyncIterator[str]

    

_async _list_dir(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys and prefixes with a given prefix and which do not contain
the character “/” after the given prefix.

Parameters:

    

**prefix** str

    
Returns:

    

AsyncIterator[str]

    

_async _list_prefix(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys in the store that begin with a given prefix. Keys are
returned relative to the root of the store.

Parameters:

    

**prefix** str

    
Returns:

    

AsyncIterator[str]

    

_classmethod _open(_* args: Any_, _** kwargs: Any_) -> Self#

    

Async:

    

Create and open the store.

Parameters:

    

***args** Any

    

Positional arguments to pass to the store constructor.

****kwargs** Any

    

Keyword arguments to pass to the store constructor.

Returns:

    

Store

    

The opened store instance.

_async _set(

    _key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _value : zarr.core.buffer.Buffer_,
    _byte_range : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store a (key, value) pair.

Parameters:

    

**key** str

    
**value** Buffer

    

_async _set_if_not_exists(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_, _value : zarr.core.buffer.Buffer_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store a key to `value` if the key is not already present.

Parameters:

    

**key** str

    
**value** Buffer

    

_abstract _set_partial_values(

    _key_start_values : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), [bytes](https://docs.python.org/3/library/stdtypes.html#bytes "\(in Python v3.13\)") | [bytearray](https://docs.python.org/3/library/stdtypes.html#bytearray "\(in Python v3.13\)") | [memoryview](https://docs.python.org/3/library/stdtypes.html#memoryview "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")]]]_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Async:

    

Store values at a given key, starting at byte range_start.

Parameters:

    

**key_start_values** list[tuple[str, int, BytesLike]]

    

set of key, range_start, values triples, a key may occur multiple times with
different range_starts, range_starts (considering the length of the respective
values) must not specify overlapping ranges for the same key

with_read_only(_read_only :
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)") = False_) -> MemoryStore#

    

Return a new store with a new read_only setting.

The new store points to the same location with the specified new read_only
state. The returned Store is not automatically opened, and this store is not
automatically closed.

Parameters:

    

**read_only**

    

If True, the store will be created in read-only mode. Defaults to False.

Returns:

    

A new store of the same type with the new read only attribute.

    

_property _read_only _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Is the store read-only?

_property _supports_consolidated_metadata _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support consolidated metadata?.

If it doesn’t an error will be raised on requests to consolidate the metadata.
Returning False can be useful for stores which implement their own
consolidation mechanism outside of the zarr-python implementation.

supports_deletes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = True_#

    

Does the store support deletes?

supports_listing _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = True_#

    

Does the store support listing?

supports_partial_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = True_#

    

Does the store support partial writes?

supports_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = True_#

    

Does the store support writes?

_class _zarr.storage.LocalStore(_root : [pathlib.Path](https://docs.python.org/3/library/pathlib.html#pathlib.Path "\(in Python v3.13\)") | [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_, _*_ , _read_only : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_)#
    

Bases: `zarr.abc.store.Store`

Store for the local file system.

Parameters:

    

**root** str or Path

    

Directory to use as root of store.

**read_only** bool

    

Whether the store is read-only

Attributes:

    

**supports_writes**

    
**supports_deletes**

    
**supports_partial_writes**

    
**supports_listing**

    
**root**

    

_async _clear() ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Clear the store.

Remove all keys and values from the store.

close() -> [None](https://docs.python.org/3/library/constants.html#None "\(in
Python v3.13\)")#

    

Close the store.

_async _delete(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Remove a key from the store.

Parameters:

    

**key** str

    

Notes

If `key` is a directory within this store, the entire directory at `store.root
/ key` is deleted.

_async _delete_dir(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Remove all keys and prefixes in the store that begin with a given prefix.

_async _exists(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")#

    

Check if a key exists in the store.

Parameters:

    

**key** str

    
Returns:

    

bool

    

_async _get(

    _key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _prototype : zarr.core.buffer.BufferPrototype | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _byte_range : zarr.abc.store.ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")#
    

Retrieve the value associated with a given key.

Parameters:

    

**key** str

    
**prototype** BufferPrototype

    

The prototype of the output buffer. Stores may support a default buffer
prototype.

**byte_range** ByteRequest, optional

    

ByteRequest may be one of the following. If not provided, all data associated
with the key is retrieved. \- RangeByteRequest(int, int): Request a specific
range of bytes in the form (start, end). The end is exclusive. If the given
range is zero-length or starts after the end of the object, an error will be
returned. Additionally, if the range ends after the end of the object, the
entire remainder of the object will be returned. Otherwise, the exact
requested range will be returned. \- OffsetByteRequest(int): Request all bytes
starting from a given byte offset. This is equivalent to bytes={int}- as an
HTTP header. \- SuffixByteRequest(int): Request the last int bytes. Note that
here, int is the size of the request, not the byte offset. This is equivalent
to bytes=-{int} as an HTTP header.

Returns:

    

Buffer

    

_async _get_partial_values(

    _prototype : zarr.core.buffer.BufferPrototype_,
    _key_ranges : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.abc.store.ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]]_,
) -> [list](https://docs.python.org/3/library/stdtypes.html#list "\(in Python v3.13\)")[zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Retrieve possibly partial values from given key_ranges.

Parameters:

    

**prototype** BufferPrototype

    

The prototype of the output buffer. Stores may support a default buffer
prototype.

**key_ranges** Iterable[tuple[str, tuple[int | None, int | None]]]
    

Ordered set of key, range pairs, a key may occur multiple times with different
ranges

Returns:

    

list of values, in the order of the key_ranges, may contain null/none for
missing keys

    

_async _getsize(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")#

    

Return the size, in bytes, of a value in a Store.

Parameters:

    

**key** str

    
Returns:

    

**nbytes** int

    

The size of the value (in bytes).

Raises:

    

FileNotFoundError

    

When the given key does not exist in the store.

_async _getsize_prefix(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")#

    

Return the size, in bytes, of all values under a prefix.

Parameters:

    

**prefix** str

    

The prefix of the directory to measure.

Returns:

    

**nbytes** int

    

The sum of the sizes of the values in the directory (in bytes).

See also

`zarr.Array.nbytes_stored`

    
`Store.getsize`

    

Notes

`getsize_prefix` is just provided as a potentially faster alternative to
listing all the keys under a prefix calling `Store.getsize()` on each.

In general, `prefix` should be the path of an Array or Group in the Store.
Implementations may differ on the behavior when some other `prefix` is
provided.

_async _is_empty(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")#

    

Check if the directory is empty.

Parameters:

    

**prefix** str

    

Prefix of keys to check.

Returns:

    

bool

    

True if the store is empty, False otherwise.

_async _list() ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys in the store.

Returns:

    

AsyncIterator[str]

    

_async _list_dir(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys and prefixes with a given prefix and which do not contain
the character “/” after the given prefix.

Parameters:

    

**prefix** str

    
Returns:

    

AsyncIterator[str]

    

_async _list_prefix(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys in the store that begin with a given prefix. Keys are
returned relative to the root of the store.

Parameters:

    

**prefix** str

    
Returns:

    

AsyncIterator[str]

    

_async _move(_dest_root : [pathlib.Path](https://docs.python.org/3/library/pathlib.html#pathlib.Path "\(in Python v3.13\)") | [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")#
    

Move the store to another path. The old root directory is deleted.

_classmethod _open(_* args: Any_, _** kwargs: Any_) -> Self#

    

Async:

    

Create and open the store.

Parameters:

    

***args** Any

    

Positional arguments to pass to the store constructor.

****kwargs** Any

    

Keyword arguments to pass to the store constructor.

Returns:

    

Store

    

The opened store instance.

_async _set(_key : [str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")_, _value : zarr.core.buffer.Buffer_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store a (key, value) pair.

Parameters:

    

**key** str

    
**value** Buffer

    

_async _set_if_not_exists(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_, _value : zarr.core.buffer.Buffer_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store a key to `value` if the key is not already present.

Parameters:

    

**key** str

    
**value** Buffer

    

_async _set_partial_values(

    _key_start_values : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), [bytes](https://docs.python.org/3/library/stdtypes.html#bytes "\(in Python v3.13\)") | [bytearray](https://docs.python.org/3/library/stdtypes.html#bytearray "\(in Python v3.13\)") | [memoryview](https://docs.python.org/3/library/stdtypes.html#memoryview "\(in Python v3.13\)")]]_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store values at a given key, starting at byte range_start.

Parameters:

    

**key_start_values** list[tuple[str, int, BytesLike]]

    

set of key, range_start, values triples, a key may occur multiple times with
different range_starts, range_starts (considering the length of the respective
values) must not specify overlapping ranges for the same key

with_read_only(_read_only :
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)") = False_) -> LocalStore#

    

Return a new store with a new read_only setting.

The new store points to the same location with the specified new read_only
state. The returned Store is not automatically opened, and this store is not
automatically closed.

Parameters:

    

**read_only**

    

If True, the store will be created in read-only mode. Defaults to False.

Returns:

    

A new store of the same type with the new read only attribute.

    

_property _read_only _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Is the store read-only?

root _:
[pathlib.Path](https://docs.python.org/3/library/pathlib.html#pathlib.Path
"\(in Python v3.13\)")_#

    

_property _supports_consolidated_metadata _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support consolidated metadata?.

If it doesn’t an error will be raised on requests to consolidate the metadata.
Returning False can be useful for stores which implement their own
consolidation mechanism outside of the zarr-python implementation.

supports_deletes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = True_#

    

Does the store support deletes?

supports_listing _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = True_#

    

Does the store support listing?

supports_partial_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = True_#

    

Does the store support partial writes?

supports_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = True_#

    

Does the store support writes?

_class _zarr.storage.LoggingStore(

    _store : T_Store_,
    _log_level : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") = 'DEBUG'_,
    _log_handler : [logging.Handler](https://docs.python.org/3/library/logging.html#logging.Handler "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
)#

    

Bases: `zarr.storage._wrapper.WrapperStore`[`T_Store`]

Store that logs all calls to another wrapped store.

Parameters:

    

**store** Store

    

Store to wrap

**log_level** str

    

Log level

**log_handler** logging.Handler

    

Log handler

Attributes:

    

**counter** dict

    

Counter of number of times each method has been called

_async _clear() ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Clear the store.

Remove all keys and values from the store.

close() -> [None](https://docs.python.org/3/library/constants.html#None "\(in
Python v3.13\)")#

    

Close the store.

_async _delete(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Remove a key from the store

Parameters:

    

**key** str

    

_async _delete_dir(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Remove all keys and prefixes in the store that begin with a given prefix.

_async _exists(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")#

    

Check if a key exists in the store.

Parameters:

    

**key** str

    
Returns:

    

bool

    

_async _get(

    _key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _prototype : zarr.core.buffer.BufferPrototype_,
    _byte_range : zarr.abc.store.ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")#
    

Retrieve the value associated with a given key.

Parameters:

    

**key** str

    
**prototype** BufferPrototype

    

The prototype of the output buffer. Stores may support a default buffer
prototype.

**byte_range** ByteRequest, optional

    

ByteRequest may be one of the following. If not provided, all data associated
with the key is retrieved. \- RangeByteRequest(int, int): Request a specific
range of bytes in the form (start, end). The end is exclusive. If the given
range is zero-length or starts after the end of the object, an error will be
returned. Additionally, if the range ends after the end of the object, the
entire remainder of the object will be returned. Otherwise, the exact
requested range will be returned. \- OffsetByteRequest(int): Request all bytes
starting from a given byte offset. This is equivalent to bytes={int}- as an
HTTP header. \- SuffixByteRequest(int): Request the last int bytes. Note that
here, int is the size of the request, not the byte offset. This is equivalent
to bytes=-{int} as an HTTP header.

Returns:

    

Buffer

    

_async _get_partial_values(

    _prototype : zarr.core.buffer.BufferPrototype_,
    _key_ranges : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.abc.store.ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]]_,
) -> [list](https://docs.python.org/3/library/stdtypes.html#list "\(in Python v3.13\)")[zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Retrieve possibly partial values from given key_ranges.

Parameters:

    

**prototype** BufferPrototype

    

The prototype of the output buffer. Stores may support a default buffer
prototype.

**key_ranges** Iterable[tuple[str, tuple[int | None, int | None]]]
    

Ordered set of key, range pairs, a key may occur multiple times with different
ranges

Returns:

    

list of values, in the order of the key_ranges, may contain null/none for
missing keys

    

_async _getsize(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")#

    

Return the size, in bytes, of a value in a Store.

Parameters:

    

**key** str

    
Returns:

    

**nbytes** int

    

The size of the value (in bytes).

Raises:

    

FileNotFoundError

    

When the given key does not exist in the store.

_async _getsize_prefix(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")#

    

Return the size, in bytes, of all values under a prefix.

Parameters:

    

**prefix** str

    

The prefix of the directory to measure.

Returns:

    

**nbytes** int

    

The sum of the sizes of the values in the directory (in bytes).

See also

`zarr.Array.nbytes_stored`

    
`Store.getsize`

    

Notes

`getsize_prefix` is just provided as a potentially faster alternative to
listing all the keys under a prefix calling `Store.getsize()` on each.

In general, `prefix` should be the path of an Array or Group in the Store.
Implementations may differ on the behavior when some other `prefix` is
provided.

_async _is_empty(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)") = ''_) ->
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")#

    

Check if the directory is empty.

Parameters:

    

**prefix** str

    

Prefix of keys to check.

Returns:

    

bool

    

True if the store is empty, False otherwise.

_async _list() ->
[collections.abc.AsyncGenerator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncGenerator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")]#

    

Retrieve all keys in the store.

Returns:

    

AsyncIterator[str]

    

_async _list_dir(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) ->
[collections.abc.AsyncGenerator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncGenerator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")]#

    

Retrieve all keys and prefixes with a given prefix and which do not contain
the character “/” after the given prefix.

Parameters:

    

**prefix** str

    
Returns:

    

AsyncIterator[str]

    

_async _list_prefix(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) ->
[collections.abc.AsyncGenerator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncGenerator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")]#

    

Retrieve all keys in the store that begin with a given prefix. Keys are
returned relative to the root of the store.

Parameters:

    

**prefix** str

    
Returns:

    

AsyncIterator[str]

    

log(_hint : Any = ''_) ->
[collections.abc.Generator](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator
"\(in Python
v3.13\)")[[None](https://docs.python.org/3/library/constants.html#None "\(in
Python v3.13\)"), [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)"),
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

    

Context manager to log method calls

Each call to the wrapped store is logged to the configured logger and added to
the counter dict.

_classmethod _open(_store_cls :
[type](https://docs.python.org/3/library/functions.html#type "\(in Python
v3.13\)")[T_Store]_, _* args: Any_, _** kwargs: Any_) -> Self#

    

Async:

    

Create and open the store.

Parameters:

    

***args** Any

    

Positional arguments to pass to the store constructor.

****kwargs** Any

    

Keyword arguments to pass to the store constructor.

Returns:

    

Store

    

The opened store instance.

_async _set(_key : [str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")_, _value : zarr.core.buffer.Buffer_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store a (key, value) pair.

Parameters:

    

**key** str

    
**value** Buffer

    

_async _set_if_not_exists(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_, _value : zarr.core.buffer.Buffer_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store a key to `value` if the key is not already present.

Parameters:

    

**key** str

    
**value** Buffer

    

_async _set_partial_values(

    _key_start_values : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), [bytes](https://docs.python.org/3/library/stdtypes.html#bytes "\(in Python v3.13\)") | [bytearray](https://docs.python.org/3/library/stdtypes.html#bytearray "\(in Python v3.13\)") | [memoryview](https://docs.python.org/3/library/stdtypes.html#memoryview "\(in Python v3.13\)")]]_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store values at a given key, starting at byte range_start.

Parameters:

    

**key_start_values** list[tuple[str, int, BytesLike]]

    

set of key, range_start, values triples, a key may occur multiple times with
different range_starts, range_starts (considering the length of the respective
values) must not specify overlapping ranges for the same key

_abstract _with_read_only(_read_only :
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)") = False_) -> Store#

    

Return a new store with a new read_only setting.

The new store points to the same location with the specified new read_only
state. The returned Store is not automatically opened, and this store is not
automatically closed.

Parameters:

    

**read_only**

    

If True, the store will be created in read-only mode. Defaults to False.

Returns:

    

A new store of the same type with the new read only attribute.

    

counter _:
[collections.defaultdict](https://docs.python.org/3/library/collections.html#collections.defaultdict
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")]_#

    

log_handler _ = None_#

    

log_level _ = 'DEBUG'_#

    

_property _read_only _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Is the store read-only?

_property _supports_consolidated_metadata _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support consolidated metadata?.

If it doesn’t an error will be raised on requests to consolidate the metadata.
Returning False can be useful for stores which implement their own
consolidation mechanism outside of the zarr-python implementation.

_property _supports_deletes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support deletes?

_property _supports_listing _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support listing?

_property _supports_partial_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support partial writes?

_property _supports_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support writes?

_class _zarr.storage.MemoryStore(

    _store_dict : [collections.abc.MutableMapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableMapping "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.buffer.Buffer] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _*_ ,
    _read_only : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
)#

    

Bases: `zarr.abc.store.Store`

Store for local memory.

Parameters:

    

**store_dict** dict

    

Initial data

**read_only** bool

    

Whether the store is read-only

Attributes:

    

**supports_writes**

    
**supports_deletes**

    
**supports_partial_writes**

    
**supports_listing**

    

_async _clear() ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Clear the store.

Remove all keys and values from the store.

close() -> [None](https://docs.python.org/3/library/constants.html#None "\(in
Python v3.13\)")#

    

Close the store.

_async _delete(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Remove a key from the store

Parameters:

    

**key** str

    

_async _delete_dir(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Remove all keys and prefixes in the store that begin with a given prefix.

_async _exists(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")#

    

Check if a key exists in the store.

Parameters:

    

**key** str

    
Returns:

    

bool

    

_async _get(

    _key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _prototype : zarr.core.buffer.BufferPrototype_,
    _byte_range : zarr.abc.store.ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")#
    

Retrieve the value associated with a given key.

Parameters:

    

**key** str

    
**prototype** BufferPrototype

    

The prototype of the output buffer. Stores may support a default buffer
prototype.

**byte_range** ByteRequest, optional

    

ByteRequest may be one of the following. If not provided, all data associated
with the key is retrieved. \- RangeByteRequest(int, int): Request a specific
range of bytes in the form (start, end). The end is exclusive. If the given
range is zero-length or starts after the end of the object, an error will be
returned. Additionally, if the range ends after the end of the object, the
entire remainder of the object will be returned. Otherwise, the exact
requested range will be returned. \- OffsetByteRequest(int): Request all bytes
starting from a given byte offset. This is equivalent to bytes={int}- as an
HTTP header. \- SuffixByteRequest(int): Request the last int bytes. Note that
here, int is the size of the request, not the byte offset. This is equivalent
to bytes=-{int} as an HTTP header.

Returns:

    

Buffer

    

_async _get_partial_values(

    _prototype : zarr.core.buffer.BufferPrototype_,
    _key_ranges : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.abc.store.ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]]_,
) -> [list](https://docs.python.org/3/library/stdtypes.html#list "\(in Python v3.13\)")[zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Retrieve possibly partial values from given key_ranges.

Parameters:

    

**prototype** BufferPrototype

    

The prototype of the output buffer. Stores may support a default buffer
prototype.

**key_ranges** Iterable[tuple[str, tuple[int | None, int | None]]]
    

Ordered set of key, range pairs, a key may occur multiple times with different
ranges

Returns:

    

list of values, in the order of the key_ranges, may contain null/none for
missing keys

    

_async _getsize(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")#

    

Return the size, in bytes, of a value in a Store.

Parameters:

    

**key** str

    
Returns:

    

**nbytes** int

    

The size of the value (in bytes).

Raises:

    

FileNotFoundError

    

When the given key does not exist in the store.

_async _getsize_prefix(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")#

    

Return the size, in bytes, of all values under a prefix.

Parameters:

    

**prefix** str

    

The prefix of the directory to measure.

Returns:

    

**nbytes** int

    

The sum of the sizes of the values in the directory (in bytes).

See also

`zarr.Array.nbytes_stored`

    
`Store.getsize`

    

Notes

`getsize_prefix` is just provided as a potentially faster alternative to
listing all the keys under a prefix calling `Store.getsize()` on each.

In general, `prefix` should be the path of an Array or Group in the Store.
Implementations may differ on the behavior when some other `prefix` is
provided.

_async _is_empty(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")#

    

Check if the directory is empty.

Parameters:

    

**prefix** str

    

Prefix of keys to check.

Returns:

    

bool

    

True if the store is empty, False otherwise.

_async _list() ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys in the store.

Returns:

    

AsyncIterator[str]

    

_async _list_dir(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys and prefixes with a given prefix and which do not contain
the character “/” after the given prefix.

Parameters:

    

**prefix** str

    
Returns:

    

AsyncIterator[str]

    

_async _list_prefix(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys in the store that begin with a given prefix. Keys are
returned relative to the root of the store.

Parameters:

    

**prefix** str

    
Returns:

    

AsyncIterator[str]

    

_classmethod _open(_* args: Any_, _** kwargs: Any_) -> Self#

    

Async:

    

Create and open the store.

Parameters:

    

***args** Any

    

Positional arguments to pass to the store constructor.

****kwargs** Any

    

Keyword arguments to pass to the store constructor.

Returns:

    

Store

    

The opened store instance.

_async _set(

    _key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _value : zarr.core.buffer.Buffer_,
    _byte_range : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store a (key, value) pair.

Parameters:

    

**key** str

    
**value** Buffer

    

_async _set_if_not_exists(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_, _value : zarr.core.buffer.Buffer_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store a key to `value` if the key is not already present.

Parameters:

    

**key** str

    
**value** Buffer

    

_abstract _set_partial_values(

    _key_start_values : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), [bytes](https://docs.python.org/3/library/stdtypes.html#bytes "\(in Python v3.13\)") | [bytearray](https://docs.python.org/3/library/stdtypes.html#bytearray "\(in Python v3.13\)") | [memoryview](https://docs.python.org/3/library/stdtypes.html#memoryview "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")]]]_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Async:

    

Store values at a given key, starting at byte range_start.

Parameters:

    

**key_start_values** list[tuple[str, int, BytesLike]]

    

set of key, range_start, values triples, a key may occur multiple times with
different range_starts, range_starts (considering the length of the respective
values) must not specify overlapping ranges for the same key

with_read_only(_read_only :
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)") = False_) -> MemoryStore#

    

Return a new store with a new read_only setting.

The new store points to the same location with the specified new read_only
state. The returned Store is not automatically opened, and this store is not
automatically closed.

Parameters:

    

**read_only**

    

If True, the store will be created in read-only mode. Defaults to False.

Returns:

    

A new store of the same type with the new read only attribute.

    

_property _read_only _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Is the store read-only?

_property _supports_consolidated_metadata _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support consolidated metadata?.

If it doesn’t an error will be raised on requests to consolidate the metadata.
Returning False can be useful for stores which implement their own
consolidation mechanism outside of the zarr-python implementation.

supports_deletes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = True_#

    

Does the store support deletes?

supports_listing _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = True_#

    

Does the store support listing?

supports_partial_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = True_#

    

Does the store support partial writes?

supports_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = True_#

    

Does the store support writes?

_class _zarr.storage.ObjectStore(_store : obstore.store.ObjectStore_, _*_ ,
_read_only : [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)") = False_)#

    

Bases: `zarr.abc.store.Store`

Store that uses obstore for fast read/write from AWS, GCP, Azure.

Parameters:

    

**store** obstore.store.ObjectStore

    

An obstore store instance that is set up with the proper credentials.

**read_only** bool

    

Whether to open the store in read-only mode.

Warning

ObjectStore is experimental and subject to API changes without notice. Please
raise an issue with any comments/concerns about the store.

_async _clear() ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Clear the store.

Remove all keys and values from the store.

close() -> [None](https://docs.python.org/3/library/constants.html#None "\(in
Python v3.13\)")#

    

Close the store.

_async _delete(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Remove a key from the store

Parameters:

    

**key** str

    

_async _delete_dir(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Remove all keys and prefixes in the store that begin with a given prefix.

_async _exists(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")#

    

Check if a key exists in the store.

Parameters:

    

**key** str

    
Returns:

    

bool

    

_async _get(

    _key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _prototype : zarr.core.buffer.BufferPrototype_,
    _byte_range : zarr.abc.store.ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")#
    

Retrieve the value associated with a given key.

Parameters:

    

**key** str

    
**prototype** BufferPrototype

    

The prototype of the output buffer. Stores may support a default buffer
prototype.

**byte_range** ByteRequest, optional

    

ByteRequest may be one of the following. If not provided, all data associated
with the key is retrieved. \- RangeByteRequest(int, int): Request a specific
range of bytes in the form (start, end). The end is exclusive. If the given
range is zero-length or starts after the end of the object, an error will be
returned. Additionally, if the range ends after the end of the object, the
entire remainder of the object will be returned. Otherwise, the exact
requested range will be returned. \- OffsetByteRequest(int): Request all bytes
starting from a given byte offset. This is equivalent to bytes={int}- as an
HTTP header. \- SuffixByteRequest(int): Request the last int bytes. Note that
here, int is the size of the request, not the byte offset. This is equivalent
to bytes=-{int} as an HTTP header.

Returns:

    

Buffer

    

_async _get_partial_values(

    _prototype : zarr.core.buffer.BufferPrototype_,
    _key_ranges : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.abc.store.ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]]_,
) -> [list](https://docs.python.org/3/library/stdtypes.html#list "\(in Python v3.13\)")[zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Retrieve possibly partial values from given key_ranges.

Parameters:

    

**prototype** BufferPrototype

    

The prototype of the output buffer. Stores may support a default buffer
prototype.

**key_ranges** Iterable[tuple[str, tuple[int | None, int | None]]]
    

Ordered set of key, range pairs, a key may occur multiple times with different
ranges

Returns:

    

list of values, in the order of the key_ranges, may contain null/none for
missing keys

    

_async _getsize(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")#

    

Return the size, in bytes, of a value in a Store.

Parameters:

    

**key** str

    
Returns:

    

**nbytes** int

    

The size of the value (in bytes).

Raises:

    

FileNotFoundError

    

When the given key does not exist in the store.

_async _getsize_prefix(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")#

    

Return the size, in bytes, of all values under a prefix.

Parameters:

    

**prefix** str

    

The prefix of the directory to measure.

Returns:

    

**nbytes** int

    

The sum of the sizes of the values in the directory (in bytes).

See also

`zarr.Array.nbytes_stored`

    
`Store.getsize`

    

Notes

`getsize_prefix` is just provided as a potentially faster alternative to
listing all the keys under a prefix calling `Store.getsize()` on each.

In general, `prefix` should be the path of an Array or Group in the Store.
Implementations may differ on the behavior when some other `prefix` is
provided.

_async _is_empty(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")#

    

Check if the directory is empty.

Parameters:

    

**prefix** str

    

Prefix of keys to check.

Returns:

    

bool

    

True if the store is empty, False otherwise.

list() ->
[collections.abc.AsyncGenerator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncGenerator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")]#

    

Retrieve all keys in the store.

Returns:

    

AsyncIterator[str]

    

list_dir(_prefix : [str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")_) ->
[collections.abc.AsyncGenerator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncGenerator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")]#

    

Retrieve all keys and prefixes with a given prefix and which do not contain
the character “/” after the given prefix.

Parameters:

    

**prefix** str

    
Returns:

    

AsyncIterator[str]

    

list_prefix(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) ->
[collections.abc.AsyncGenerator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncGenerator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")]#

    

Retrieve all keys in the store that begin with a given prefix. Keys are
returned relative to the root of the store.

Parameters:

    

**prefix** str

    
Returns:

    

AsyncIterator[str]

    

_classmethod _open(_* args: Any_, _** kwargs: Any_) -> Self#

    

Async:

    

Create and open the store.

Parameters:

    

***args** Any

    

Positional arguments to pass to the store constructor.

****kwargs** Any

    

Keyword arguments to pass to the store constructor.

Returns:

    

Store

    

The opened store instance.

_async _set(_key : [str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")_, _value : zarr.core.buffer.Buffer_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store a (key, value) pair.

Parameters:

    

**key** str

    
**value** Buffer

    

_async _set_if_not_exists(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_, _value : zarr.core.buffer.Buffer_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store a key to `value` if the key is not already present.

Parameters:

    

**key** str

    
**value** Buffer

    

_abstract _set_partial_values(

    _key_start_values : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), zarr.core.common.BytesLike]]_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Async:

    

Store values at a given key, starting at byte range_start.

Parameters:

    

**key_start_values** list[tuple[str, int, BytesLike]]

    

set of key, range_start, values triples, a key may occur multiple times with
different range_starts, range_starts (considering the length of the respective
values) must not specify overlapping ranges for the same key

with_read_only(_read_only :
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)") = False_) -> ObjectStore#

    

Return a new store with a new read_only setting.

The new store points to the same location with the specified new read_only
state. The returned Store is not automatically opened, and this store is not
automatically closed.

Parameters:

    

**read_only**

    

If True, the store will be created in read-only mode. Defaults to False.

Returns:

    

A new store of the same type with the new read only attribute.

    

_property _read_only _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Is the store read-only?

store _: obstore.store.ObjectStore_#

    

The underlying obstore instance.

_property _supports_consolidated_metadata _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support consolidated metadata?.

If it doesn’t an error will be raised on requests to consolidate the metadata.
Returning False can be useful for stores which implement their own
consolidation mechanism outside of the zarr-python implementation.

_property _supports_deletes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support deletes?

_property _supports_listing _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support listing?

_property _supports_partial_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support partial writes?

_property _supports_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support writes?

_class _zarr.storage.StorePath(_store : zarr.abc.store.Store_, _path :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)") = ''_)#

    

Path-like interface for a Store.

Parameters:

    

**store** Store

    

The store to use.

**path** str

    

The path within the store.

_async _delete() ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Delete the key from the store.

Raises:

    

NotImplementedError

    

If the store does not support deletion.

_async _delete_dir() ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Delete all keys with the given prefix from the store.

_async _exists() ->
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")#

    

Check if the key exists in the store.

Returns:

    

bool

    

True if the key exists in the store, False otherwise.

_async _get(

    _prototype : zarr.core.buffer.BufferPrototype | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _byte_range : zarr.abc.store.ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")#
    

Read bytes from the store.

Parameters:

    

**prototype** BufferPrototype, optional

    

The buffer prototype to use when reading the bytes.

**byte_range** ByteRequest, optional

    

The range of bytes to read.

Returns:

    

**buffer** Buffer or None

    

The read bytes, or None if the key does not exist.

_async _is_empty() ->
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")#

    

Check if any keys exist in the store with the given prefix.

Returns:

    

bool

    

True if no keys exist in the store with the given prefix, False otherwise.

_classmethod _open(

    _store : zarr.abc.store.Store_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _mode : zarr.core.common.AccessModeLiteral | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> Self#

    

Async:

    

Open StorePath based on the provided mode.

  * If the mode is None, return an opened version of the store with no changes.

  * If the mode is ‘r+’, ‘w-’, ‘w’, or ‘a’ and the store is read-only, raise a ValueError.

  * If the mode is ‘r’ and the store is not read-only, return a copy of the store with read_only set to True.

  * If the mode is ‘w-’ and the store is not read-only and the StorePath contains keys, raise a FileExistsError.

  * If the mode is ‘w’ and the store is not read-only, delete all keys nested within the StorePath.

Parameters:

    

**mode** AccessModeLiteral

    

The mode to use when initializing the store path.

The accepted values are:

  * `'r'`: read only (must exist)

  * `'r+'`: read/write (must exist)

  * `'a'`: read/write (create if doesn’t exist)

  * `'w'`: read/write (overwrite if exists)

  * `'w-'`: read/write (create if doesn’t exist).

Raises:

    

FileExistsError

    

If the mode is ‘w-’ and the store path already exists.

ValueError

    

If the mode is not “r” and the store is read-only, or

_async _set(

    _value : zarr.core.buffer.Buffer_,
    _byte_range : zarr.abc.store.ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Write bytes to the store.

Parameters:

    

**value** Buffer

    

The buffer to write.

**byte_range** ByteRequest, optional

    

The range of bytes to write. If None, the entire buffer is written.

Raises:

    

NotImplementedError

    

If byte_range is not None, because Store.set does not support partial writes
yet.

_async _set_if_not_exists(_default : zarr.core.buffer.Buffer_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store a key to `value` if the key is not already present.

Parameters:

    

**default** Buffer

    

The buffer to store if the key is not already present.

path _: [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_#

    

_property _read_only _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

store _: zarr.abc.store.Store_#

    

_class _zarr.storage.WrapperStore(_store : T_Store_)#

    

Bases: `zarr.abc.store.Store`, `Generic`[`T_Store`]

Store that wraps an existing Store.

By default all of the store methods are delegated to the wrapped store
instance, which is accessible via the `._store` attribute of this class.

Use this class to modify or extend the behavior of the other store classes.

_async _clear() ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Clear the store.

Remove all keys and values from the store.

close() -> [None](https://docs.python.org/3/library/constants.html#None "\(in
Python v3.13\)")#

    

Close the store.

_async _delete(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Remove a key from the store

Parameters:

    

**key** str

    

_async _delete_dir(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Remove all keys and prefixes in the store that begin with a given prefix.

_async _exists(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")#

    

Check if a key exists in the store.

Parameters:

    

**key** str

    
Returns:

    

bool

    

_async _get(

    _key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _prototype : zarr.core.buffer.BufferPrototype_,
    _byte_range : zarr.abc.store.ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")#
    

Retrieve the value associated with a given key.

Parameters:

    

**key** str

    
**prototype** BufferPrototype

    

The prototype of the output buffer. Stores may support a default buffer
prototype.

**byte_range** ByteRequest, optional

    

ByteRequest may be one of the following. If not provided, all data associated
with the key is retrieved. \- RangeByteRequest(int, int): Request a specific
range of bytes in the form (start, end). The end is exclusive. If the given
range is zero-length or starts after the end of the object, an error will be
returned. Additionally, if the range ends after the end of the object, the
entire remainder of the object will be returned. Otherwise, the exact
requested range will be returned. \- OffsetByteRequest(int): Request all bytes
starting from a given byte offset. This is equivalent to bytes={int}- as an
HTTP header. \- SuffixByteRequest(int): Request the last int bytes. Note that
here, int is the size of the request, not the byte offset. This is equivalent
to bytes=-{int} as an HTTP header.

Returns:

    

Buffer

    

_async _get_partial_values(

    _prototype : zarr.core.buffer.BufferPrototype_,
    _key_ranges : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.abc.store.ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]]_,
) -> [list](https://docs.python.org/3/library/stdtypes.html#list "\(in Python v3.13\)")[zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Retrieve possibly partial values from given key_ranges.

Parameters:

    

**prototype** BufferPrototype

    

The prototype of the output buffer. Stores may support a default buffer
prototype.

**key_ranges** Iterable[tuple[str, tuple[int | None, int | None]]]
    

Ordered set of key, range pairs, a key may occur multiple times with different
ranges

Returns:

    

list of values, in the order of the key_ranges, may contain null/none for
missing keys

    

_async _getsize(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")#

    

Return the size, in bytes, of a value in a Store.

Parameters:

    

**key** str

    
Returns:

    

**nbytes** int

    

The size of the value (in bytes).

Raises:

    

FileNotFoundError

    

When the given key does not exist in the store.

_async _getsize_prefix(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")#

    

Return the size, in bytes, of all values under a prefix.

Parameters:

    

**prefix** str

    

The prefix of the directory to measure.

Returns:

    

**nbytes** int

    

The sum of the sizes of the values in the directory (in bytes).

See also

`zarr.Array.nbytes_stored`

    
`Store.getsize`

    

Notes

`getsize_prefix` is just provided as a potentially faster alternative to
listing all the keys under a prefix calling `Store.getsize()` on each.

In general, `prefix` should be the path of an Array or Group in the Store.
Implementations may differ on the behavior when some other `prefix` is
provided.

_async _is_empty(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")#

    

Check if the directory is empty.

Parameters:

    

**prefix** str

    

Prefix of keys to check.

Returns:

    

bool

    

True if the store is empty, False otherwise.

list() ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys in the store.

Returns:

    

AsyncIterator[str]

    

list_dir(_prefix : [str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")_) ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys and prefixes with a given prefix and which do not contain
the character “/” after the given prefix.

Parameters:

    

**prefix** str

    
Returns:

    

AsyncIterator[str]

    

list_prefix(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys in the store that begin with a given prefix. Keys are
returned relative to the root of the store.

Parameters:

    

**prefix** str

    
Returns:

    

AsyncIterator[str]

    

_classmethod _open(_store_cls :
[type](https://docs.python.org/3/library/functions.html#type "\(in Python
v3.13\)")[T_Store]_, _* args: Any_, _** kwargs: Any_) -> Self#

    

Async:

    

Create and open the store.

Parameters:

    

***args** Any

    

Positional arguments to pass to the store constructor.

****kwargs** Any

    

Keyword arguments to pass to the store constructor.

Returns:

    

Store

    

The opened store instance.

_async _set(_key : [str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")_, _value : zarr.core.buffer.Buffer_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store a (key, value) pair.

Parameters:

    

**key** str

    
**value** Buffer

    

_async _set_if_not_exists(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_, _value : zarr.core.buffer.Buffer_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store a key to `value` if the key is not already present.

Parameters:

    

**key** str

    
**value** Buffer

    

_async _set_partial_values(

    _key_start_values : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), zarr.core.common.BytesLike]]_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store values at a given key, starting at byte range_start.

Parameters:

    

**key_start_values** list[tuple[str, int, BytesLike]]

    

set of key, range_start, values triples, a key may occur multiple times with
different range_starts, range_starts (considering the length of the respective
values) must not specify overlapping ranges for the same key

_abstract _with_read_only(_read_only :
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)") = False_) -> Store#

    

Return a new store with a new read_only setting.

The new store points to the same location with the specified new read_only
state. The returned Store is not automatically opened, and this store is not
automatically closed.

Parameters:

    

**read_only**

    

If True, the store will be created in read-only mode. Defaults to False.

Returns:

    

A new store of the same type with the new read only attribute.

    

_property _read_only _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Is the store read-only?

_property _supports_consolidated_metadata _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support consolidated metadata?.

If it doesn’t an error will be raised on requests to consolidate the metadata.
Returning False can be useful for stores which implement their own
consolidation mechanism outside of the zarr-python implementation.

_property _supports_deletes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support deletes?

_property _supports_listing _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support listing?

_property _supports_partial_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support partial writes?

_property _supports_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support writes?

_class _zarr.storage.ZipStore(

    _path : [pathlib.Path](https://docs.python.org/3/library/pathlib.html#pathlib.Path "\(in Python v3.13\)") | [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _*_ ,
    _mode : ZipStoreAccessModeLiteral = 'r'_,
    _read_only : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _compression : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") = zipfile.ZIP_STORED_,
    _allowZip64 : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = True_,
)#

    

Bases: `zarr.abc.store.Store`

Store using a ZIP file.

Parameters:

    

**path** str

    

Location of file.

**mode** str, optional

    

One of ‘r’ to read an existing file, ‘w’ to truncate and write a new file, ‘a’
to append to an existing file, or ‘x’ to exclusively create and write a new
file.

**compression** int, optional

    

Compression method to use when writing to the archive.

**allowZip64** bool, optional

    

If True (the default) will create ZIP files that use the ZIP64 extensions when
the zipfile is larger than 2 GiB. If False will raise an exception when the
ZIP file would require ZIP64 extensions.

Attributes:

    

**allowed_exceptions**

    
**supports_writes**

    
**supports_deletes**

    
**supports_partial_writes**

    
**supports_listing**

    
**path**

    
**compression**

    
**allowZip64**

    

_async _clear() ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Clear the store.

Remove all keys and values from the store.

close() -> [None](https://docs.python.org/3/library/constants.html#None "\(in
Python v3.13\)")#

    

Close the store.

_async _delete(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Remove a key from the store

Parameters:

    

**key** str

    

_async _delete_dir(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Remove all keys and prefixes in the store that begin with a given prefix.

_async _exists(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")#

    

Check if a key exists in the store.

Parameters:

    

**key** str

    
Returns:

    

bool

    

_async _get(

    _key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _prototype : zarr.core.buffer.BufferPrototype_,
    _byte_range : zarr.abc.store.ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")#
    

Retrieve the value associated with a given key.

Parameters:

    

**key** str

    
**prototype** BufferPrototype

    

The prototype of the output buffer. Stores may support a default buffer
prototype.

**byte_range** ByteRequest, optional

    

ByteRequest may be one of the following. If not provided, all data associated
with the key is retrieved. \- RangeByteRequest(int, int): Request a specific
range of bytes in the form (start, end). The end is exclusive. If the given
range is zero-length or starts after the end of the object, an error will be
returned. Additionally, if the range ends after the end of the object, the
entire remainder of the object will be returned. Otherwise, the exact
requested range will be returned. \- OffsetByteRequest(int): Request all bytes
starting from a given byte offset. This is equivalent to bytes={int}- as an
HTTP header. \- SuffixByteRequest(int): Request the last int bytes. Note that
here, int is the size of the request, not the byte offset. This is equivalent
to bytes=-{int} as an HTTP header.

Returns:

    

Buffer

    

_async _get_partial_values(

    _prototype : zarr.core.buffer.BufferPrototype_,
    _key_ranges : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.abc.store.ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]]_,
) -> [list](https://docs.python.org/3/library/stdtypes.html#list "\(in Python v3.13\)")[zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Retrieve possibly partial values from given key_ranges.

Parameters:

    

**prototype** BufferPrototype

    

The prototype of the output buffer. Stores may support a default buffer
prototype.

**key_ranges** Iterable[tuple[str, tuple[int | None, int | None]]]
    

Ordered set of key, range pairs, a key may occur multiple times with different
ranges

Returns:

    

list of values, in the order of the key_ranges, may contain null/none for
missing keys

    

_async _getsize(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")#

    

Return the size, in bytes, of a value in a Store.

Parameters:

    

**key** str

    
Returns:

    

**nbytes** int

    

The size of the value (in bytes).

Raises:

    

FileNotFoundError

    

When the given key does not exist in the store.

_async _getsize_prefix(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")#

    

Return the size, in bytes, of all values under a prefix.

Parameters:

    

**prefix** str

    

The prefix of the directory to measure.

Returns:

    

**nbytes** int

    

The sum of the sizes of the values in the directory (in bytes).

See also

`zarr.Array.nbytes_stored`

    
`Store.getsize`

    

Notes

`getsize_prefix` is just provided as a potentially faster alternative to
listing all the keys under a prefix calling `Store.getsize()` on each.

In general, `prefix` should be the path of an Array or Group in the Store.
Implementations may differ on the behavior when some other `prefix` is
provided.

_async _is_empty(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")#

    

Check if the directory is empty.

Parameters:

    

**prefix** str

    

Prefix of keys to check.

Returns:

    

bool

    

True if the store is empty, False otherwise.

_async _list() ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys in the store.

Returns:

    

AsyncIterator[str]

    

_async _list_dir(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys and prefixes with a given prefix and which do not contain
the character “/” after the given prefix.

Parameters:

    

**prefix** str

    
Returns:

    

AsyncIterator[str]

    

_async _list_prefix(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys in the store that begin with a given prefix. Keys are
returned relative to the root of the store.

Parameters:

    

**prefix** str

    
Returns:

    

AsyncIterator[str]

    

_async _move(_path : [pathlib.Path](https://docs.python.org/3/library/pathlib.html#pathlib.Path "\(in Python v3.13\)") | [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")#
    

Move the store to another path.

_classmethod _open(_* args: Any_, _** kwargs: Any_) -> Self#

    

Async:

    

Create and open the store.

Parameters:

    

***args** Any

    

Positional arguments to pass to the store constructor.

****kwargs** Any

    

Keyword arguments to pass to the store constructor.

Returns:

    

Store

    

The opened store instance.

_async _set(_key : [str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")_, _value : zarr.core.buffer.Buffer_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store a (key, value) pair.

Parameters:

    

**key** str

    
**value** Buffer

    

_async _set_if_not_exists(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_, _value : zarr.core.buffer.Buffer_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store a key to `value` if the key is not already present.

Parameters:

    

**key** str

    
**value** Buffer

    

_abstract _set_partial_values(

    _key_start_values : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), [bytes](https://docs.python.org/3/library/stdtypes.html#bytes "\(in Python v3.13\)") | [bytearray](https://docs.python.org/3/library/stdtypes.html#bytearray "\(in Python v3.13\)") | [memoryview](https://docs.python.org/3/library/stdtypes.html#memoryview "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")]]]_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Async:

    

Store values at a given key, starting at byte range_start.

Parameters:

    

**key_start_values** list[tuple[str, int, BytesLike]]

    

set of key, range_start, values triples, a key may occur multiple times with
different range_starts, range_starts (considering the length of the respective
values) must not specify overlapping ranges for the same key

_abstract _with_read_only(_read_only :
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)") = False_) -> Store#

    

Return a new store with a new read_only setting.

The new store points to the same location with the specified new read_only
state. The returned Store is not automatically opened, and this store is not
automatically closed.

Parameters:

    

**read_only**

    

If True, the store will be created in read-only mode. Defaults to False.

Returns:

    

A new store of the same type with the new read only attribute.

    

allowZip64 _: [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")_#

    

compression _: [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")_#

    

path _:
[pathlib.Path](https://docs.python.org/3/library/pathlib.html#pathlib.Path
"\(in Python v3.13\)")_#

    

_property _read_only _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Is the store read-only?

_property _supports_consolidated_metadata _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support consolidated metadata?.

If it doesn’t an error will be raised on requests to consolidate the metadata.
Returning False can be useful for stores which implement their own
consolidation mechanism outside of the zarr-python implementation.

supports_deletes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = False_#

    

Does the store support deletes?

supports_listing _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = True_#

    

Does the store support listing?

supports_partial_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = False_#

    

Does the store support partial writes?

supports_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = True_#

    

Does the store support writes?

zarr.storage.StoreLike _: TypeAlias_ _ = Store | StorePath | FSMap | Path | str | dict[str, Buffer]_#
    

#### zarr.testing#

##### Submodules#

###### zarr.testing.buffer#

###### Classes#

`NDBufferUsingTestNDArrayLike` | Example of a custom NDBuffer that handles MyNDArrayLike  
---|---  
`StoreExpectingTestBuffer` | Example of a custom Store that expect MyBuffer for all its non-metadata  
`TestBuffer` | Example of a custom Buffer that handles ArrayLike  
  
###### Module Contents#

_class _zarr.testing.buffer.NDBufferUsingTestNDArrayLike(_array :
zarr.core.buffer.core.NDArrayLike_)#

    

Bases: `zarr.core.buffer.cpu.NDBuffer`

Example of a custom NDBuffer that handles MyNDArrayLike

all_equal(_other : Any_, _equal_nan :
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)") = True_) ->
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")#

    

Compare to other using np.array_equal.

as_ndarray_like() -> NDArrayLike#

    

Returns the underlying array (host or device memory) of this buffer

This will never copy data.

Returns:

    

The underlying array such as a NumPy or CuPy array.

    

as_numpy_array() -> numpy.typing.NDArray[Any]#

    

Returns the buffer as a NumPy array (host memory).

Returns:

    

NumPy array of this buffer (might be a data copy)

    

Warning

Might have to copy data, consider using .as_ndarray_like() instead.

as_scalar() -> ScalarType#

    

Returns the buffer as a scalar value

astype(

    _dtype : numpy.typing.DTypeLike_,
    _order : Literal['K', 'A', 'C', 'F'] = 'K'_,
) -> Self#

    

copy() -> Self#

    

_classmethod _create(

    _*_ ,
    _shape : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")]_,
    _dtype : numpy.typing.DTypeLike_,
    _order : Literal['C', 'F'] = 'C'_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> Self#

    

Overwrite NDBuffer.create to create an TestNDArrayLike instance

_classmethod _empty(

    _shape : zarr.core.common.ChunkCoords_,
    _dtype : numpy.typing.DTypeLike_,
    _order : Literal['C', 'F'] = 'C'_,
) -> Self#

    

Create an empty buffer with the given shape, dtype, and order.

This method can be faster than `NDBuffer.create` because it doesn’t have to
initialize the memory used by the underlying ndarray-like object.

Parameters:

    

**shape**

    

The shape of the buffer and its underlying ndarray-like object

**dtype**

    

The datatype of the buffer and its underlying ndarray-like object

**order**

    

Whether to store multi-dimensional data in row-major (C-style) or column-major
(Fortran-style) order in memory.

Returns:

    

buffer

    

New buffer representing a new ndarray_like object with empty data.

See also

`NDBuffer.create`

    

Create a new buffer with some initial fill value.

fill(_value : Any_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_classmethod _from_ndarray_like(_ndarray_like : NDArrayLike_) -> Self#

    

Create a new buffer of a ndarray-like object

Parameters:

    

**ndarray_like**

    

ndarray-like object

Returns:

    

New buffer representing ndarray_like

    

_classmethod _from_numpy_array(_array_like : numpy.typing.ArrayLike_) -> Self#

    

Create a new buffer of Numpy array-like object

Parameters:

    

**array_like**

    

Object that can be coerced into a Numpy array

Returns:

    

New buffer representing array_like

    

reshape(_newshape : zarr.core.common.ChunkCoords | Literal[-1]_) -> Self#
    

squeeze(_axis : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple
"\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), Ellipsis]_) -> Self#

    

transpose(

    _axes : SupportsIndex | [collections.abc.Sequence](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "\(in Python v3.13\)")[SupportsIndex] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")_,
) -> Self#

    

_property _byteorder _: zarr.codecs.bytes.Endian_#

    

_property _dtype _:
[numpy.dtype](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype
"\(in NumPy v2.3\)")[Any]_#

    

_property _shape _:
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), Ellipsis]_#

    

_class _zarr.testing.buffer.StoreExpectingTestBuffer(

    _store_dict : [collections.abc.MutableMapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableMapping "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.buffer.Buffer] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _*_ ,
    _read_only : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
)#

    

Bases: `zarr.storage.MemoryStore`

Example of a custom Store that expect MyBuffer for all its non-metadata

We assume that keys containing “json” is metadata

_async _clear() ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Clear the store.

Remove all keys and values from the store.

close() -> [None](https://docs.python.org/3/library/constants.html#None "\(in
Python v3.13\)")#

    

Close the store.

_async _delete(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Remove a key from the store

Parameters:

    

**key** str

    

_async _delete_dir(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Remove all keys and prefixes in the store that begin with a given prefix.

_async _exists(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")#

    

Check if a key exists in the store.

Parameters:

    

**key** str

    
Returns:

    

bool

    

_async _get(

    _key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _prototype : zarr.core.buffer.BufferPrototype_,
    _byte_range : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")#
    

Retrieve the value associated with a given key.

Parameters:

    

**key** str

    
**prototype** BufferPrototype

    

The prototype of the output buffer. Stores may support a default buffer
prototype.

**byte_range** ByteRequest, optional

    

ByteRequest may be one of the following. If not provided, all data associated
with the key is retrieved. \- RangeByteRequest(int, int): Request a specific
range of bytes in the form (start, end). The end is exclusive. If the given
range is zero-length or starts after the end of the object, an error will be
returned. Additionally, if the range ends after the end of the object, the
entire remainder of the object will be returned. Otherwise, the exact
requested range will be returned. \- OffsetByteRequest(int): Request all bytes
starting from a given byte offset. This is equivalent to bytes={int}- as an
HTTP header. \- SuffixByteRequest(int): Request the last int bytes. Note that
here, int is the size of the request, not the byte offset. This is equivalent
to bytes=-{int} as an HTTP header.

Returns:

    

Buffer

    

_async _get_partial_values(

    _prototype : zarr.core.buffer.BufferPrototype_,
    _key_ranges : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.abc.store.ByteRequest | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]]_,
) -> [list](https://docs.python.org/3/library/stdtypes.html#list "\(in Python v3.13\)")[zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Retrieve possibly partial values from given key_ranges.

Parameters:

    

**prototype** BufferPrototype

    

The prototype of the output buffer. Stores may support a default buffer
prototype.

**key_ranges** Iterable[tuple[str, tuple[int | None, int | None]]]
    

Ordered set of key, range pairs, a key may occur multiple times with different
ranges

Returns:

    

list of values, in the order of the key_ranges, may contain null/none for
missing keys

    

_async _getsize(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")#

    

Return the size, in bytes, of a value in a Store.

Parameters:

    

**key** str

    
Returns:

    

**nbytes** int

    

The size of the value (in bytes).

Raises:

    

FileNotFoundError

    

When the given key does not exist in the store.

_async _getsize_prefix(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")#

    

Return the size, in bytes, of all values under a prefix.

Parameters:

    

**prefix** str

    

The prefix of the directory to measure.

Returns:

    

**nbytes** int

    

The sum of the sizes of the values in the directory (in bytes).

See also

`zarr.Array.nbytes_stored`

    
`Store.getsize`

    

Notes

`getsize_prefix` is just provided as a potentially faster alternative to
listing all the keys under a prefix calling `Store.getsize()` on each.

In general, `prefix` should be the path of an Array or Group in the Store.
Implementations may differ on the behavior when some other `prefix` is
provided.

_async _is_empty(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")#

    

Check if the directory is empty.

Parameters:

    

**prefix** str

    

Prefix of keys to check.

Returns:

    

bool

    

True if the store is empty, False otherwise.

_async _list() ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys in the store.

Returns:

    

AsyncIterator[str]

    

_async _list_dir(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys and prefixes with a given prefix and which do not contain
the character “/” after the given prefix.

Parameters:

    

**prefix** str

    
Returns:

    

AsyncIterator[str]

    

_async _list_prefix(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) ->
[collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")]#

    

Retrieve all keys in the store that begin with a given prefix. Keys are
returned relative to the root of the store.

Parameters:

    

**prefix** str

    
Returns:

    

AsyncIterator[str]

    

_classmethod _open(_* args: Any_, _** kwargs: Any_) -> Self#

    

Async:

    

Create and open the store.

Parameters:

    

***args** Any

    

Positional arguments to pass to the store constructor.

****kwargs** Any

    

Keyword arguments to pass to the store constructor.

Returns:

    

Store

    

The opened store instance.

_async _set(

    _key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _value : zarr.core.buffer.Buffer_,
    _byte_range : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store a (key, value) pair.

Parameters:

    

**key** str

    
**value** Buffer

    

_async _set_if_not_exists(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_, _value : zarr.core.buffer.Buffer_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Store a key to `value` if the key is not already present.

Parameters:

    

**key** str

    
**value** Buffer

    

_abstract _set_partial_values(

    _key_start_values : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), [bytes](https://docs.python.org/3/library/stdtypes.html#bytes "\(in Python v3.13\)") | [bytearray](https://docs.python.org/3/library/stdtypes.html#bytearray "\(in Python v3.13\)") | [memoryview](https://docs.python.org/3/library/stdtypes.html#memoryview "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")]]]_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Async:

    

Store values at a given key, starting at byte range_start.

Parameters:

    

**key_start_values** list[tuple[str, int, BytesLike]]

    

set of key, range_start, values triples, a key may occur multiple times with
different range_starts, range_starts (considering the length of the respective
values) must not specify overlapping ranges for the same key

with_read_only(_read_only :
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)") = False_) -> MemoryStore#

    

Return a new store with a new read_only setting.

The new store points to the same location with the specified new read_only
state. The returned Store is not automatically opened, and this store is not
automatically closed.

Parameters:

    

**read_only**

    

If True, the store will be created in read-only mode. Defaults to False.

Returns:

    

A new store of the same type with the new read only attribute.

    

_property _read_only _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Is the store read-only?

_property _supports_consolidated_metadata _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Does the store support consolidated metadata?.

If it doesn’t an error will be raised on requests to consolidate the metadata.
Returning False can be useful for stores which implement their own
consolidation mechanism outside of the zarr-python implementation.

supports_deletes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = True_#

    

Does the store support deletes?

supports_listing _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = True_#

    

Does the store support listing?

supports_partial_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = True_#

    

Does the store support partial writes?

supports_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_ _ = True_#

    

Does the store support writes?

_class _zarr.testing.buffer.TestBuffer(_array_like :
zarr.core.buffer.core.ArrayLike_)#

    

Bases: `zarr.core.buffer.cpu.Buffer`

Example of a custom Buffer that handles ArrayLike

as_array_like() -> ArrayLike#

    

Returns the underlying array (host or device memory) of this buffer

This will never copy data.

Returns:

    

The underlying 1d array such as a NumPy or CuPy array.

    

as_buffer_like() -> zarr.core.common.BytesLike#

    

Returns the buffer as an object that implements the Python buffer protocol.

Returns:

    

An object that implements the Python buffer protocol

    

Notes

Might have to copy data, since the implementation uses .as_numpy_array().

as_numpy_array() -> numpy.typing.NDArray[Any]#

    

Returns the buffer as a NumPy array (host memory).

Returns:

    

NumPy array of this buffer (might be a data copy)

    

Notes

Might have to copy data, consider using .as_array_like() instead.

_classmethod _create_zero_length() -> Self#

    

Create an empty buffer with length zero

Returns:

    

New empty 0-length buffer

    

_classmethod _from_array_like(_array_like : ArrayLike_) -> Self#

    

Create a new buffer of an array-like object

Parameters:

    

**array_like**

    

array-like object that must be 1-dim, contiguous, and byte dtype.

Returns:

    

New buffer representing array_like

    

_classmethod _from_buffer(_buffer : zarr.core.buffer.core.Buffer_) -> Self#

    

Create a new buffer of an existing Buffer

This is useful if you want to ensure that an existing buffer is of the correct
subclass of Buffer. E.g., MemoryStore uses this to return a buffer instance of
the subclass specified by its BufferPrototype argument.

Typically, this only copies data if the data has to be moved between memory
types, such as from host to device memory.

Parameters:

    

**buffer**

    

buffer object.

Returns:

    

A new buffer representing the content of the input buffer

    

Notes

Subclasses of Buffer must override this method to implement more optimal
conversions that avoid copies where possible

_classmethod _from_bytes(_bytes_like : zarr.core.common.BytesLike_) -> Self#

    

Create a new buffer of a bytes-like object (host memory)

Parameters:

    

**bytes_like**

    

bytes-like object

Returns:

    

New buffer representing bytes_like

    

to_bytes() -> [bytes](https://docs.python.org/3/library/stdtypes.html#bytes
"\(in Python v3.13\)")#

    

Returns the buffer as bytes (host memory).

Returns:

    

bytes of this buffer (data copy)

    

Warning

Will always copy data, only use this method for small buffers such as metadata
buffers. If possible, use .as_numpy_array() or .as_array_like() instead.

###### zarr.testing.conftest#

###### Functions#

`pytest_configure`(→ None) |   
---|---  
  
###### Module Contents#

zarr.testing.conftest.pytest_configure(_config : pytest.Config_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

###### zarr.testing.stateful#

###### Attributes#

`F` |   
---|---  
`MAX_BINARY_SIZE` |   
  
###### Classes#

`SyncStoreWrapper` |   
---|---  
`ZarrHierarchyStateMachine` | This state machine models operations that modify a zarr store's  
`ZarrStoreStateMachine` |   
  
###### Functions#

`split_prefix_name`(→ tuple[str, str]) |   
---|---  
`with_frequency`(→ collections.abc.Callable[[F], F]) | This needs to be deterministic for hypothesis replaying  
  
###### Module Contents#

_class _zarr.testing.stateful.SyncStoreWrapper(_store :
zarr.abc.store.Store_)#

    

Bases: `zarr.core.sync.SyncMixin`

clear() -> [None](https://docs.python.org/3/library/constants.html#None "\(in
Python v3.13\)")#

    

delete(_path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

exists(_key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")_) ->
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")#

    

get(

    _key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _prototype : zarr.core.buffer.BufferPrototype_,
) -> zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")#
    

get_partial_values(

    _key_ranges : [list](https://docs.python.org/3/library/stdtypes.html#list "\(in Python v3.13\)")[Any]_,
    _prototype : zarr.core.buffer.BufferPrototype_,
) -> [list](https://docs.python.org/3/library/stdtypes.html#list "\(in Python v3.13\)")[zarr.core.buffer.Buffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

is_empty(_prefix : [str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")_) ->
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")#

    

list() -> [list](https://docs.python.org/3/library/stdtypes.html#list "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")]#

    

_abstract _list_dir(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

_abstract _list_prefix(_prefix :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

set(_key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")_, _data_buffer : zarr.core.buffer.Buffer_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_abstract _set_partial_values(_key_start_values : Any_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_property _read_only _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

store#

    

_property _supports_deletes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

_property _supports_listing _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

_property _supports_partial_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

_property _supports_writes _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

_class _zarr.testing.stateful.ZarrHierarchyStateMachine(_store :
zarr.abc.store.Store_)#

    

Bases: `zarr.core.sync.SyncMixin`, `hypothesis.stateful.RuleBasedStateMachine`

This state machine models operations that modify a zarr store’s hierarchy.
That is, user actions that modify arrays/groups as well as list operations. It
is intended to be used by external stores, and compares their results to a
MemoryStore that is assumed to be perfect.

add_array(

    _data : hypothesis.strategies.DataObject_,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _array_and_chunks : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "\(in NumPy v2.3\)")[Any, Any], [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), Ellipsis]]_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

add_group(_name : [str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")_, _data : hypothesis.strategies.DataObject_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

can_add(_path : [str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")_) ->
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")#

    

check_array(_data : hypothesis.strategies.DataObject_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

check_list_dir(_data : hypothesis.strategies.DataObject_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

check_list_prefix_from_root() ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

clear() -> [None](https://docs.python.org/3/library/constants.html#None "\(in
Python v3.13\)")#

    

delete_array_using_del(_data : hypothesis.strategies.DataObject_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

delete_chunk(_data : hypothesis.strategies.DataObject_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

delete_dir(_data : hypothesis.strategies.DataObject_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

delete_group_using_del(_data : hypothesis.strategies.DataObject_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

draw_directory(_data : hypothesis.strategies.DataObject_) ->
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")#

    

init_store() -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

overwrite_array_basic_indexing(_data : hypothesis.strategies.DataObject_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

overwrite_array_orthogonal_indexing(

    _data : hypothesis.strategies.DataObject_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

resize_array(_data : hypothesis.strategies.DataObject_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

all_arrays _: [set](https://docs.python.org/3/library/stdtypes.html#set "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")]_#

    

all_groups _: [set](https://docs.python.org/3/library/stdtypes.html#set "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")]_#

    

model#

    

store#

    

_class _zarr.testing.stateful.ZarrStoreStateMachine(_store :
zarr.abc.store.Store_)#

    

Bases: `hypothesis.stateful.RuleBasedStateMachine`

” Zarr store state machine

> This is a subclass of a Hypothesis RuleBasedStateMachine. It is testing a
> framework to ensure that the state of a Zarr store matches an expected state
> after a set of random operations. It contains a store (currently, a Zarr
> MemoryStore) and a model, a simplified version of a zarr store (in this
> case, a dict). It also contains rules which represent actions that can be
> applied to a zarr store. Rules apply an action to both the store and the
> model, and invariants assert that the state of the model is equal to the
> state of the store. Hypothesis then generates sequences of rules, running
> invariants after each rule. It raises an error if a sequence produces
> discontinuity between state of the model and state of the store (ie. an
> invariant is violated).
> <https://hypothesis.readthedocs.io/en/latest/stateful.html>

check_num_zarr_keys_equal() ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

check_paths_equal() ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

check_vals_equal() ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

check_zarr_keys() ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

clear() -> [None](https://docs.python.org/3/library/constants.html#None "\(in
Python v3.13\)")#

    

delete(_data : hypothesis.strategies.DataObject_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

exists(_key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

get(_key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")_, _data : hypothesis.strategies.DataObject_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

get_invalid_zarr_keys(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_, _data : hypothesis.strategies.DataObject_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

get_partial_values(_data : hypothesis.strategies.DataObject_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

init_store() -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

is_empty() -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

set(_key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")_, _data :
[bytes](https://docs.python.org/3/library/stdtypes.html#bytes "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

model _: [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"), zarr.core.buffer.Buffer]_#

    

prototype#

    

store#

    

zarr.testing.stateful.split_prefix_name(_path :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [tuple](https://docs.python.org/3/library/stdtypes.html#tuple
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), [str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")]#

    

zarr.testing.stateful.with_frequency(_frequency :
[float](https://docs.python.org/3/library/functions.html#float "\(in Python
v3.13\)")_) ->
[collections.abc.Callable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable
"\(in Python v3.13\)")[[F], F]#

    

This needs to be deterministic for hypothesis replaying

zarr.testing.stateful.F#

    

zarr.testing.stateful.MAX_BINARY_SIZE _ = 100_#

    

###### zarr.testing.store#

###### Classes#

`StoreTests` |   
---|---  
  
###### Module Contents#

_class _zarr.testing.store.StoreTests#

    

Bases: `Generic`[`S`, `B`]

_abstract _get(_store : S_, _key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> zarr.core.buffer.Buffer#

    

Async:

    

Retrieve a value from a storage backend, by key. This should not use any store
methods. Bypassing the store methods allows them to be tested.

open_kwargs(_store_kwargs :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), Any]_) ->
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), Any]#

    

_abstract _set(_store : S_, _key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_, _value : zarr.core.buffer.Buffer_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Async:

    

Insert a value into a storage backend, with a specific key. This should not
use any store methods. Bypassing the store methods allows them to be tested.

_async _store(_open_kwargs :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), Any]_) -> zarr.abc.store.Store#

    

_abstract _store_kwargs(_* args: Any_, _** kwargs: Any_) ->
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), Any]#

    

Kwargs for instantiating a store

_async _store_not_open(_store_kwargs :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), Any]_) -> zarr.abc.store.Store#

    

_async _test_clear(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_async _test_delete(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_async _test_delete_dir(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_async _test_delete_nonexistent_key_does_not_raise(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_async _test_exists(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_async _test_get(

    _store : S_,
    _key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _data : [bytes](https://docs.python.org/3/library/stdtypes.html#bytes "\(in Python v3.13\)")_,
    _byte_range : zarr.abc.store.ByteRequest_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Ensure that data can be read from the store using the store.get method.

_async _test_get_many(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Ensure that multiple keys can be retrieved at once with the _get_many method.

_async _test_get_not_open(_store_not_open : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Ensure that data can be read from the store that isn’t yet open using the
store.get method.

_async _test_get_partial_values(

    _store : S_,
    _key_ranges : [list](https://docs.python.org/3/library/stdtypes.html#list "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.abc.store.ByteRequest]]_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_async _test_get_raises(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Ensure that a ValueError is raise for invalid byte range syntax

_async _test_getsize(_store : S_, _key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_, _data :
[bytes](https://docs.python.org/3/library/stdtypes.html#bytes "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Test the result of store.getsize().

_async _test_getsize_prefix(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Test the result of store.getsize_prefix().

_async _test_getsize_raises(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Test that getsize() raise a FileNotFoundError if the key doesn’t exist.

_async _test_is_empty(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_async _test_list(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_async _test_list_dir(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_async _test_list_empty_path(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Verify that list and list_prefix work correctly when path is an empty string,
i.e. no unwanted replacement occurs.

_async _test_list_prefix(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Test that the list_prefix method works as intended. Given a prefix, it should
return all the keys in storage that start with this prefix.

_async _test_read_only_store_raises(_open_kwargs :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), Any]_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_async _test_serializable_store(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_async _test_set(_store : S_, _key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_, _data :
[bytes](https://docs.python.org/3/library/stdtypes.html#bytes "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Ensure that data can be written to the store using the store.set method.

_async _test_set_if_not_exists(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_async _test_set_many(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Test that a dict of key : value pairs can be inserted into the store via the
_set_many method.

_async _test_set_not_open(_store_not_open : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Ensure that data can be written to the store that’s not yet open using the
store.set method.

_async _test_store_context_manager(_open_kwargs :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), Any]_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

test_store_eq(_store : S_, _store_kwargs :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), Any]_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_async _test_store_open_read_only(_open_kwargs :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), Any]_, _read_only :
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

test_store_read_only(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_abstract _test_store_repr(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_abstract _test_store_supports_listing(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_abstract _test_store_supports_partial_writes(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_abstract _test_store_supports_writes(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

test_store_type(_store : S_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

_async _test_with_read_only_store(_open_kwargs :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), Any]_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

buffer_cls _: [type](https://docs.python.org/3/library/functions.html#type
"\(in Python v3.13\)")[B]_#

    

store_cls _: [type](https://docs.python.org/3/library/functions.html#type
"\(in Python v3.13\)")[S]_#

    

###### zarr.testing.strategies#

###### Attributes#

`array_names` |   
---|---  
`array_shapes` |   
`attrs` |   
`compressors` |   
`node_names` |   
`short_node_names` |   
`stores` |   
`zarr_formats` |   
`zarr_key_chars` |   
  
###### Functions#

`array_metadata`(...) |   
---|---  
`arrays`(, array_names, arrays, attrs, zarr_formats) |   
`basic_indices`(→ Any) | Basic indices without unsupported negative slices.  
`chunk_paths`(→ str) |   
`chunk_shapes`(→ tuple[int, Ellipsis]) |   
`clear_store`(→ zarr.abc.store.Store) |   
`dimension_names`(→ list[None | str] | None) |   
`dtypes`(...) |   
`end_slices`(→ Any) | A strategy that slices ranges that include the last chunk.  
`is_negative_slice`(→ bool) |   
`key_ranges`(...) | Function to generate key_ranges strategy for get_partial_values()  
`keys`(→ str) |   
`np_array_and_chunks`() → tuple[numpy.ndarray, ...) | A hypothesis strategy to generate small sized random arrays.  
`numpy_arrays`(→ numpy.typing.NDArray[Any]) | Generate numpy arrays that can be saved in the provided Zarr format.  
`orthogonal_indices`(→ tuple[tuple[numpy.ndarray[Any, ...) | Strategy that returns  
`paths`(→ str) |   
`safe_unicode_for_dtype`(...) | Generate UTF-8-safe text constrained to max_len of dtype.  
`shard_shapes`(→ tuple[int, Ellipsis]) |   
`simple_arrays`(→ Any) |   
`v2_dtypes`(...) |   
`v3_dtypes`(...) |   
  
###### Module Contents#

zarr.testing.strategies.array_metadata(

    _*_ ,
    _array_shapes : [collections.abc.Callable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "\(in Python v3.13\)")[Ellipsis, hypothesis.strategies.SearchStrategy[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), Ellipsis]]] = npst.array_shapes_,
    _zarr_formats : hypothesis.strategies.SearchStrategy[Literal[2, 3]] = zarr_formats_,
    _attributes : hypothesis.strategies.SearchStrategy[[collections.abc.Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")] = attrs_,
) -> zarr.core.metadata.ArrayV2Metadata | zarr.core.metadata.ArrayV3Metadata#
    

zarr.testing.strategies.arrays(

    _*_ ,
    _shapes : hypothesis.strategies.SearchStrategy[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), Ellipsis]] = array_shapes_,
    _compressors : hypothesis.strategies.SearchStrategy = compressors_,
    _stores : hypothesis.strategies.SearchStrategy[zarr.storage.StoreLike] = stores_,
    _paths : hypothesis.strategies.SearchStrategy[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")] = paths()_,
    _array_names : hypothesis.strategies.SearchStrategy = array_names_,
    _arrays : hypothesis.strategies.SearchStrategy | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _attrs : hypothesis.strategies.SearchStrategy = attrs_,
    _zarr_formats : hypothesis.strategies.SearchStrategy = zarr_formats_,
) -> zarr.core.array.Array#

    

zarr.testing.strategies.basic_indices(

    _*_ ,
    _shape : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), Ellipsis]_,
    _min_dims : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") = 0_,
    _max_dims : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _allow_newaxis : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _allow_ellipsis : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = True_,
) -> Any#

    

Basic indices without unsupported negative slices.

zarr.testing.strategies.chunk_paths(

    _ndim : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")_,
    _numblocks : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), Ellipsis]_,
    _subset : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = True_,
) -> [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")#

    

zarr.testing.strategies.chunk_shapes(_*_ , _shape :
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), Ellipsis]_) ->
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), Ellipsis]#

    

zarr.testing.strategies.clear_store(_x : zarr.abc.store.Store_) ->
zarr.abc.store.Store#

    

zarr.testing.strategies.dimension_names(_*_ , _ndim : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_) -> [list](https://docs.python.org/3/library/stdtypes.html#list "\(in Python v3.13\)")[[None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") | [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")#
    

zarr.testing.strategies.dtypes() ->
hypothesis.strategies.SearchStrategy[[numpy.dtype](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype
"\(in NumPy v2.3\)")[Any]]#

    

zarr.testing.strategies.end_slices(_*_ , _shape :
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), Ellipsis]_) -> Any#

    

A strategy that slices ranges that include the last chunk. This is intended to
stress-test handling of a possibly smaller last chunk.

zarr.testing.strategies.is_negative_slice(_idx : Any_) ->
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")#

    

zarr.testing.strategies.key_ranges(

    _keys : hypothesis.strategies.SearchStrategy[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")] = node_names_,
    _max_size : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") = sys.maxsize_,
) ->
hypothesis.strategies.SearchStrategy[[list](https://docs.python.org/3/library/stdtypes.html#list
"\(in Python
v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"), zarr.abc.store.RangeByteRequest]]]#

    

Function to generate key_ranges strategy for get_partial_values() returns list
strategy w/ form:

    
    
    [(key, (range_start, range_end)),
     (key, (range_start, range_end)),...]
    

zarr.testing.strategies.keys(_*_ , _max_num_nodes : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_) -> [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")#
    

zarr.testing.strategies.np_array_and_chunks(

    _*_ ,
    _arrays : hypothesis.strategies.SearchStrategy[numpy.typing.NDArray[Any]] = numpy_arrays()_,
) -> [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in
Python
v3.13\)")[[numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray
"\(in NumPy v2.3\)"),
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), Ellipsis]]#

    

A hypothesis strategy to generate small sized random arrays.

Returns: a tuple of the array and a suitable random chunking for it.

zarr.testing.strategies.numpy_arrays(

    _*_ ,
    _shapes : hypothesis.strategies.SearchStrategy[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), Ellipsis]] = array_shapes_,
    _dtype : [numpy.dtype](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype "\(in NumPy v2.3\)")[Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> numpy.typing.NDArray[Any]#

    

Generate numpy arrays that can be saved in the provided Zarr format.

zarr.testing.strategies.orthogonal_indices(

    _*_ ,
    _shape : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), Ellipsis]_,
) -> [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in
Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple
"\(in Python
v3.13\)")[[numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray
"\(in NumPy v2.3\)")[Any, Any], Ellipsis],
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray
"\(in NumPy v2.3\)")[Any, Any], Ellipsis]]#

    

Strategy that returns (1) a tuple of integer arrays used for orthogonal
indexing of Zarr arrays. (2) an tuple of integer arrays that can be used for
equivalent indexing of numpy arrays

zarr.testing.strategies.paths(_*_ , _max_num_nodes : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_) -> [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")#
    

zarr.testing.strategies.safe_unicode_for_dtype(

    _dtype : [numpy.dtype](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype "\(in NumPy v2.3\)")[[numpy.str_](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.str_ "\(in NumPy v2.3\)")]_,
) ->
hypothesis.strategies.SearchStrategy[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")]#

    

Generate UTF-8-safe text constrained to max_len of dtype.

zarr.testing.strategies.shard_shapes(

    _*_ ,
    _shape : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), Ellipsis]_,
    _chunk_shape : [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), Ellipsis]_,
) -> [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in
Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)"), Ellipsis]#

    

zarr.testing.strategies.simple_arrays(

    _*_ ,
    _shapes : hypothesis.strategies.SearchStrategy[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)"), Ellipsis]] = array_shapes_,
) -> Any#

    

zarr.testing.strategies.v2_dtypes() ->
hypothesis.strategies.SearchStrategy[[numpy.dtype](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype
"\(in NumPy v2.3\)")[Any]]#

    

zarr.testing.strategies.v3_dtypes() ->
hypothesis.strategies.SearchStrategy[[numpy.dtype](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype
"\(in NumPy v2.3\)")[Any]]#

    

zarr.testing.strategies.array_names#

    

zarr.testing.strategies.array_shapes#

    

zarr.testing.strategies.attrs _: hypothesis.strategies.SearchStrategy[[collections.abc.Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]_#
    

zarr.testing.strategies.compressors#

    

zarr.testing.strategies.node_names#

    

zarr.testing.strategies.short_node_names#

    

zarr.testing.strategies.stores#

    

zarr.testing.strategies.zarr_formats _:
hypothesis.strategies.SearchStrategy[zarr.core.common.ZarrFormat]_#

    

zarr.testing.strategies.zarr_key_chars#

    

###### zarr.testing.utils#

###### Functions#

`assert_bytes_equal`(→ None) | Help function to assert if two bytes-like or Buffers are equal  
---|---  
  
###### Module Contents#

zarr.testing.utils.assert_bytes_equal(

    _b1 : zarr.core.buffer.Buffer | zarr.core.common.BytesLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")_,
    _b2 : zarr.core.buffer.Buffer | zarr.core.common.BytesLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Help function to assert if two bytes-like or Buffers are equal

Warning

Always copies data, only use for testing and debugging

##### Functions#

`assert_bytes_equal`(→ None) | Help function to assert if two bytes-like or Buffers are equal  
---|---  
  
##### Package Contents#

zarr.testing.assert_bytes_equal(

    _b1 : zarr.core.buffer.Buffer | zarr.core.common.BytesLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")_,
    _b2 : zarr.core.buffer.Buffer | zarr.core.common.BytesLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Help function to assert if two bytes-like or Buffers are equal

Warning

Always copies data, only use for testing and debugging

### Attributes#

`config` |   
---|---  
  
### Classes#

`Array` | A Zarr array.  
---|---  
`AsyncArray` | An asynchronous array class representing a chunked array stored in a Zarr store.  
`AsyncGroup` | Asynchronous Group object.  
`Group` | A Zarr group.  
  
### Functions#

`array`(→ zarr.core.array.Array) | Create an array filled with data.  
---|---  
`consolidate_metadata`(→ zarr.core.group.Group) | Consolidate the metadata of all nodes in a hierarchy.  
`copy`(→ tuple[int, int, int]) |   
`copy_all`(→ tuple[int, int, int]) |   
`copy_store`(→ tuple[int, int, int]) |   
`create`(→ zarr.core.array.Array) | Create an array.  
`create_array`(→ zarr.core.array.Array) | Create an array.  
`create_group`(→ zarr.core.group.Group) | Create a group.  
`create_hierarchy`(→ collections.abc.Iterator[tuple[str, ...) | Create a complete zarr hierarchy from a collection of metadata objects.  
`empty`(→ zarr.core.array.Array) | Create an empty array with the specified shape. The contents will be filled with the  
`empty_like`(→ zarr.core.array.Array) | Create an empty array like another array. The contents will be filled with the  
`from_array`(→ zarr.core.array.Array) | Create an array from an existing array or array-like.  
`full`(→ zarr.core.array.Array) | Create an array with a default fill value.  
`full_like`(→ zarr.core.array.Array) | Create a filled array like another array.  
`group`(→ zarr.core.group.Group) | Create a group.  
`load`(...) | Load data from an array or group into memory.  
`ones`(→ zarr.core.array.Array) | Create an array with a fill value of one.  
`ones_like`(→ zarr.core.array.Array) | Create an array of ones like another array.  
`open`(→ zarr.core.array.Array | zarr.core.group.Group) | Open a group or array using file-mode-like semantics.  
`open_array`(→ zarr.core.array.Array) | Open an array using file-mode-like semantics.  
`open_consolidated`(→ zarr.core.group.Group) | Alias for `open_group()` with `use_consolidated=True`.  
`open_group`(→ zarr.core.group.Group) | Open a group using file-mode-like semantics.  
`open_like`(→ zarr.core.array.Array) | Open a persistent array like another array.  
`print_debug_info`(→ None) | Print version info for use in bug reports.  
`save`(→ None) | Save an array or group of arrays to the local file system.  
`save_array`(→ None) | Save a NumPy array to the local file system.  
`save_group`(→ None) | Save several NumPy arrays to the local file system.  
`tree`(→ Any) | Provide a rich display of the hierarchy.  
`zeros`(→ zarr.core.array.Array) | Create an array with a fill value of zero.  
`zeros_like`(→ zarr.core.array.Array) | Create an array of zeros like another array.  
  
### Package Contents#

_class _zarr.Array#

    

A Zarr array.

append(

    _data : numpy.typing.ArrayLike_,
    _axis : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") = 0_,
) -> zarr.core.common.ChunkCoords#

    

Append data to axis.

Parameters:

    

**data** array-like

    

Data to be appended.

**axis** int

    

Axis along which to append.

Returns:

    

**new_shape** tuple

    

Notes

The size of all dimensions other than axis must match between this array and
data.

Examples

    
    
    >>> import numpy as np
    >>> import zarr
    >>> a = np.arange(10000000, dtype='i4').reshape(10000, 1000)
    >>> z = zarr.array(a, chunks=(1000, 100))
    >>> z.shape
    (10000, 1000)
    >>> z.append(a)
    (20000, 1000)
    >>> z.append(np.vstack([a, a]), axis=1)
    (20000, 2000)
    >>> z.shape
    (20000, 2000)
    

_classmethod _create(

    _store : zarr.storage.StoreLike_,
    _*_ ,
    _shape : zarr.core.common.ChunkCoords_,
    _dtype : zarr.core.dtype.ZDTypeLike_,
    _zarr_format : zarr.core.common.ZarrFormat = 3_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = DEFAULT_FILL_VALUE_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_shape : zarr.core.common.ChunkCoords | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_key_encoding : zarr.core.chunk_key_encodings.ChunkKeyEncoding | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[Literal['default'], Literal['.', '/']] | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[Literal['v2'], Literal['.', '/']] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _codecs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[zarr.abc.codec.Codec | [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON]] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_names : zarr.core.common.DimensionNames = None_,
    _chunks : zarr.core.common.ChunkCoords | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_separator : Literal['.', '/'] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _order : zarr.core.common.MemoryOrder | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _filters : [list](https://docs.python.org/3/library/stdtypes.html#list "\(in Python v3.13\)")[[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON]] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _compressor : CompressorLike = 'auto'_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _config : zarr.core.array_spec.ArrayConfigLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> Array#

    

Creates a new Array instance from an initialized store.

Deprecated since version 3.0.0: Deprecated in favor of `zarr.create_array()`.

Parameters:

    

**store** StoreLike

    

The array store that has already been initialized.

**shape** ChunkCoords

    

The shape of the array.

**dtype** ZDTypeLike

    

The data type of the array.

**chunk_shape** ChunkCoords, optional

    

The shape of the Array’s chunks. Zarr format 3 only. Zarr format 2 arrays
should use chunks instead. If not specified, default are guessed based on the
shape and dtype.

**chunk_key_encoding** ChunkKeyEncodingLike, 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. The elements of this
collection 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:

  * For numeric arrays, the default is `BytesCodec` and `ZstdCodec`.

  * For Unicode strings, the default is `VLenUTF8Codec` and `ZstdCodec`.

  * For bytes or objects, the default is `VLenBytesCodec` and `ZstdCodec`.

These defaults can be changed by modifying the value of
`array.v3_default_filters`, `array.v3_default_serializer` and
`array.v3_default_compressors` in `zarr.core.config`.

**dimension_names** Iterable[str | None], optional
    

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

**chunks** ChunkCoords, optional

    

The shape of the array’s chunks. Zarr format 2 only. Zarr format 3 arrays
should use `chunk_shape` instead. If not specified, default are guessed based
on the shape and dtype.

**dimension_separator** Literal[“.”, “/”], optional

    

The dimension separator (default is “.”). Zarr format 2 only. Zarr format 3
arrays should use `chunk_key_encoding` instead.

**order** Literal[“C”, “F”], optional

    

The memory of the array (default is “C”). If `zarr_format` is 2, this
parameter sets the memory order of the array. If zarr_format` is 3, then this
parameter is deprecated, because memory order is a runtime parameter for Zarr
3 arrays. The recommended way to specify the memory order for Zarr 3 arrays is
via the `config` parameter, e.g. `{'order': 'C'}`.

**filters** list[dict[str, JSON]], optional

    

Sequence of filters to use to encode chunk data prior to compression. Zarr
format 2 only. Zarr format 3 arrays should use `codecs` instead. If no
`filters` are provided, a default set of filters will be used. These defaults
can be changed by modifying the value of `array.v2_default_filters` in
`zarr.core.config`.

**compressor** dict[str, JSON], optional

    

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

If no `compressor` is provided, a default compressor will be used:

  * For numeric arrays, the default is `ZstdCodec`.

  * For Unicode strings, the default is `VLenUTF8Codec`.

  * For bytes or objects, the default is `VLenBytesCodec`.

These defaults can be changed by modifying the value of
`array.v2_default_compressor` in `zarr.core.config`.

**overwrite** bool, optional

    

Whether to raise an error if the store already exists (default is False).

Returns:

    

Array

    

Array created from the store.

_classmethod _from_dict(

    _store_path : zarr.storage._common.StorePath_,
    _data : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON]_,
) -> Array#

    

Create a Zarr array from a dictionary.

Parameters:

    

**store_path** StorePath

    

The path within the store where the array should be created.

**data** dict

    

A dictionary representing the array data. This dictionary should include
necessary metadata for the array, such as shape, dtype, fill value, and
attributes.

Returns:

    

Array

    

The created Zarr array.

Raises:

    

ValueError

    

If the dictionary data is invalid or missing required fields for array
creation.

get_basic_selection(

    _selection : zarr.core.indexing.BasicSelection = Ellipsis_,
    _*_ ,
    _out : zarr.core.buffer.NDBuffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _prototype : zarr.core.buffer.BufferPrototype | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _fields : zarr.core.indexing.Fields | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.NDArrayLikeOrScalar#

    

Retrieve data for an item or region of the array.

Parameters:

    

**selection** tuple

    

A tuple specifying the requested item or region for each dimension of the
array. May be any combination of int and/or slice or ellipsis for
multidimensional arrays.

**out** NDBuffer, optional

    

If given, load the selected data directly into this buffer.

**prototype** BufferPrototype, optional

    

The prototype of the buffer to use for the output data. If not provided, the
default buffer prototype is used.

**fields** str or sequence of str, optional

    

For arrays with a structured dtype, one or more fields can be specified to
extract data for.

Returns:

    

NDArrayLikeOrScalar

    

An array-like or scalar containing the data for the requested region.

See also

`set_basic_selection`, `get_mask_selection`, `set_mask_selection`

    
`get_coordinate_selection`, `set_coordinate_selection`,
`get_orthogonal_selection`

    
`set_orthogonal_selection`, `get_block_selection`, `set_block_selection`

    
`vindex`, `oindex`, `blocks`, `__getitem__`, `__setitem__`

    

Notes

Slices with step > 1 are supported, but slices with negative step are not.

For arrays with a structured dtype, see Zarr format 2 for examples of how to
use the fields parameter.

This method provides the implementation for accessing data via the square
bracket notation (__getitem__). See `__getitem__()` for examples using the
alternative notation.

Examples

Setup a 1-dimensional array:

    
    
    >>> import zarr
    >>> import numpy as np
    >>> data = np.arange(100, dtype="uint16")
    >>> z = zarr.create_array(
    >>>        StorePath(MemoryStore(mode="w")),
    >>>        shape=data.shape,
    >>>        chunks=(3,),
    >>>        dtype=data.dtype,
    >>>        )
    >>> z[:] = data
    

Retrieve a single item:

    
    
    >>> z.get_basic_selection(5)
    5
    

Retrieve a region via slicing:

    
    
    >>> z.get_basic_selection(slice(5))
    array([0, 1, 2, 3, 4])
    >>> z.get_basic_selection(slice(-5, None))
    array([95, 96, 97, 98, 99])
    >>> z.get_basic_selection(slice(5, 10))
    array([5, 6, 7, 8, 9])
    >>> z.get_basic_selection(slice(5, 10, 2))
    array([5, 7, 9])
    >>> z.get_basic_selection(slice(None, None, 2))
    array([  0,  2,  4, ..., 94, 96, 98])
    

Setup a 3-dimensional array:

    
    
    >>> data = np.arange(1000).reshape(10, 10, 10)
    >>> z = zarr.create_array(
    >>>        StorePath(MemoryStore(mode="w")),
    >>>        shape=data.shape,
    >>>        chunks=(5, 5, 5),
    >>>        dtype=data.dtype,
    >>>        )
    >>> z[:] = data
    

Retrieve an item:

    
    
    >>> z.get_basic_selection((1, 2, 3))
    123
    

Retrieve a region via slicing and Ellipsis:

    
    
    >>> z.get_basic_selection((slice(1, 3), slice(1, 3), 0))
    array([[110, 120],
           [210, 220]])
    >>> z.get_basic_selection(0, (slice(1, 3), slice(None)))
    array([[10, 11, 12, 13, 14, 15, 16, 17, 18, 19],
           [20, 21, 22, 23, 24, 25, 26, 27, 28, 29]])
    >>> z.get_basic_selection((..., 5))
    array([[  2  12  22  32  42  52  62  72  82  92]
           [102 112 122 132 142 152 162 172 182 192]
           ...
           [802 812 822 832 842 852 862 872 882 892]
           [902 912 922 932 942 952 962 972 982 992]]
    

get_block_selection(

    _selection : zarr.core.indexing.BasicSelection_,
    _*_ ,
    _out : zarr.core.buffer.NDBuffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _fields : zarr.core.indexing.Fields | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _prototype : zarr.core.buffer.BufferPrototype | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.NDArrayLikeOrScalar#

    

Retrieve a selection of individual items, by providing the indices
(coordinates) for each selected item.

Parameters:

    

**selection** int or slice or tuple of int or slice

    

An integer (coordinate) or slice for each dimension of the array.

**out** NDBuffer, optional

    

If given, load the selected data directly into this buffer.

**fields** str or sequence of str, optional

    

For arrays with a structured dtype, one or more fields can be specified to
extract data for.

**prototype** BufferPrototype, optional

    

The prototype of the buffer to use for the output data. If not provided, the
default buffer prototype is used.

Returns:

    

NDArrayLikeOrScalar

    

An array-like or scalar containing the data for the requested block selection.

See also

`get_basic_selection`, `set_basic_selection`, `get_mask_selection`,
`set_mask_selection`

    
`get_orthogonal_selection`, `set_orthogonal_selection`,
`get_coordinate_selection`

    
`set_coordinate_selection`, `set_block_selection`

    
`vindex`, `oindex`, `blocks`, `__getitem__`, `__setitem__`

    

Notes

Block indexing is a convenience indexing method to work on individual chunks
with chunk index slicing. It has the same concept as Dask’s Array.blocks
indexing.

Slices are supported. However, only with a step size of one.

Block index arrays may be multidimensional to index multidimensional arrays.
For example:

    
    
    >>> z.blocks[0, 1:3]
    array([[ 3,  4,  5,  6,  7,  8],
           [13, 14, 15, 16, 17, 18],
           [23, 24, 25, 26, 27, 28]])
    

Examples

Setup a 2-dimensional array:

    
    
    >>> import zarr
    >>> import numpy as np
    >>> data = np.arange(0, 100, dtype="uint16").reshape((10, 10))
    >>> z = zarr.create_array(
    >>>        StorePath(MemoryStore(mode="w")),
    >>>        shape=data.shape,
    >>>        chunks=(3, 3),
    >>>        dtype=data.dtype,
    >>>        )
    >>> z[:] = data
    

Retrieve items by specifying their block coordinates:

    
    
    >>> z.get_block_selection((1, slice(None)))
    array([[30, 31, 32, 33, 34, 35, 36, 37, 38, 39],
           [40, 41, 42, 43, 44, 45, 46, 47, 48, 49],
           [50, 51, 52, 53, 54, 55, 56, 57, 58, 59]])
    

Which is equivalent to:

    
    
    >>> z[3:6, :]
    array([[30, 31, 32, 33, 34, 35, 36, 37, 38, 39],
           [40, 41, 42, 43, 44, 45, 46, 47, 48, 49],
           [50, 51, 52, 53, 54, 55, 56, 57, 58, 59]])
    

For convenience, the block selection functionality is also available via the
blocks property, e.g.:

    
    
    >>> z.blocks[1]
    array([[30, 31, 32, 33, 34, 35, 36, 37, 38, 39],
           [40, 41, 42, 43, 44, 45, 46, 47, 48, 49],
           [50, 51, 52, 53, 54, 55, 56, 57, 58, 59]])
    

get_coordinate_selection(

    _selection : zarr.core.indexing.CoordinateSelection_,
    _*_ ,
    _out : zarr.core.buffer.NDBuffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _fields : zarr.core.indexing.Fields | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _prototype : zarr.core.buffer.BufferPrototype | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.NDArrayLikeOrScalar#

    

Retrieve a selection of individual items, by providing the indices
(coordinates) for each selected item.

Parameters:

    

**selection** tuple

    

An integer (coordinate) array for each dimension of the array.

**out** NDBuffer, optional

    

If given, load the selected data directly into this buffer.

**fields** str or sequence of str, optional

    

For arrays with a structured dtype, one or more fields can be specified to
extract data for.

**prototype** BufferPrototype, optional

    

The prototype of the buffer to use for the output data. If not provided, the
default buffer prototype is used.

Returns:

    

NDArrayLikeOrScalar

    

An array-like or scalar containing the data for the requested coordinate
selection.

See also

`get_basic_selection`, `set_basic_selection`, `get_mask_selection`,
`set_mask_selection`

    
`get_orthogonal_selection`, `set_orthogonal_selection`,
`set_coordinate_selection`

    
`get_block_selection`, `set_block_selection`

    
`vindex`, `oindex`, `blocks`, `__getitem__`, `__setitem__`

    

Notes

Coordinate indexing is also known as point selection, and is a form of
vectorized or inner indexing.

Slices are not supported. Coordinate arrays must be provided for all
dimensions of the array.

Coordinate arrays may be multidimensional, in which case the output array will
also be multidimensional. Coordinate arrays are broadcast against each other
before being applied. The shape of the output will be the same as the shape of
each coordinate array after broadcasting.

Examples

Setup a 2-dimensional array:

    
    
    >>> import zarr
    >>> import numpy as np
    >>> data = np.arange(0, 100, dtype="uint16").reshape((10, 10))
    >>> z = zarr.create_array(
    >>>        StorePath(MemoryStore(mode="w")),
    >>>        shape=data.shape,
    >>>        chunks=(3, 3),
    >>>        dtype=data.dtype,
    >>>        )
    >>> z[:] = data
    

Retrieve items by specifying their coordinates:

    
    
    >>> z.get_coordinate_selection(([1, 4], [1, 4]))
    array([11, 44])
    

For convenience, the coordinate selection functionality is also available via
the vindex property, e.g.:

    
    
    >>> z.vindex[[1, 4], [1, 4]]
    array([11, 44])
    

get_mask_selection(

    _mask : zarr.core.indexing.MaskSelection_,
    _*_ ,
    _out : zarr.core.buffer.NDBuffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _fields : zarr.core.indexing.Fields | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _prototype : zarr.core.buffer.BufferPrototype | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.NDArrayLikeOrScalar#

    

Retrieve a selection of individual items, by providing a Boolean array of the
same shape as the array against which the selection is being made, where True
values indicate a selected item.

Parameters:

    

**mask** ndarray, bool

    

A Boolean array of the same shape as the array against which the selection is
being made.

**out** NDBuffer, optional

    

If given, load the selected data directly into this buffer.

**fields** str or sequence of str, optional

    

For arrays with a structured dtype, one or more fields can be specified to
extract data for.

**prototype** BufferPrototype, optional

    

The prototype of the buffer to use for the output data. If not provided, the
default buffer prototype is used.

Returns:

    

NDArrayLikeOrScalar

    

An array-like or scalar containing the data for the requested selection.

See also

`get_basic_selection`, `set_basic_selection`, `set_mask_selection`

    
`get_orthogonal_selection`, `set_orthogonal_selection`,
`get_coordinate_selection`

    
`set_coordinate_selection`, `get_block_selection`, `set_block_selection`

    
`vindex`, `oindex`, `blocks`, `__getitem__`, `__setitem__`

    

Notes

Mask indexing is a form of vectorized or inner indexing, and is equivalent to
coordinate indexing. Internally the mask array is converted to coordinate
arrays by calling np.nonzero.

Examples

Setup a 2-dimensional array:

    
    
    >>> import zarr
    >>> import numpy as np
    >>> data = np.arange(100).reshape(10, 10)
    >>> z = zarr.create_array(
    >>>        StorePath(MemoryStore(mode="w")),
    >>>        shape=data.shape,
    >>>        chunks=data.shape,
    >>>        dtype=data.dtype,
    >>>        )
    >>> z[:] = data
    

Retrieve items by specifying a mask:

    
    
    >>> sel = np.zeros_like(z, dtype=bool)
    >>> sel[1, 1] = True
    >>> sel[4, 4] = True
    >>> z.get_mask_selection(sel)
    array([11, 44])
    

For convenience, the mask selection functionality is also available via the
vindex property, e.g.:

    
    
    >>> z.vindex[sel]
    array([11, 44])
    

get_orthogonal_selection(

    _selection : zarr.core.indexing.OrthogonalSelection_,
    _*_ ,
    _out : zarr.core.buffer.NDBuffer | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _fields : zarr.core.indexing.Fields | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _prototype : zarr.core.buffer.BufferPrototype | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.NDArrayLikeOrScalar#

    

Retrieve data by making a selection for each dimension of the array. For
example, if an array has 2 dimensions, allows selecting specific rows and/or
columns. The selection for each dimension can be either an integer (indexing a
single item), a slice, an array of integers, or a Boolean array where True
values indicate a selection.

Parameters:

    

**selection** tuple

    

A selection for each dimension of the array. May be any combination of int,
slice, integer array or Boolean array.

**out** NDBuffer, optional

    

If given, load the selected data directly into this buffer.

**fields** str or sequence of str, optional

    

For arrays with a structured dtype, one or more fields can be specified to
extract data for.

**prototype** BufferPrototype, optional

    

The prototype of the buffer to use for the output data. If not provided, the
default buffer prototype is used.

Returns:

    

NDArrayLikeOrScalar

    

An array-like or scalar containing the data for the requested selection.

See also

`get_basic_selection`, `set_basic_selection`, `get_mask_selection`,
`set_mask_selection`

    
`get_coordinate_selection`, `set_coordinate_selection`,
`set_orthogonal_selection`

    
`get_block_selection`, `set_block_selection`

    
`vindex`, `oindex`, `blocks`, `__getitem__`, `__setitem__`

    

Notes

Orthogonal indexing is also known as outer indexing.

Slices with step > 1 are supported, but slices with negative step are not.

Examples

Setup a 2-dimensional array:

    
    
    >>> import zarr
    >>> import numpy as np
    >>> data = np.arange(100).reshape(10, 10)
    >>> z = zarr.create_array(
    >>>        StorePath(MemoryStore(mode="w")),
    >>>        shape=data.shape,
    >>>        chunks=data.shape,
    >>>        dtype=data.dtype,
    >>>        )
    >>> z[:] = data
    

Retrieve rows and columns via any combination of int, slice, integer array
and/or Boolean array:

    
    
    >>> z.get_orthogonal_selection(([1, 4], slice(None)))
    array([[10, 11, 12, 13, 14, 15, 16, 17, 18, 19],
           [40, 41, 42, 43, 44, 45, 46, 47, 48, 49]])
    >>> z.get_orthogonal_selection((slice(None), [1, 4]))
    array([[ 1,  4],
           [11, 14],
           [21, 24],
           [31, 34],
           [41, 44],
           [51, 54],
           [61, 64],
           [71, 74],
           [81, 84],
           [91, 94]])
    >>> z.get_orthogonal_selection(([1, 4], [1, 4]))
    array([[11, 14],
           [41, 44]])
    >>> sel = np.zeros(z.shape[0], dtype=bool)
    >>> sel[1] = True
    >>> sel[4] = True
    >>> z.get_orthogonal_selection((sel, sel))
    array([[11, 14],
           [41, 44]])
    

For convenience, the orthogonal selection functionality is also available via
the oindex property, e.g.:

    
    
    >>> z.oindex[[1, 4], :]
    array([[10, 11, 12, 13, 14, 15, 16, 17, 18, 19],
           [40, 41, 42, 43, 44, 45, 46, 47, 48, 49]])
    >>> z.oindex[:, [1, 4]]
    array([[ 1,  4],
           [11, 14],
           [21, 24],
           [31, 34],
           [41, 44],
           [51, 54],
           [61, 64],
           [71, 74],
           [81, 84],
           [91, 94]])
    >>> z.oindex[[1, 4], [1, 4]]
    array([[11, 14],
           [41, 44]])
    >>> sel = np.zeros(z.shape[0], dtype=bool)
    >>> sel[1] = True
    >>> sel[4] = True
    >>> z.oindex[sel, sel]
    array([[11, 14],
           [41, 44]])
    

info_complete() -> Any#

    

Returns all the information about an array, including information from the
Store.

In addition to the statically known information like `name` and `zarr_format`,
this includes additional information like the size of the array in bytes and
the number of chunks written.

Note that this method will need to read metadata from the store.

Returns:

    

ArrayInfo

    

See also

`Array.info`

    

The statically known subset of metadata about an array.

nbytes_stored() -> [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")#

    

Determine the size, in bytes, of the array actually written to the store.

Returns:

    

**size** int

    

_classmethod _open(_store : zarr.storage.StoreLike_) -> Array#

    

Opens an existing Array from a store.

Parameters:

    

**store** Store

    

Store containing the Array.

Returns:

    

Array

    

Array opened from the store.

resize(_new_shape : zarr.core.common.ShapeLike_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Change the shape of the array by growing or shrinking one or more dimensions.

Parameters:

    

**new_shape** tuple

    

New shape of the array.

Notes

If one or more dimensions are shrunk, any chunks falling outside the new array
shape will be deleted from the underlying store. However, it is noteworthy
that the chunks partially falling inside the new array (i.e. boundary chunks)
will remain intact, and therefore, the data falling outside the new array but
inside the boundary chunks would be restored by a subsequent resize operation
that grows the array size.

Examples

    
    
    >>> import zarr
    >>> z = zarr.zeros(shape=(10000, 10000),
    >>>                chunk_shape=(1000, 1000),
    >>>                dtype="i4",)
    >>> z.shape
    (10000, 10000)
    >>> z = z.resize(20000, 1000)
    >>> z.shape
    (20000, 1000)
    >>> z2 = z.resize(50, 50)
    >>> z.shape
    (20000, 1000)
    >>> z2.shape
    (50, 50)
    

set_basic_selection(

    _selection : zarr.core.indexing.BasicSelection_,
    _value : numpy.typing.ArrayLike_,
    _*_ ,
    _fields : zarr.core.indexing.Fields | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _prototype : zarr.core.buffer.BufferPrototype | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Modify data for an item or region of the array.

Parameters:

    

**selection** tuple

    

A tuple specifying the requested item or region for each dimension of the
array. May be any combination of int and/or slice or ellipsis for
multidimensional arrays.

**value** npt.ArrayLike

    

An array-like containing values to be stored into the array.

**fields** str or sequence of str, optional

    

For arrays with a structured dtype, one or more fields can be specified to set
data for.

**prototype** BufferPrototype, optional

    

The prototype of the buffer used for setting the data. If not provided, the
default buffer prototype is used.

See also

`get_basic_selection`, `get_mask_selection`, `set_mask_selection`

    
`get_coordinate_selection`, `set_coordinate_selection`,
`get_orthogonal_selection`

    
`set_orthogonal_selection`, `get_block_selection`, `set_block_selection`

    
`vindex`, `oindex`, `blocks`, `__getitem__`, `__setitem__`

    

Notes

For arrays with a structured dtype, see Zarr format 2 for examples of how to
use the fields parameter.

This method provides the underlying implementation for modifying data via
square bracket notation, see `__setitem__()` for equivalent examples using the
alternative notation.

Examples

Setup a 1-dimensional array:

    
    
    >>> import zarr
    >>> z = zarr.zeros(
    >>>        shape=(100,),
    >>>        store=StorePath(MemoryStore(mode="w")),
    >>>        chunk_shape=(100,),
    >>>        dtype="i4",
    >>>       )
    

Set all array elements to the same scalar value:

    
    
    >>> z.set_basic_selection(..., 42)
    >>> z[...]
    array([42, 42, 42, ..., 42, 42, 42])
    

Set a portion of the array:

    
    
    >>> z.set_basic_selection(slice(10), np.arange(10))
    >>> z.set_basic_selection(slice(-10, None), np.arange(10)[::-1])
    >>> z[...]
    array([ 0, 1, 2, ..., 2, 1, 0])
    

Setup a 2-dimensional array:

    
    
    >>> z = zarr.zeros(
    >>>        shape=(5, 5),
    >>>        store=StorePath(MemoryStore(mode="w")),
    >>>        chunk_shape=(5, 5),
    >>>        dtype="i4",
    >>>       )
    

Set all array elements to the same scalar value:

    
    
    >>> z.set_basic_selection(..., 42)
    

Set a portion of the array:

    
    
    >>> z.set_basic_selection((0, slice(None)), np.arange(z.shape[1]))
    >>> z.set_basic_selection((slice(None), 0), np.arange(z.shape[0]))
    >>> z[...]
    array([[ 0,  1,  2,  3,  4],
           [ 1, 42, 42, 42, 42],
           [ 2, 42, 42, 42, 42],
           [ 3, 42, 42, 42, 42],
           [ 4, 42, 42, 42, 42]])
    

set_block_selection(

    _selection : zarr.core.indexing.BasicSelection_,
    _value : numpy.typing.ArrayLike_,
    _*_ ,
    _fields : zarr.core.indexing.Fields | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _prototype : zarr.core.buffer.BufferPrototype | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Modify a selection of individual blocks, by providing the chunk indices
(coordinates) for each block to be modified.

Parameters:

    

**selection** tuple

    

An integer (coordinate) or slice for each dimension of the array.

**value** npt.ArrayLike

    

An array-like containing the data to be stored in the block selection.

**fields** str or sequence of str, optional

    

For arrays with a structured dtype, one or more fields can be specified to set
data for.

**prototype** BufferPrototype, optional

    

The prototype of the buffer used for setting the data. If not provided, the
default buffer prototype is used.

See also

`get_basic_selection`, `set_basic_selection`, `get_mask_selection`,
`set_mask_selection`

    
`get_orthogonal_selection`, `set_orthogonal_selection`,
`get_coordinate_selection`

    
`get_block_selection`, `set_block_selection`

    
`vindex`, `oindex`, `blocks`, `__getitem__`, `__setitem__`

    

Notes

Block indexing is a convenience indexing method to work on individual chunks
with chunk index slicing. It has the same concept as Dask’s Array.blocks
indexing.

Slices are supported. However, only with a step size of one.

Examples

Set up a 2-dimensional array:

    
    
    >>> import zarr
    >>> z = zarr.zeros(
    >>>        shape=(6, 6),
    >>>        store=StorePath(MemoryStore(mode="w")),
    >>>        chunk_shape=(2, 2),
    >>>        dtype="i4",
    >>>       )
    

Set data for a selection of items:

    
    
    >>> z.set_block_selection((1, 0), 1)
    >>> z[...]
    array([[0, 0, 0, 0, 0, 0],
           [0, 0, 0, 0, 0, 0],
           [1, 1, 0, 0, 0, 0],
           [1, 1, 0, 0, 0, 0],
           [0, 0, 0, 0, 0, 0],
           [0, 0, 0, 0, 0, 0]])
    

For convenience, this functionality is also available via the blocks property.
E.g.:

    
    
    >>> z.blocks[2, 1] = 4
    >>> z[...]
    array([[0, 0, 0, 0, 0, 0],
           [0, 0, 0, 0, 0, 0],
           [1, 1, 0, 0, 0, 0],
           [1, 1, 0, 0, 0, 0],
           [0, 0, 4, 4, 0, 0],
           [0, 0, 4, 4, 0, 0]])
    
    >>> z.blocks[:, 2] = 7
    >>> z[...]
    array([[0, 0, 0, 0, 7, 7],
           [0, 0, 0, 0, 7, 7],
           [1, 1, 0, 0, 7, 7],
           [1, 1, 0, 0, 7, 7],
           [0, 0, 4, 4, 7, 7],
           [0, 0, 4, 4, 7, 7]])
    

set_coordinate_selection(

    _selection : zarr.core.indexing.CoordinateSelection_,
    _value : numpy.typing.ArrayLike_,
    _*_ ,
    _fields : zarr.core.indexing.Fields | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _prototype : zarr.core.buffer.BufferPrototype | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Modify a selection of individual items, by providing the indices (coordinates)
for each item to be modified.

Parameters:

    

**selection** tuple

    

An integer (coordinate) array for each dimension of the array.

**value** npt.ArrayLike

    

An array-like containing values to be stored into the array.

**fields** str or sequence of str, optional

    

For arrays with a structured dtype, one or more fields can be specified to set
data for.

See also

`get_basic_selection`, `set_basic_selection`, `get_mask_selection`,
`set_mask_selection`

    
`get_orthogonal_selection`, `set_orthogonal_selection`,
`get_coordinate_selection`

    
`get_block_selection`, `set_block_selection`

    
`vindex`, `oindex`, `blocks`, `__getitem__`, `__setitem__`

    

Notes

Coordinate indexing is also known as point selection, and is a form of
vectorized or inner indexing.

Slices are not supported. Coordinate arrays must be provided for all
dimensions of the array.

Examples

Setup a 2-dimensional array:

    
    
    >>> import zarr
    >>> z = zarr.zeros(
    >>>        shape=(5, 5),
    >>>        store=StorePath(MemoryStore(mode="w")),
    >>>        chunk_shape=(5, 5),
    >>>        dtype="i4",
    >>>       )
    

Set data for a selection of items:

    
    
    >>> z.set_coordinate_selection(([1, 4], [1, 4]), 1)
    >>> z[...]
    array([[0, 0, 0, 0, 0],
           [0, 1, 0, 0, 0],
           [0, 0, 0, 0, 0],
           [0, 0, 0, 0, 0],
           [0, 0, 0, 0, 1]])
    

For convenience, this functionality is also available via the vindex property.
E.g.:

    
    
    >>> z.vindex[[1, 4], [1, 4]] = 2
    >>> z[...]
    array([[0, 0, 0, 0, 0],
           [0, 2, 0, 0, 0],
           [0, 0, 0, 0, 0],
           [0, 0, 0, 0, 0],
           [0, 0, 0, 0, 2]])
    

set_mask_selection(

    _mask : zarr.core.indexing.MaskSelection_,
    _value : numpy.typing.ArrayLike_,
    _*_ ,
    _fields : zarr.core.indexing.Fields | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _prototype : zarr.core.buffer.BufferPrototype | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Modify a selection of individual items, by providing a Boolean array of the
same shape as the array against which the selection is being made, where True
values indicate a selected item.

Parameters:

    

**mask** ndarray, bool

    

A Boolean array of the same shape as the array against which the selection is
being made.

**value** npt.ArrayLike

    

An array-like containing values to be stored into the array.

**fields** str or sequence of str, optional

    

For arrays with a structured dtype, one or more fields can be specified to set
data for.

See also

`get_basic_selection`, `set_basic_selection`, `get_mask_selection`

    
`get_orthogonal_selection`, `set_orthogonal_selection`,
`get_coordinate_selection`

    
`set_coordinate_selection`, `get_block_selection`, `set_block_selection`

    
`vindex`, `oindex`, `blocks`, `__getitem__`, `__setitem__`

    

Notes

Mask indexing is a form of vectorized or inner indexing, and is equivalent to
coordinate indexing. Internally the mask array is converted to coordinate
arrays by calling np.nonzero.

Examples

Setup a 2-dimensional array:

    
    
    >>> import zarr
    >>> z = zarr.zeros(
    >>>        shape=(5, 5),
    >>>        store=StorePath(MemoryStore(mode="w")),
    >>>        chunk_shape=(5, 5),
    >>>        dtype="i4",
    >>>       )
    

Set data for a selection of items:

    
    
    >>> sel = np.zeros_like(z, dtype=bool)
    >>> sel[1, 1] = True
    >>> sel[4, 4] = True
    >>> z.set_mask_selection(sel, 1)
    >>> z[...]
    array([[0, 0, 0, 0, 0],
           [0, 1, 0, 0, 0],
           [0, 0, 0, 0, 0],
           [0, 0, 0, 0, 0],
           [0, 0, 0, 0, 1]])
    

For convenience, this functionality is also available via the vindex property.
E.g.:

    
    
    >>> z.vindex[sel] = 2
    >>> z[...]
    array([[0, 0, 0, 0, 0],
           [0, 2, 0, 0, 0],
           [0, 0, 0, 0, 0],
           [0, 0, 0, 0, 0],
           [0, 0, 0, 0, 2]])
    

set_orthogonal_selection(

    _selection : zarr.core.indexing.OrthogonalSelection_,
    _value : numpy.typing.ArrayLike_,
    _*_ ,
    _fields : zarr.core.indexing.Fields | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _prototype : zarr.core.buffer.BufferPrototype | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Modify data via a selection for each dimension of the array.

Parameters:

    

**selection** tuple

    

A selection for each dimension of the array. May be any combination of int,
slice, integer array or Boolean array.

**value** npt.ArrayLike

    

An array-like array containing the data to be stored in the array.

**fields** str or sequence of str, optional

    

For arrays with a structured dtype, one or more fields can be specified to set
data for.

**prototype** BufferPrototype, optional

    

The prototype of the buffer used for setting the data. If not provided, the
default buffer prototype is used.

See also

`get_basic_selection`, `set_basic_selection`, `get_mask_selection`,
`set_mask_selection`

    
`get_coordinate_selection`, `set_coordinate_selection`,
`get_orthogonal_selection`

    
`get_block_selection`, `set_block_selection`

    
`vindex`, `oindex`, `blocks`, `__getitem__`, `__setitem__`

    

Notes

Orthogonal indexing is also known as outer indexing.

Slices with step > 1 are supported, but slices with negative step are not.

Examples

Setup a 2-dimensional array:

    
    
    >>> import zarr
    >>> z = zarr.zeros(
    >>>        shape=(5, 5),
    >>>        store=StorePath(MemoryStore(mode="w")),
    >>>        chunk_shape=(5, 5),
    >>>        dtype="i4",
    >>>       )
    

Set data for a selection of rows:

    
    
    >>> z.set_orthogonal_selection(([1, 4], slice(None)), 1)
    >>> z[...]
    array([[0, 0, 0, 0, 0],
           [1, 1, 1, 1, 1],
           [0, 0, 0, 0, 0],
           [0, 0, 0, 0, 0],
           [1, 1, 1, 1, 1]])
    

Set data for a selection of columns:

    
    
    >>> z.set_orthogonal_selection((slice(None), [1, 4]), 2)
    >>> z[...]
    array([[0, 2, 0, 0, 2],
           [1, 2, 1, 1, 2],
           [0, 2, 0, 0, 2],
           [0, 2, 0, 0, 2],
           [1, 2, 1, 1, 2]])
    

Set data for a selection of rows and columns:

    
    
    >>> z.set_orthogonal_selection(([1, 4], [1, 4]), 3)
    >>> z[...]
    array([[0, 2, 0, 0, 2],
           [1, 3, 1, 1, 3],
           [0, 2, 0, 0, 2],
           [0, 2, 0, 0, 2],
           [1, 3, 1, 1, 3]])
    

Set data from a 2D array:

    
    
    >>> values = np.arange(10).reshape(2, 5)
    >>> z.set_orthogonal_selection(([0, 3], ...), values)
    >>> z[...]
    array([[0, 1, 2, 3, 4],
           [1, 3, 1, 1, 3],
           [0, 2, 0, 0, 2],
           [5, 6, 7, 8, 9],
           [1, 3, 1, 1, 3]])
    

For convenience, this functionality is also available via the oindex property.
E.g.:

    
    
    >>> z.oindex[[1, 4], [1, 4]] = 4
    >>> z[...]
    array([[0, 1, 2, 3, 4],
           [1, 4, 1, 1, 4],
           [0, 2, 0, 0, 2],
           [5, 6, 7, 8, 9],
           [1, 4, 1, 1, 4]])
    

update_attributes(_new_attributes :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), zarr.core.common.JSON]_) -> Array#

    

Update the array’s attributes.

Parameters:

    

**new_attributes** dict

    

A dictionary of new attributes to update or add to the array. The keys
represent attribute names, and the values must be JSON-compatible.

Returns:

    

Array

    

The array with the updated attributes.

Raises:

    

ValueError

    

If the attributes are invalid or incompatible with the array’s metadata.

Notes

  * The updated attributes will be merged with existing attributes, and any conflicts will be overwritten by the new values.

_property _attrs _: zarr.core.attributes.Attributes_#

    

Returns a MutableMapping containing user-defined attributes.

Returns:

    

**attrs** MutableMapping

    

A MutableMapping object containing user-defined attributes.

Notes

Note that attribute values must be JSON serializable.

_property _basename _:
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_#

    

Final component of name.

_property _blocks _: zarr.core.indexing.BlockIndex_#

    

Shortcut for blocked chunked indexing, see `get_block_selection()` and
`set_block_selection()` for documentation and examples.

_property _cdata_shape _: zarr.core.common.ChunkCoords_#

    

The shape of the chunk grid for this array.

_property _chunks _: zarr.core.common.ChunkCoords_#

    

Returns a tuple of integers describing the length of each dimension of a chunk
of the array. If sharding is used the inner chunk shape is returned.

Only defined for arrays using using RegularChunkGrid. If array doesn’t use
RegularChunkGrid, NotImplementedError is raised.

Returns:

    

tuple

    

A tuple of integers representing the length of each dimension of a chunk.

_property _compressor _: [numcodecs.abc.Codec](https://numcodecs.readthedocs.io/en/stable/abc.html#numcodecs.abc.Codec "\(in numcodecs v0.16.1\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")_#
    

Compressor that is applied to each chunk of the array.

Deprecated since version 3.0.0: array.compressor is deprecated and will be
removed in a future release. Use array.compressors instead.

_property _compressors _: [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[numcodecs.abc.Codec](https://numcodecs.readthedocs.io/en/stable/abc.html#numcodecs.abc.Codec "\(in numcodecs v0.16.1\)"), Ellipsis] | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[zarr.abc.codec.BytesBytesCodec, Ellipsis]_#
    

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

_property _dtype _:
[numpy.dtype](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype
"\(in NumPy v2.3\)")[Any]_#

    

Returns the NumPy data type.

Returns:

    

np.dtype

    

The NumPy data type.

_property _fill_value _: Any_#

    

_property _filters _: [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[numcodecs.abc.Codec](https://numcodecs.readthedocs.io/en/stable/abc.html#numcodecs.abc.Codec "\(in numcodecs v0.16.1\)"), Ellipsis] | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[zarr.abc.codec.ArrayArrayCodec, Ellipsis]_#
    

Filters that are applied to each chunk of the array, in order, before
serializing that chunk to bytes.

_property _info _: Any_#

    

Return the statically known information for an array.

Returns:

    

ArrayInfo

    

See also

`Array.info_complete`

    

All information about a group, including dynamic information like the number
of bytes and chunks written.

Examples

    
    
    >>> arr = zarr.create(shape=(10,), chunks=(2,), dtype="float32")
    >>> arr.info
    Type               : Array
    Zarr format        : 3
    Data type          : DataType.float32
    Shape              : (10,)
    Chunk shape        : (2,)
    Order              : C
    Read-only          : False
    Store type         : MemoryStore
    Codecs             : [BytesCodec(endian=<Endian.little: 'little'>)]
    No. bytes          : 40
    

_property _metadata _: zarr.core.metadata.ArrayMetadata_#

    

_property _name _: [str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")_#

    

Array name following h5py convention.

_property _nbytes _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The total number of bytes that can be stored in the chunks of this array.

Notes

This value is calculated by multiplying the number of elements in the array
and the size of each element, the latter of which is determined by the dtype
of the array. For this reason, `nbytes` will likely be inaccurate for arrays
with variable-length dtypes. It is not possible to determine the size of an
array with variable-length elements from the shape and dtype alone.

_property _nchunks _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The number of chunks in the stored representation of this array.

_property _nchunks_initialized _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

Calculate the number of chunks that have been initialized, i.e. the number of
chunks that have been persisted to the storage backend.

Returns:

    

**nchunks_initialized** int

    

The number of chunks that have been initialized.

Notes

On `Array` this is a (synchronous) property, unlike asynchronous function
`AsyncArray.nchunks_initialized()`.

Examples

    
    
    >>> arr = await zarr.create(shape=(10,), chunks=(2,))
    >>> arr.nchunks_initialized
    0
    >>> arr[:5] = 1
    >>> arr.nchunks_initialized
    3
    

_property _ndim _: [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")_#

    

Returns the number of dimensions in the array.

Returns:

    

int

    

The number of dimensions in the array.

_property _oindex _: zarr.core.indexing.OIndex_#

    

Shortcut for orthogonal (outer) indexing, see `get_orthogonal_selection()` and
`set_orthogonal_selection()` for documentation and examples.

_property _order _: zarr.core.common.MemoryOrder_#

    

_property _path _: [str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")_#

    

Storage path.

_property _read_only _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

_property _serializer _: [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") | zarr.abc.codec.ArrayBytesCodec_#
    

Array-to-bytes codec to use for serializing the chunks into bytes.

_property _shape _: zarr.core.common.ChunkCoords_#

    

Returns the shape of the array.

Returns:

    

ChunkCoords

    

The shape of the array.

_property _shards _: zarr.core.common.ChunkCoords | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")_#
    

Returns a tuple of integers describing the length of each dimension of a shard
of the array. Returns None if sharding is not used.

Only defined for arrays using using RegularChunkGrid. If array doesn’t use
RegularChunkGrid, NotImplementedError is raised.

Returns:

    

tuple | None
    

A tuple of integers representing the length of each dimension of a shard or
None if sharding is not used.

_property _size _: [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")_#

    

Returns the total number of elements in the array.

Returns:

    

int

    

Total number of elements in the array.

_property _store _: zarr.abc.store.Store_#

    

_property _store_path _: zarr.storage._common.StorePath_#

    

_property _vindex _: zarr.core.indexing.VIndex_#

    

Shortcut for vectorized (inner) indexing, see `get_coordinate_selection()`,
`set_coordinate_selection()`, `get_mask_selection()` and
`set_mask_selection()` for documentation and examples.

_class _zarr.AsyncArray(

    _metadata : zarr.core.metadata.ArrayV2Metadata | zarr.core.metadata.ArrayV2MetadataDict_,
    _store_path : zarr.storage._common.StorePath_,
    _config : zarr.core.array_spec.ArrayConfigLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
)#

_class _zarr.AsyncArray(

    _metadata : zarr.core.metadata.ArrayV3Metadata | zarr.core.metadata.ArrayV3MetadataDict_,
    _store_path : zarr.storage._common.StorePath_,
    _config : zarr.core.array_spec.ArrayConfigLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
)

    

Bases: `Generic`[`zarr.core.metadata.T_ArrayMetadata`]

An asynchronous array class representing a chunked array stored in a Zarr
store.

Parameters:

    

**metadata** ArrayMetadata

    

The metadata of the array.

**store_path** StorePath

    

The path to the Zarr store.

**config** ArrayConfigLike, optional

    

The runtime configuration of the array, by default None.

Attributes:

    

**metadata** ArrayMetadata

    

The metadata of the array.

**store_path** StorePath

    

The path to the Zarr store.

**codec_pipeline** CodecPipeline

    

The codec pipeline used for encoding and decoding chunks.

**_config** ArrayConfig

    

The runtime configuration of the array.

_async _append(

    _data : numpy.typing.ArrayLike_,
    _axis : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") = 0_,
) -> zarr.core.common.ChunkCoords#

    

Append data to axis.

Parameters:

    

**data** array-like

    

Data to be appended.

**axis** int

    

Axis along which to append.

Returns:

    

**new_shape** tuple

    

Notes

The size of all dimensions other than axis must match between this array and
data.

_classmethod _create(

    _store : zarr.storage.StoreLike_,
    _*_ ,
    _shape : zarr.core.common.ShapeLike_,
    _dtype : zarr.core.dtype.ZDTypeLike_,
    _zarr_format : Literal[2]_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = DEFAULT_FILL_VALUE_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunks : zarr.core.common.ShapeLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_separator : Literal['.', '/'] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _order : zarr.core.common.MemoryOrder | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _filters : [list](https://docs.python.org/3/library/stdtypes.html#list "\(in Python v3.13\)")[[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON]] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _compressor : zarr.core.metadata.v2.CompressorLikev2 | Literal['auto'] = 'auto'_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _data : numpy.typing.ArrayLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _config : zarr.core.array_spec.ArrayConfigLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> AsyncArray[zarr.core.metadata.ArrayV2Metadata]#

_classmethod _create(

    _store : zarr.storage.StoreLike_,
    _*_ ,
    _shape : zarr.core.common.ShapeLike_,
    _dtype : zarr.core.dtype.ZDTypeLike_,
    _zarr_format : Literal[3]_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = DEFAULT_FILL_VALUE_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_shape : zarr.core.common.ShapeLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_key_encoding : zarr.core.chunk_key_encodings.ChunkKeyEncoding | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[Literal['default'], Literal['.', '/']] | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[Literal['v2'], Literal['.', '/']] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _codecs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[zarr.abc.codec.Codec | [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON]] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_names : zarr.core.common.DimensionNames = None_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _data : numpy.typing.ArrayLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _config : zarr.core.array_spec.ArrayConfigLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> AsyncArray[zarr.core.metadata.ArrayV3Metadata]

_classmethod _create(

    _store : zarr.storage.StoreLike_,
    _*_ ,
    _shape : zarr.core.common.ShapeLike_,
    _dtype : zarr.core.dtype.ZDTypeLike_,
    _zarr_format : Literal[3] = 3_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = DEFAULT_FILL_VALUE_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_shape : zarr.core.common.ShapeLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_key_encoding : zarr.core.chunk_key_encodings.ChunkKeyEncoding | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[Literal['default'], Literal['.', '/']] | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[Literal['v2'], Literal['.', '/']] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _codecs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[zarr.abc.codec.Codec | [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON]] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_names : zarr.core.common.DimensionNames = None_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _data : numpy.typing.ArrayLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _config : zarr.core.array_spec.ArrayConfigLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> AsyncArray[zarr.core.metadata.ArrayV3Metadata]

_classmethod _create(

    _store : zarr.storage.StoreLike_,
    _*_ ,
    _shape : zarr.core.common.ShapeLike_,
    _dtype : zarr.core.dtype.ZDTypeLike_,
    _zarr_format : zarr.core.common.ZarrFormat_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = DEFAULT_FILL_VALUE_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_shape : zarr.core.common.ShapeLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_key_encoding : zarr.core.chunk_key_encodings.ChunkKeyEncoding | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[Literal['default'], Literal['.', '/']] | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[Literal['v2'], Literal['.', '/']] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _codecs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[zarr.abc.codec.Codec | [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON]] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_names : zarr.core.common.DimensionNames = None_,
    _chunks : zarr.core.common.ShapeLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_separator : Literal['.', '/'] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _order : zarr.core.common.MemoryOrder | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _filters : [list](https://docs.python.org/3/library/stdtypes.html#list "\(in Python v3.13\)")[[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON]] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _compressor : CompressorLike = 'auto'_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _data : numpy.typing.ArrayLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _config : zarr.core.array_spec.ArrayConfigLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> AsyncArray[zarr.core.metadata.ArrayV3Metadata] | AsyncArray[zarr.core.metadata.ArrayV2Metadata]
    

Async:

    

Method to create a new asynchronous array instance.

Deprecated since version 3.0.0: Deprecated in favor of
`zarr.api.asynchronous.create_array()`.

Parameters:

    

**store** StoreLike

    

The store where the array will be created.

**shape** ShapeLike

    

The shape of the array.

**dtype** ZDTypeLike

    

The data type of the array.

**zarr_format** ZarrFormat, optional

    

The Zarr format version (default is 3).

**fill_value** Any, optional

    

The fill value of the array (default is None).

**attributes** dict[str, JSON], optional

    

The attributes of the array (default is None).

**chunk_shape** ChunkCoords, optional

    

The shape of the array’s chunks Zarr format 3 only. Zarr format 2 arrays
should use chunks instead. If not specified, default are guessed based on the
shape and dtype.

**chunk_key_encoding** ChunkKeyEncodingLike, 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. The elements of this
collection 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:

  * For numeric arrays, the default is `BytesCodec` and `ZstdCodec`.

  * For Unicode strings, the default is `VLenUTF8Codec` and `ZstdCodec`.

  * For bytes or objects, the default is `VLenBytesCodec` and `ZstdCodec`.

These defaults can be changed by modifying the value of
`array.v3_default_filters`, `array.v3_default_serializer` and
`array.v3_default_compressors` in `zarr.core.config`.

**dimension_names** Iterable[str | None], optional
    

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

**chunks** ShapeLike, optional

    

The shape of the array’s chunks. Zarr format 2 only. Zarr format 3 arrays
should use `chunk_shape` instead. If not specified, default are guessed based
on the shape and dtype.

**dimension_separator** Literal[“.”, “/”], optional

    

The dimension separator (default is “.”). Zarr format 2 only. Zarr format 3
arrays should use `chunk_key_encoding` instead.

**order** Literal[“C”, “F”], optional

    

The memory of the array (default is “C”). If `zarr_format` is 2, this
parameter sets the memory order of the array. If zarr_format` is 3, then this
parameter is deprecated, because memory order is a runtime parameter for Zarr
3 arrays. The recommended way to specify the memory order for Zarr 3 arrays is
via the `config` parameter, e.g. `{'config': 'C'}`.

**filters** list[dict[str, JSON]], optional

    

Sequence of filters to use to encode chunk data prior to compression. Zarr
format 2 only. Zarr format 3 arrays should use `codecs` instead. If no
`filters` are provided, a default set of filters will be used. These defaults
can be changed by modifying the value of `array.v2_default_filters` in
`zarr.core.config`.

**compressor** dict[str, JSON], optional

    

The compressor used to compress the data (default is None). Zarr format 2
only. Zarr format 3 arrays should use `codecs` instead.

If no `compressor` is provided, a default compressor will be used:

  * For numeric arrays, the default is `ZstdCodec`.

  * For Unicode strings, the default is `VLenUTF8Codec`.

  * For bytes or objects, the default is `VLenBytesCodec`.

These defaults can be changed by modifying the value of
`array.v2_default_compressor` in `zarr.core.config`.

**overwrite** bool, optional

    

Whether to raise an error if the store already exists (default is False).

**data** npt.ArrayLike, optional

    

The data to be inserted into the array (default is None).

**config** ArrayConfigLike, optional

    

Runtime configuration for the array.

Returns:

    

AsyncArray

    

The created asynchronous array instance.

_classmethod _from_dict(

    _store_path : zarr.storage._common.StorePath_,
    _data : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON]_,
) -> AsyncArray[zarr.core.metadata.ArrayV3Metadata] | AsyncArray[zarr.core.metadata.ArrayV2Metadata]#
    

Create a Zarr array from a dictionary, with support for both Zarr format 2 and
3 metadata.

Parameters:

    

**store_path** StorePath

    

The path within the store where the array should be created.

**data** dict

    

A dictionary representing the array data. This dictionary should include
necessary metadata for the array, such as shape, dtype, and other attributes.
The format of the metadata will determine whether a Zarr format 2 or 3 array
is created.

Returns:

    

AsyncArray[ArrayV3Metadata] or AsyncArray[ArrayV2Metadata]

    

The created Zarr array, either using Zarr format 2 or 3 metadata based on the
provided data.

Raises:

    

ValueError

    

If the dictionary data is invalid or incompatible with either Zarr format 2 or
3 array creation.

_async _getitem(

    _selection : zarr.core.indexing.BasicSelection_,
    _*_ ,
    _prototype : zarr.core.buffer.BufferPrototype | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.NDArrayLikeOrScalar#

    

Asynchronous function that retrieves a subset of the array’s data based on the
provided selection.

Parameters:

    

**selection** BasicSelection

    

A selection object specifying the subset of data to retrieve.

**prototype** BufferPrototype, optional

    

A buffer prototype to use for the retrieved data (default is None).

Returns:

    

NDArrayLikeOrScalar

    

The retrieved subset of the array’s data.

Examples

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

_async _info_complete() -> Any#

    

Return all the information for an array, including dynamic information like a
storage size.

In addition to the static information, this provides

  * The count of chunks initialized

  * The sum of the bytes written

Returns:

    

ArrayInfo

    

See also

`AsyncArray.info`

    

A property giving just the statically known information about an array.

_async _nbytes_stored() ->
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

_async _nchunks_initialized() ->
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")#

    

Calculate the number of chunks that have been initialized, i.e. the number of
chunks that have been persisted to the storage backend.

Returns:

    

**nchunks_initialized** int

    

The number of chunks that have been initialized.

Notes

On `AsyncArray` this is an asynchronous method, unlike the (synchronous)
property `Array.nchunks_initialized`.

Examples

    
    
    >>> arr = await zarr.api.asynchronous.create(shape=(10,), chunks=(2,))
    >>> await arr.nchunks_initialized()
    0
    >>> await arr.setitem(slice(5), 1)
    >>> await arr.nchunks_initialized()
    3
    

_classmethod _open(

    _store : zarr.storage.StoreLike_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 3_,
) -> AsyncArray[zarr.core.metadata.ArrayV3Metadata] | AsyncArray[zarr.core.metadata.ArrayV2Metadata]#
    

Async:

    

Async method to open an existing Zarr array from a given store.

Parameters:

    

**store** StoreLike

    

The store containing the Zarr array.

**zarr_format** ZarrFormat | None, optional
    

The Zarr format version (default is 3).

Returns:

    

AsyncArray

    

The opened Zarr array.

Examples

    
    
    >>> import zarr
    >>>  store = zarr.storage.MemoryStore()
    >>>  async_arr = await AsyncArray.open(store) 
    <AsyncArray memory://... shape=(100, 100) dtype=int32>
    

_async _resize(

    _new_shape : zarr.core.common.ShapeLike_,
    _delete_outside_chunks : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = True_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Asynchronously resize the array to a new shape.

Parameters:

    

**new_shape** ChunkCoords

    

The desired new shape of the array.

**delete_outside_chunks** bool, optional

    

If True (default), chunks that fall outside the new shape will be deleted. If
False, the data in those chunks will be preserved.

Returns:

    

AsyncArray

    

The resized array.

Raises:

    

ValueError

    

If the new shape is incompatible with the current array’s chunking
configuration.

Notes

  * This method is asynchronous and should be awaited.

_async _setitem(

    _selection : zarr.core.indexing.BasicSelection_,
    _value : numpy.typing.ArrayLike_,
    _prototype : zarr.core.buffer.BufferPrototype | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Asynchronously set values in the array using basic indexing.

Parameters:

    

**selection** BasicSelection

    

The selection defining the region of the array to set.

**value** numpy.typing.ArrayLike

    

The values to be written into the selected region of the array.

**prototype** BufferPrototype or None, optional

    

A prototype buffer that defines the structure and properties of the array
chunks being modified. If None, the default buffer prototype is used. Default
is None.

Returns:

    

None

    

This method does not return any value.

Raises:

    

IndexError

    

If the selection is out of bounds for the array.

ValueError

    

If the values are not compatible with the array’s dtype or shape.

Notes

  * This method is asynchronous and should be awaited.

  * Supports basic indexing, where the selection is contiguous and does not involve advanced indexing.

_async _update_attributes(_new_attributes :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), zarr.core.common.JSON]_) -> Self#

    

Asynchronously update the array’s attributes.

Parameters:

    

**new_attributes** dict of str to JSON

    

A dictionary of new attributes to update or add to the array. The keys
represent attribute names, and the values must be JSON-compatible.

Returns:

    

AsyncArray

    

The array with the updated attributes.

Raises:

    

ValueError

    

If the attributes are invalid or incompatible with the array’s metadata.

Notes

  * This method is asynchronous and should be awaited.

  * The updated attributes will be merged with existing attributes, and any conflicts will be overwritten by the new values.

_property _attrs _:
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), zarr.core.common.JSON]_#

    

Returns the attributes of the array.

Returns:

    

dict

    

Attributes of the array

_property _basename _:
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_#

    

Final component of name.

Returns:

    

str

    

The basename or final component of the array name.

_property _cdata_shape _: zarr.core.common.ChunkCoords_#

    

The shape of the chunk grid for this array.

Returns:

    

Tuple[int]

    

The shape of the chunk grid for this array.

_property _chunks _: zarr.core.common.ChunkCoords_#

    

Returns the chunk shape of the Array. If sharding is used the inner chunk
shape is returned.

Only defined for arrays using using RegularChunkGrid. If array doesn’t use
RegularChunkGrid, NotImplementedError is raised.

Returns:

    

ChunkCoords:

    

The chunk shape of the Array.

codec_pipeline _: zarr.abc.codec.CodecPipeline_#

    

_property _compressor _: [numcodecs.abc.Codec](https://numcodecs.readthedocs.io/en/stable/abc.html#numcodecs.abc.Codec "\(in numcodecs v0.16.1\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")_#
    

Compressor that is applied to each chunk of the array.

Deprecated since version 3.0.0: array.compressor is deprecated and will be
removed in a future release. Use array.compressors instead.

_property _compressors _: [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[numcodecs.abc.Codec](https://numcodecs.readthedocs.io/en/stable/abc.html#numcodecs.abc.Codec "\(in numcodecs v0.16.1\)"), Ellipsis] | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[zarr.abc.codec.BytesBytesCodec, Ellipsis]_#
    

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

_property _dtype _: zarr.core.dtype.wrapper.TBaseDType_#

    

Returns the data type of the array.

Returns:

    

np.dtype

    

Data type of the array

_property _filters _: [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[numcodecs.abc.Codec](https://numcodecs.readthedocs.io/en/stable/abc.html#numcodecs.abc.Codec "\(in numcodecs v0.16.1\)"), Ellipsis] | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[zarr.abc.codec.ArrayArrayCodec, Ellipsis]_#
    

Filters that are applied to each chunk of the array, in order, before
serializing that chunk to bytes.

_property _info _: Any_#

    

Return the statically known information for an array.

Returns:

    

ArrayInfo

    

See also

`AsyncArray.info_complete`

    

All information about a group, including dynamic information like the number
of bytes and chunks written.

Examples

    
    
    >>> arr = await zarr.api.asynchronous.create(
    ...     path="array", shape=(3, 4, 5), chunks=(2, 2, 2))
    ... )
    >>> arr.info
    Type               : Array
    Zarr format        : 3
    Data type          : DataType.float64
    Shape              : (3, 4, 5)
    Chunk shape        : (2, 2, 2)
    Order              : C
    Read-only          : False
    Store type         : MemoryStore
    Codecs             : [{'endian': <Endian.little: 'little'>}]
    No. bytes          : 480
    

metadata _: zarr.core.metadata.T_ArrayMetadata_#

    

_property _name _: [str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")_#

    

Array name following h5py convention.

Returns:

    

str

    

The name of the array.

_property _nbytes _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The total number of bytes that can be stored in the chunks of this array.

Notes

This value is calculated by multiplying the number of elements in the array
and the size of each element, the latter of which is determined by the dtype
of the array. For this reason, `nbytes` will likely be inaccurate for arrays
with variable-length dtypes. It is not possible to determine the size of an
array with variable-length elements from the shape and dtype alone.

_property _nchunks _:
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")_#

    

The number of chunks in the stored representation of this array.

Returns:

    

int

    

The total number of chunks in the array.

_property _ndim _: [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")_#

    

Returns the number of dimensions in the Array.

Returns:

    

int

    

The number of dimensions in the Array.

_property _order _: zarr.core.common.MemoryOrder_#

    

Returns the memory order of the array.

Returns:

    

bool

    

Memory order of the array

_property _path _: [str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")_#

    

Storage path.

Returns:

    

str

    

The path to the array in the Zarr store.

_property _read_only _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

Returns True if the array is read-only.

Returns:

    

bool

    

True if the array is read-only

_property _serializer _: zarr.abc.codec.ArrayBytesCodec | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")_#
    

Array-to-bytes codec to use for serializing the chunks into bytes.

_property _shape _: zarr.core.common.ChunkCoords_#

    

Returns the shape of the Array.

Returns:

    

tuple

    

The shape of the Array.

_property _shards _: zarr.core.common.ChunkCoords | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")_#
    

Returns the shard shape of the Array. Returns None if sharding is not used.

Only defined for arrays using using RegularChunkGrid. If array doesn’t use
RegularChunkGrid, NotImplementedError is raised.

Returns:

    

ChunkCoords:

    

The shard shape of the Array.

_property _size _: [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)")_#

    

Returns the total number of elements in the array

Returns:

    

int

    

Total number of elements in the array

_property _store _: zarr.abc.store.Store_#

    

store_path _: zarr.storage._common.StorePath_#

    

_class _zarr.AsyncGroup#

    

Asynchronous Group object.

_async _array_keys() ->
[collections.abc.AsyncGenerator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncGenerator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")]#

    

Iterate over array names.

_async _array_values() -> [collections.abc.AsyncGenerator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncGenerator "\(in Python v3.13\)")[zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata], [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Iterate over array values.

_async _arrays() -> [collections.abc.AsyncGenerator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncGenerator "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]], [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

Iterate over arrays.

_async _contains(_member :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [bool](https://docs.python.org/3/library/functions.html#bool
"\(in Python v3.13\)")#

    

Check if a member exists in the group.

Parameters:

    

**member** str

    

Member name.

Returns:

    

bool

    

_async _create_array(

    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _*_ ,
    _shape : zarr.core.common.ShapeLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dtype : zarr.core.dtype.ZDTypeLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _data : [numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "\(in NumPy v2.3\)")[Any, [numpy.dtype](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype "\(in NumPy v2.3\)")[Any]] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunks : zarr.core.common.ChunkCoords | Literal['auto'] = 'auto'_,
    _shards : zarr.core.array.ShardsLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _filters : zarr.core.array.FiltersLike = 'auto'_,
    _compressors : zarr.core.array.CompressorsLike = 'auto'_,
    _compressor : zarr.core.array.CompressorLike = 'auto'_,
    _serializer : zarr.core.array.SerializerLike = 'auto'_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = DEFAULT_FILL_VALUE_,
    _order : zarr.core.common.MemoryOrder | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_key_encoding : zarr.core.chunk_key_encodings.ChunkKeyEncodingLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_names : zarr.core.common.DimensionNames = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _config : zarr.core.array_spec.ArrayConfigLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _write_data : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = True_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.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** ChunkCoords

    

Shape of the array.

**dtype** npt.DTypeLike

    

Data type of the array.

**chunks** ChunkCoords, optional

    

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

**shards** ChunkCoords, optional

    

Shard shape of the array. The default value of `None` results in no sharding
at all.

**filters** Iterable[Codec], 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 `ArrayArrayCodec`, or dict
representations of `ArrayArrayCodec`. If no `filters` are provided, a default
set of filters will be used. These defaults can be changed by modifying the
value of `array.v3_default_filters` in `zarr.core.config`. Use `None` to omit
default filters.

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. If no `filters` are provided, a default set of filters will be used.
These defaults can be changed by modifying the value of
`array.v2_default_filters` in `zarr.core.config`. Use `None` to omit default
filters.

**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.core.config`. Use `None` to omit
default compressors.

For Zarr format 2, a “compressor” can be any numcodecs codec. Only a single
compressor may be provided for Zarr format 2. If no `compressor` is provided,
a default compressor will be used. in `zarr.core.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.core.config`.

**fill_value** Any, optional

    

Fill value for the array.

**order**{“C”, “F”}, optional

    

The memory of the array (default is “C”). For Zarr format 2, this parameter
sets the memory order of the array. For Zarr format 3, this parameter is
deprecated, because memory order is a runtime parameter for Zarr format 3
arrays. The recommended way to specify the memory order for Zarr format 3
arrays is via the `config` parameter, e.g. `{'config': 'C'}`. If no `order` is
provided, a default order will be used. This default can be changed by
modifying the value of `array.order` in `zarr.core.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

    

_async _create_dataset(

    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _*_ ,
    _shape : zarr.core.common.ShapeLike_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]#
    

Create an array.

Deprecated since version 3.0.0: The h5py compatibility methods will be removed
in 3.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

    

_async _create_group(

    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _*_ ,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 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

    

_async _create_hierarchy(

    _nodes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.metadata.ArrayV2Metadata | zarr.core.metadata.ArrayV3Metadata | GroupMetadata]_,
    _*_ ,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
) -> [collections.abc.AsyncIterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncIterator "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), AsyncGroup | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.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].
    

_async _delitem(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

Delete a group member.

Parameters:

    

**key** str

    

Array or group name

_async _empty(

    _*_ ,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _shape : zarr.core.common.ChunkCoords_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.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.

_async _empty_like(

    _*_ ,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _data : zarr.api.asynchronous.ArrayLike_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.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.

_classmethod _from_dict(

    _store_path : zarr.storage.StorePath_,
    _data : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any]_,
) -> AsyncGroup#

    

_classmethod _from_store(

    _store : zarr.storage.StoreLike_,
    _*_ ,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _zarr_format : zarr.core.common.ZarrFormat = 3_,
) -> AsyncGroup#

    

Async:

    

_async _full(

    _*_ ,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _shape : zarr.core.common.ChunkCoords_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.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.

_async _full_like(

    _*_ ,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _data : zarr.api.asynchronous.ArrayLike_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.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.

_async _get(

    _key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _default : DefaultT | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.array.AsyncArray[Any] | AsyncGroup | DefaultT | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")#
    

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.

_async _getitem(

    _key : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata] | AsyncGroup#
    

Get a subarray or subgroup from the group.

Parameters:

    

**key** str

    

Array or group name

Returns:

    

AsyncArray or AsyncGroup

    

_async _group_keys() ->
[collections.abc.AsyncGenerator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncGenerator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")]#

    

Iterate over group names.

_async _group_values() ->
[collections.abc.AsyncGenerator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncGenerator
"\(in Python v3.13\)")[AsyncGroup,
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

    

Iterate over group values.

_async _groups() ->
[collections.abc.AsyncGenerator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncGenerator
"\(in Python
v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"), AsyncGroup],
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

    

Iterate over subgroups.

_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

    

See also

`AsyncGroup.info`

    

_async _keys() ->
[collections.abc.AsyncGenerator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncGenerator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")]#

    

Iterate over member names.

_async _members(

    _max_depth : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 0_,
    _*_ ,
    _use_consolidated_for_children : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = True_,
) -> [collections.abc.AsyncGenerator](https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncGenerator "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata] | AsyncGroup], [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")]#
    

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

_abstract _move(_source :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_, _dest : [str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Async:

    

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

Notes

Not implemented

_async _nmembers(_max_depth : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 0_) -> [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")#
    

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

    

_async _ones(

    _*_ ,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _shape : zarr.core.common.ChunkCoords_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.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.

_async _ones_like(

    _*_ ,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _data : zarr.api.asynchronous.ArrayLike_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.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.

_classmethod _open(

    _store : zarr.storage.StoreLike_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 3_,
    _use_consolidated : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> AsyncGroup#

    

Async:

    

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.

_async _require_array(

    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _*_ ,
    _shape : zarr.core.common.ShapeLike_,
    _dtype : numpy.typing.DTypeLike = None_,
    _exact : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.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

    

_async _require_dataset(

    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _*_ ,
    _shape : zarr.core.common.ChunkCoords_,
    _dtype : numpy.typing.DTypeLike = None_,
    _exact : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]#
    

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

Deprecated since version 3.0.0: The h5py compatibility methods will be removed
in 3.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

    

_async _require_group(_name :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_, _overwrite :
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)") = 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

    

_async _require_groups(_* names:
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [tuple](https://docs.python.org/3/library/stdtypes.html#tuple
"\(in Python v3.13\)")[AsyncGroup, Ellipsis]#

    

Convenience method to require multiple groups in a single call.

Parameters:

    

***names** str

    

Group names.

Returns:

    

Tuple[AsyncGroup, …]

    

_async _setitem(_key :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_, _value : Any_) ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

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

_async _tree(_expand : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_, _level : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 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.

_async _update_attributes(_new_attributes :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), Any]_) -> AsyncGroup#

    

Update group attributes.

Parameters:

    

**new_attributes** dict

    

New attributes to set on the group.

Returns:

    

**self** AsyncGroup

    

_async _zeros(

    _*_ ,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _shape : zarr.core.common.ChunkCoords_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.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.

_async _zeros_like(

    _*_ ,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _data : zarr.api.asynchronous.ArrayLike_,
    _** kwargs: Any_,
) -> zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.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.

_property _attrs _:
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), Any]_#

    

_property _basename _:
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_#

    

Final component of name.

_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

    

See also

`AsyncGroup.info_complete`

    

All information about a group, including dynamic information

metadata _: GroupMetadata_#

    

_property _name _: [str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")_#

    

Group name following h5py convention.

_property _path _: [str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")_#

    

Storage path.

_property _read_only _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

_property _store _: zarr.abc.store.Store_#

    

store_path _: zarr.storage.StorePath_#

    

_property _synchronizer _:
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")_#

    

_class _zarr.Group#

    

Bases: `zarr.core.sync.SyncMixin`

A Zarr group.

array(

    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _*_ ,
    _shape : zarr.core.common.ShapeLike_,
    _dtype : numpy.typing.DTypeLike_,
    _chunks : zarr.core.common.ChunkCoords | Literal['auto'] = 'auto'_,
    _shards : zarr.core.common.ChunkCoords | Literal['auto'] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _filters : zarr.core.array.FiltersLike = 'auto'_,
    _compressors : zarr.core.array.CompressorsLike = 'auto'_,
    _compressor : zarr.core.array.CompressorLike = None_,
    _serializer : zarr.core.array.SerializerLike = 'auto'_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = DEFAULT_FILL_VALUE_,
    _order : zarr.core.common.MemoryOrder | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_key_encoding : zarr.core.chunk_key_encodings.ChunkKeyEncodingLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_names : zarr.core.common.DimensionNames = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _config : zarr.core.array_spec.ArrayConfig | zarr.core.array_spec.ArrayConfigLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _data : numpy.typing.ArrayLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.array.Array#

    

Create an array within this group.

Deprecated since version 3.0.0: 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** ChunkCoords

    

Shape of the array.

**dtype** npt.DTypeLike

    

Data type of the array.

**chunks** ChunkCoords, optional

    

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

**shards** ChunkCoords, optional

    

Shard shape of the array. The default value of `None` results in no sharding
at all.

**filters** Iterable[Codec], 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 `ArrayArrayCodec`, or dict
representations of `ArrayArrayCodec`. If no `filters` are provided, a default
set of filters will be used. These defaults can be changed by modifying the
value of `array.v3_default_filters` in `zarr.core.config`. Use `None` to omit
default filters.

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. If no `filters` are provided, a default set of filters will be used.
These defaults can be changed by modifying the value of
`array.v2_default_filters` in `zarr.core.config`. Use `None` to omit default
filters.

**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.core.config`. Use `None` to omit
default compressors.

For Zarr format 2, a “compressor” can be any numcodecs codec. Only a single
compressor may be provided for Zarr format 2. If no `compressor` is provided,
a default compressor will be used. in `zarr.core.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.core.config`.

**fill_value** Any, optional

    

Fill value for the array.

**order**{“C”, “F”}, optional

    

The memory of the array (default is “C”). For Zarr format 2, this parameter
sets the memory order of the array. For Zarr format 3, this parameter is
deprecated, because memory order is a runtime parameter for Zarr format 3
arrays. The recommended way to specify the memory order for Zarr format 3
arrays is via the `config` parameter, e.g. `{'config': 'C'}`. If no `order` is
provided, a default order will be used. This default can be changed by
modifying the value of `array.order` in `zarr.core.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

    

array_keys() ->
[collections.abc.Generator](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")]#

    

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
    

array_values() ->
[collections.abc.Generator](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator
"\(in Python v3.13\)")[zarr.core.array.Array,
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

    

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>
    

arrays() ->
[collections.abc.Generator](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator
"\(in Python
v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"), zarr.core.array.Array],
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

    

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>
    

create(_* args: Any_, _** kwargs: Any_) -> zarr.core.array.Array#

    

create_array(

    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _*_ ,
    _shape : zarr.core.common.ShapeLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dtype : zarr.core.dtype.ZDTypeLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _data : [numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "\(in NumPy v2.3\)")[Any, [numpy.dtype](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype "\(in NumPy v2.3\)")[Any]] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunks : zarr.core.common.ChunkCoords | Literal['auto'] = 'auto'_,
    _shards : zarr.core.array.ShardsLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _filters : zarr.core.array.FiltersLike = 'auto'_,
    _compressors : zarr.core.array.CompressorsLike = 'auto'_,
    _compressor : zarr.core.array.CompressorLike = 'auto'_,
    _serializer : zarr.core.array.SerializerLike = 'auto'_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = DEFAULT_FILL_VALUE_,
    _order : zarr.core.common.MemoryOrder | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_key_encoding : zarr.core.chunk_key_encodings.ChunkKeyEncodingLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_names : zarr.core.common.DimensionNames = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _config : zarr.core.array_spec.ArrayConfigLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _write_data : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = True_,
) -> zarr.core.array.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** ChunkCoords, optional

    

Shape of the array. Can be `None` if `data` is provided.

**dtype** npt.DTypeLike | None
    

Data type of the array. Can 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 identical to `data.shape` and
`data.dtype`, or `None`.

**chunks** ChunkCoords, optional

    

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

**shards** ChunkCoords, optional

    

Shard shape of the array. The default value of `None` results in no sharding
at all.

**filters** Iterable[Codec], 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 `ArrayArrayCodec`, or dict
representations of `ArrayArrayCodec`. If no `filters` are provided, a default
set of filters will be used. These defaults can be changed by modifying the
value of `array.v3_default_filters` in `zarr.core.config`. Use `None` to omit
default filters.

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. If no `filters` are provided, a default set of filters will be used.
These defaults can be changed by modifying the value of
`array.v2_default_filters` in `zarr.core.config`. Use `None` to omit default
filters.

**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.core.config`. Use `None` to omit
default compressors.

For Zarr format 2, a “compressor” can be any numcodecs codec. Only a single
compressor may be provided for Zarr format 2. If no `compressor` is provided,
a default compressor will be used. in `zarr.core.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.core.config`.

**fill_value** Any, optional

    

Fill value for the array.

**order**{“C”, “F”}, optional

    

The memory of the array (default is “C”). For Zarr format 2, this parameter
sets the memory order of the array. For Zarr format 3, this parameter is
deprecated, because memory order is a runtime parameter for Zarr format 3
arrays. The recommended way to specify the memory order for Zarr format 3
arrays is via the `config` parameter, e.g. `{'config': 'C'}`. If no `order` is
provided, a default order will be used. This default can be changed by
modifying the value of `array.order` in `zarr.core.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

    

create_dataset(_name :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_, _** kwargs: Any_) -> zarr.core.array.Array#

    

Create an array.

Deprecated since version 3.0.0: The h5py compatibility methods will be removed
in 3.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

    

create_group(_name : [str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")_, _** 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>
    

create_hierarchy(

    _nodes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.metadata.ArrayV2Metadata | zarr.core.metadata.ArrayV3Metadata | GroupMetadata]_,
    _*_ ,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
) -> [collections.abc.Iterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterator "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Group | zarr.core.array.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>
    

empty(

    _*_ ,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _shape : zarr.core.common.ChunkCoords_,
    _** kwargs: Any_,
) -> zarr.core.array.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.

empty_like(

    _*_ ,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _data : zarr.api.asynchronous.ArrayLike_,
    _** kwargs: Any_,
) -> zarr.core.array.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.

_classmethod _from_store(

    _store : zarr.storage.StoreLike_,
    _*_ ,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat = 3_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = 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

    

full(

    _*_ ,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _shape : zarr.core.common.ChunkCoords_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")_,
    _** kwargs: Any_,
) -> zarr.core.array.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.

full_like(

    _*_ ,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _data : zarr.api.asynchronous.ArrayLike_,
    _** kwargs: Any_,
) -> zarr.core.array.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.

get(

    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _default : DefaultT | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.array.Array | Group | DefaultT | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)")#
    

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)
    

group_keys() ->
[collections.abc.Generator](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")]#

    

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
    

group_values() ->
[collections.abc.Generator](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator
"\(in Python v3.13\)")[Group,
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

    

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>
    

groups() ->
[collections.abc.Generator](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator
"\(in Python
v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in
Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)"), Group],
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")]#

    

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>
    

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

    

See also

`Group.info`

    

keys() ->
[collections.abc.Generator](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator
"\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")]#

    

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
    

members(

    _max_depth : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 0_,
    _*_ ,
    _use_consolidated_for_children : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = True_,
) -> [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.array.Array | Group], Ellipsis]#
    

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

move(_source : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)")_, _dest :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [None](https://docs.python.org/3/library/constants.html#None
"\(in Python v3.13\)")#

    

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

Notes

Not implemented

nmembers(_max_depth : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 0_) -> [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")#
    

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

    

ones(

    _*_ ,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _shape : zarr.core.common.ChunkCoords_,
    _** kwargs: Any_,
) -> zarr.core.array.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.

ones_like(

    _*_ ,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _data : zarr.api.asynchronous.ArrayLike_,
    _** kwargs: Any_,
) -> zarr.core.array.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.

_classmethod _open(

    _store : zarr.storage.StoreLike_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 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.

require_array(

    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _*_ ,
    _shape : zarr.core.common.ShapeLike_,
    _** kwargs: Any_,
) -> zarr.core.array.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

    

require_dataset(

    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _*_ ,
    _shape : zarr.core.common.ShapeLike_,
    _** kwargs: Any_,
) -> zarr.core.array.Array#

    

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

Deprecated since version 3.0.0: The h5py compatibility methods will be removed
in 3.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

    

require_group(_name :
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_, _** kwargs: Any_) -> Group#

    

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

Parameters:

    

**name** str

    

Group name.

Returns:

    

**g** Group

    

require_groups(_* names:
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_) -> [tuple](https://docs.python.org/3/library/stdtypes.html#tuple
"\(in Python v3.13\)")[Group, Ellipsis]#

    

Convenience method to require multiple groups in a single call.

Parameters:

    

***names** str

    

Group names.

Returns:

    

**groups** tuple of Groups

    

tree(_expand : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_, _level : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 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.

update_attributes(_new_attributes :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), Any]_) -> Group#

    

Update the attributes of this group.

Examples

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

_async _update_attributes_async(_new_attributes :
[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python
v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in
Python v3.13\)"), 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'}
    

zeros(

    _*_ ,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _shape : zarr.core.common.ChunkCoords_,
    _** kwargs: Any_,
) -> zarr.core.array.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.

zeros_like(

    _*_ ,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _data : zarr.api.asynchronous.ArrayLike_,
    _** kwargs: Any_,
) -> zarr.core.array.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.

_property _attrs _: zarr.core.attributes.Attributes_#

    

Attributes of this Group

_property _basename _:
[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python
v3.13\)")_#

    

Final component of name.

_property _info _: Any_#

    

Return the statically known information for a group.

Returns:

    

GroupInfo

    

See also

`Group.info_complete`

    

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

_property _metadata _: GroupMetadata_#

    

Group metadata.

_property _name _: [str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")_#

    

Group name following h5py convention.

_property _path _: [str](https://docs.python.org/3/library/stdtypes.html#str
"\(in Python v3.13\)")_#

    

Storage path.

_property _read_only _:
[bool](https://docs.python.org/3/library/functions.html#bool "\(in Python
v3.13\)")_#

    

_property _store _: zarr.abc.store.Store_#

    

_property _store_path _: zarr.storage.StorePath_#

    

Path-like interface for the Store.

_property _synchronizer _:
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")_#

    

zarr.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 `create()`.

Returns:

    

**array** Array

    

The new array.

zarr.consolidate_metadata(

    _store : zarr.storage.StoreLike_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 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. For Stores that do not use
consolidated metadata, this operation raises a TypeError.

Parameters:

    

**store** StoreLike

    

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

**path** str, optional

    

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

By default, the root node is used so all the metadata in the store is
consolidated.

**zarr_format**{2, 3, None}, optional

    

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

Returns:

    

group: Group

    

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

zarr.copy(_* args: Any_, _** kwargs: Any_) ->
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)"),
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")]#

    

zarr.copy_all(_* args: Any_, _** kwargs: Any_) ->
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)"),
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")]#

    

zarr.copy_store(_* args: Any_, _** kwargs: Any_) ->
[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python
v3.13\)")[[int](https://docs.python.org/3/library/functions.html#int "\(in
Python v3.13\)"), [int](https://docs.python.org/3/library/functions.html#int
"\(in Python v3.13\)"),
[int](https://docs.python.org/3/library/functions.html#int "\(in Python
v3.13\)")]#

    

zarr.create(

    _shape : zarr.core.common.ChunkCoords | [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)")_,
    _*_ ,
    _chunks : zarr.core.common.ChunkCoords | [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dtype : zarr.core.dtype.ZDTypeLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _compressor : zarr.core.array.CompressorLike = 'auto'_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = DEFAULT_FILL_VALUE_,
    _order : zarr.core.common.MemoryOrder | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _store : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _synchronizer : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _path : zarr.api.asynchronous.PathLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _filters : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[[dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [numcodecs.abc.Codec](https://numcodecs.readthedocs.io/en/stable/abc.html#numcodecs.abc.Codec "\(in numcodecs v0.16.1\)")] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _cache_metadata : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _cache_attrs : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _read_only : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _object_codec : zarr.abc.codec.Codec | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_separator : Literal['.', '/'] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _write_empty_chunks : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _meta_array : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_shape : zarr.core.common.ChunkCoords | [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_key_encoding : zarr.core.chunk_key_encodings.ChunkKeyEncoding | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[Literal['default'], Literal['.', '/']] | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[Literal['v2'], Literal['.', '/']] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _codecs : [collections.abc.Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "\(in Python v3.13\)")[zarr.abc.codec.Codec | [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON]] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_names : zarr.core.common.DimensionNames = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _config : zarr.core.array_spec.ArrayConfigLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 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.

**fill_value** object

    

Default value to use for uninitialized portions of 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** Store or str

    

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** MutableMapping, optional

    

Separate storage for chunks. If not provided, store will be used for storage
of both chunks and metadata.

**filters** sequence of Codecs, optional

    

Sequence of filters to use to encode chunk data prior to compression.

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

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

**meta_array** array-like, optional

    

An array instance to use for determining arrays to create and return to users.
Use numpy.empty(()) by default.

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

zarr.create_array(

    _store : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | zarr.storage.StoreLike_,
    _*_ ,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _shape : zarr.core.common.ShapeLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dtype : zarr.core.dtype.ZDTypeLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _data : [numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "\(in NumPy v2.3\)")[Any, [numpy.dtype](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype "\(in NumPy v2.3\)")[Any]] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunks : zarr.core.common.ChunkCoords | Literal['auto'] = 'auto'_,
    _shards : zarr.core.array.ShardsLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _filters : zarr.core.array.FiltersLike = 'auto'_,
    _compressors : zarr.core.array.CompressorsLike = 'auto'_,
    _serializer : zarr.core.array.SerializerLike = 'auto'_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = DEFAULT_FILL_VALUE_,
    _order : zarr.core.common.MemoryOrder | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 3_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_key_encoding : zarr.core.chunk_key_encodings.ChunkKeyEncodingLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_names : zarr.core.common.DimensionNames = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _config : zarr.core.array_spec.ArrayConfigLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _write_data : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = True_,
) -> zarr.core.array.Array#

    

Create an array.

This function wraps `zarr.core.array.create_array()`.

Parameters:

    

**store** str or Store

    

Store or path to directory in file system or name of zip file.

**name** str or None, optional

    

The name of the array within the store. If `name` is `None`, the array will be
located at the root of the store.

**shape** ChunkCoords, optional

    

Shape of the array. Can be `None` if `data` is provided.

**dtype** ZDTypeLike, optional

    

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

**data** np.ndarray, optional

    

Array-like data to use for initializing the array. If this parameter is
provided, the `shape` and `dtype` parameters must be identical to `data.shape`
and `data.dtype`, or `None`.

**chunks** ChunkCoords, optional

    

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

**shards** ChunkCoords, optional

    

Shard shape of the array. The default value of `None` results in no sharding
at all.

**filters** Iterable[Codec], 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 `ArrayArrayCodec`, or dict
representations of `ArrayArrayCodec`. If no `filters` are provided, a default
set of filters will be used. These defaults can be changed by modifying the
value of `array.v3_default_filters` in `zarr.core.config`. Use `None` to omit
default filters.

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. If no `filters` are provided, a default set of filters will be used.
These defaults can be changed by modifying the value of
`array.v2_default_filters` in `zarr.core.config`. Use `None` to omit default
filters.

**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.core.config`. Use `None` to omit
default compressors.

For Zarr format 2, a “compressor” can be any numcodecs codec. Only a single
compressor may be provided for Zarr format 2. If no `compressor` is provided,
a default compressor will be used. in `zarr.core.config`. Use `None` to omit
the default compressor.

**serializer** dict[str, JSON] | ArrayBytesCodec, optional
    

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

**fill_value** Any, optional

    

Fill value for the array.

**order**{“C”, “F”}, optional

    

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

**zarr_format**{2, 3}, optional

    

The zarr format to use when saving.

**attributes** dict, optional

    

Attributes for the array.

**chunk_key_encoding** 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.
If True, all existing paths in the store will be deleted.

**config** ArrayConfigLike, optional

    

Runtime configuration for the array.

**write_data** bool

    

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

Returns:

    

Array

    

The array.

Examples

    
    
    >>> import zarr
    >>> store = zarr.storage.MemoryStore()
    >>> arr = await zarr.create_array(
    >>>     store=store,
    >>>     shape=(100,100),
    >>>     chunks=(10,10),
    >>>     dtype='i4',
    >>>     fill_value=0)
    <Array memory://140349042942400 shape=(100, 100) dtype=int32>
    

zarr.create_group(

    _store : zarr.storage.StoreLike_,
    _*_ ,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.group.Group#

    

Create a group.

Parameters:

    

**store** Store or str

    

Store or path to directory in file system.

**path** str, optional

    

Group path within store.

**overwrite** bool, optional

    

If True, pre-existing data at `path` will be deleted before creating the
group.

**zarr_format**{2, 3, None}, optional

    

The zarr format to use when saving. If no `zarr_format` is provided, the
default format will be used. This default can be changed by modifying the
value of `default_zarr_format` in `zarr.core.config`.

**storage_options** dict

    

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

Returns:

    

Group

    

The new group.

zarr.create_hierarchy(

    _*_ ,
    _store : zarr.abc.store.Store_,
    _nodes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.group.GroupMetadata | zarr.core.metadata.ArrayV2Metadata | zarr.core.metadata.ArrayV3Metadata]_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
) -> [collections.abc.Iterator](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterator "\(in Python v3.13\)")[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.group.Group | zarr.core.array.Array]]#
    

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

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

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

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

Parameters:

    

**store** Store

    

The storage backend to use.

**nodes** dict[str, GroupMetadata | ArrayV3Metadata | ArrayV2Metadata]
    

A dictionary defining the hierarchy. The keys are the paths of the nodes in
the hierarchy, relative to the root of the `Store`. The root of the store can
be specified with the empty string `''`. The values are instances of
`GroupMetadata` or `ArrayMetadata`. Note that all values must have the same
`zarr_format` – it is an error to mix zarr versions in the same hierarchy.

Leading “/” characters from keys will be removed.

**overwrite** bool

    

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

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

Yields:

    

tuple[str, Group | Array]
    

This function yields (path, node) pairs, in the order the nodes were created.

Examples

    
    
    >>> from zarr import create_hierarchy
    >>> from zarr.storage import MemoryStore
    >>> from zarr.core.group import GroupMetadata
    
    
    
    >>> store = MemoryStore()
    >>> nodes = {'a': GroupMetadata(attributes={'name': 'leaf'})}
    >>> nodes_created = dict(create_hierarchy(store=store, nodes=nodes))
    >>> print(nodes)
    # {'a': GroupMetadata(attributes={'name': 'leaf'}, zarr_format=3, consolidated_metadata=None, node_type='group')}
    

zarr.empty(

    _shape : zarr.core.common.ChunkCoords_,
    _** 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 `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.

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

zarr.from_array(

    _store : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | zarr.storage.StoreLike_,
    _*_ ,
    _data : zarr.core.array.Array | numpy.typing.ArrayLike_,
    _write_data : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = True_,
    _name : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunks : Literal['auto', 'keep'] | zarr.core.common.ChunkCoords = 'keep'_,
    _shards : zarr.core.array.ShardsLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") | Literal['keep'] = 'keep'_,
    _filters : zarr.core.array.FiltersLike | Literal['keep'] = 'keep'_,
    _compressors : zarr.core.array.CompressorsLike | Literal['keep'] = 'keep'_,
    _serializer : zarr.core.array.SerializerLike | Literal['keep'] = 'keep'_,
    _fill_value : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = DEFAULT_FILL_VALUE_,
    _order : zarr.core.common.MemoryOrder | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_key_encoding : zarr.core.chunk_key_encodings.ChunkKeyEncodingLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _dimension_names : zarr.core.common.DimensionNames = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _config : zarr.core.array_spec.ArrayConfigLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.array.Array#

    

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

Parameters:

    

**store** str or Store

    

Store or path to directory in file system or name of zip file for the new
array.

**data** Array | array-like
    

The array to copy.

**write_data** bool, default True

    

Whether to copy the data from the input array to the new array. If
`write_data` is `False`, the new array will be created with the same metadata
as the input array, but without any data.

**name** str or None, optional

    

The name of the array within the store. If `name` is `None`, the array will be
located at the root of the store.

**chunks** ChunkCoords or “auto” or “keep”, optional

    

Chunk shape of the array. Following values are supported:

  * “auto”: Automatically determine the chunk shape based on the array’s shape and dtype.

  * “keep”: Retain the chunk shape of the data array if it is a zarr Array.

  * ChunkCoords: A tuple of integers representing the chunk shape.

If not specified, defaults to “keep” if data is a zarr Array, otherwise
“auto”.

**shards** ChunkCoords, optional

    

Shard shape of the array. Following values are supported:

  * “auto”: Automatically determine the shard shape based on the array’s shape and chunk shape.

  * “keep”: Retain the shard shape of the data array if it is a zarr Array.

  * ChunkCoords: A tuple of integers representing the shard shape.

  * None: No sharding.

If not specified, defaults to “keep” if data is a zarr Array, otherwise None.

**filters** Iterable[Codec] or “auto” or “keep”, optional

    

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

For Zarr format 3, a “filter” is a codec that takes an array and returns an
array, and these values must be instances of `ArrayArrayCodec`, or dict
representations of `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.

Following values are supported:

  * Iterable[Codec]: List of filters to apply to the array.

  * “auto”: Automatically determine the filters based on the array’s dtype.

  * “keep”: Retain the filters of the data array if it is a zarr Array.

If no `filters` are provided, defaults to “keep” if data is a zarr Array,
otherwise “auto”.

**compressors** Iterable[Codec] or “auto” or “keep”, optional

    

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

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

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

Following values are supported:

  * Iterable[Codec]: List of compressors to apply to the array.

  * “auto”: Automatically determine the compressors based on the array’s dtype.

  * “keep”: Retain the compressors of the input array if it is a zarr Array.

If no `compressors` are provided, defaults to “keep” if data is a zarr Array,
otherwise “auto”.

**serializer** dict[str, JSON] | ArrayBytesCodec or “auto” or “keep”, optional
    

Array-to-bytes codec to use for encoding the array data. Zarr format 3 only.
Zarr format 2 arrays use implicit array-to-bytes conversion.

Following values are supported:

  * dict[str, JSON]: A dict representation of an `ArrayBytesCodec`.

  * ArrayBytesCodec: An instance of `ArrayBytesCodec`.

  * “auto”: a default serializer will be used. These defaults can be changed by modifying the value of `array.v3_default_serializer` in `zarr.core.config`.

  * “keep”: Retain the serializer of the input array if it is a zarr Array.

**fill_value** Any, optional

    

Fill value for the array. If not specified, defaults to the fill value of the
data array.

**order**{“C”, “F”}, optional

    

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

**zarr_format**{2, 3}, optional

    

The zarr format to use when saving. If not specified, defaults to the zarr
format of the data array.

**attributes** dict, optional

    

Attributes for the array. If not specified, defaults to the attributes of the
data array.

**chunk_key_encoding** ChunkKeyEncoding, optional

    

A specification of how the chunk keys are represented in storage. For Zarr
format 3, the default is `{"name": "default", "separator": "/"}}`. For Zarr
format 2, the default is `{"name": "v2", "separator": "."}}`. If not specified
and the data array has the same zarr format as the target array, the chunk key
encoding of the data array is used.

**dimension_names** Iterable[str], optional

    

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

**storage_options** dict, optional

    

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

**overwrite** bool, default False

    

Whether to overwrite an array with the same name in the store, if one exists.

**config** ArrayConfig or ArrayConfigLike, optional

    

Runtime configuration for the array.

Returns:

    

Array

    

The array.

Examples

Create an array from an existing Array:

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

Create an array from an existing NumPy array:

    
    
    >>> import numpy as np
    >>> arr3 = zarr.from_array(
            zarr.storage.MemoryStore(),
    >>>     data=np.arange(10000, dtype='i4').reshape(100, 100),
    >>> )
    <Array memory://125477403529984 shape=(100, 100) dtype=int32>
    

Create an array from any array-like object:

    
    
    >>> arr4 = zarr.from_array(
    >>>     zarr.storage.MemoryStore(),
    >>>     data=[[1, 2], [3, 4]],
    >>> )
    <Array memory://125477392154368 shape=(2, 2) dtype=int64>
    >>> arr4[...]
    array([[1, 2],[3, 4]])
    

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

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

zarr.full(

    _shape : zarr.core.common.ChunkCoords_,
    _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 `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

zarr.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 `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

zarr.group(

    _store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _*_ ,
    _overwrite : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") = False_,
    _chunk_store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _cache_attrs : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _synchronizer : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _meta_array : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.group.Group#

    

Create a group.

Parameters:

    

**store** Store or str, optional

    

Store or path to directory in file system.

**overwrite** bool, optional

    

If True, delete any pre-existing data in store at path before creating the
group.

**chunk_store** Store, optional

    

Separate storage for chunks. If not provided, store will be used for storage
of both chunks and metadata.

**cache_attrs** bool, optional

    

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

**synchronizer** object, optional

    

Array synchronizer.

**path** str, optional

    

Group path within store.

**meta_array** array-like, optional

    

An array instance to use for determining arrays to create and return to users.
Use numpy.empty(()) by default.

**zarr_format**{2, 3, None}, optional

    

The zarr format to use when saving.

**storage_options** dict

    

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

Returns:

    

**g** Group

    

The new group.

zarr.load(

    _store : zarr.storage.StoreLike_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.buffer.NDArrayLikeOrScalar | [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.buffer.NDArrayLikeOrScalar]#
    

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.

See also

`save`, `savez`

    

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.

zarr.ones(

    _shape : zarr.core.common.ChunkCoords_,
    _** 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 `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

zarr.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 `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

zarr.open(

    _store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _*_ ,
    _mode : zarr.core.common.AccessModeLiteral | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = 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). If the store is
read-only, the default is ‘r’; otherwise, it is ‘a’.

**zarr_format**{2, 3, None}, optional

    

The zarr format to use when saving.

**path** str or None, optional

    

The path within the store to open.

**storage_options** dict

    

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

****kwargs**

    

Additional parameters are passed through to
`zarr.api.asynchronous.open_array()` or `zarr.api.asynchronous.open_group()`.

Returns:

    

**z** array or group

    

Return type depends on what exists in the given store.

zarr.open_array(

    _store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _*_ ,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : zarr.api.asynchronous.PathLike = ''_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _** kwargs: Any_,
) -> zarr.core.array.Array#

    

Open an array using file-mode-like semantics.

Parameters:

    

**store** Store or str

    

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.

**path** str, optional

    

Path in store to array.

**storage_options** dict

    

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

****kwargs**

    

Any keyword arguments to pass to `create`.

Returns:

    

AsyncArray

    

The opened array.

zarr.open_consolidated(

    _* args: Any_,
    _use_consolidated : Literal[True] = True_,
    _** kwargs: Any_,
) -> zarr.core.group.Group#

    

Alias for `open_group()` with `use_consolidated=True`.

zarr.open_group(

    _store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _*_ ,
    _mode : zarr.core.common.AccessModeLiteral = 'a'_,
    _cache_attrs : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _synchronizer : Any = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _chunk_store : zarr.storage.StoreLike | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _meta_array : Any | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _attributes : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), zarr.core.common.JSON] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _use_consolidated : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> zarr.core.group.Group#

    

Open a group using file-mode-like semantics.

Parameters:

    

**store** Store, str, or mapping, optional

    

Store or path to directory in file system or name of zip file.

Strings are interpreted as paths on the local file system and used as the
`root` argument to `zarr.storage.LocalStore`.

Dictionaries are used as the `store_dict` argument in
`zarr.storage.MemoryStore``.

By default (`store=None`) a new `zarr.storage.MemoryStore` is created.

**mode**{‘r’, ‘r+’, ‘a’, ‘w’, ‘w-‘}, optional

    

Persistence mode: ‘r’ means read only (must exist); ‘r+’ means read/write
(must exist); ‘a’ means read/write (create if doesn’t exist); ‘w’ means create
(overwrite if exists); ‘w-’ means create (fail if exists).

**cache_attrs** bool, optional

    

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

**synchronizer** object, optional

    

Array synchronizer.

**path** str, optional

    

Group path within store.

**chunk_store** Store or str, optional

    

Store or path to directory in file system or name of zip file.

**storage_options** dict

    

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

**meta_array** array-like, optional

    

An array instance to use for determining arrays to create and return to users.
Use numpy.empty(()) by default.

**attributes** dict

    

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

**use_consolidated** bool or str, default None

    

Whether to use consolidated metadata.

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

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

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

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

Returns:

    

**g** Group

    

The new group.

zarr.open_like(

    _a : zarr.api.asynchronous.ArrayLike_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)")_,
    _** 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.

zarr.print_debug_info() ->
[None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

Print version info for use in bug reports.

zarr.save(

    _store : zarr.storage.StoreLike_,
    _* args: zarr.core.buffer.NDArrayLike_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _** kwargs: Any_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

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.

zarr.save_array(

    _store : zarr.storage.StoreLike_,
    _arr : zarr.core.buffer.NDArrayLike_,
    _*_ ,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _** kwargs: Any_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

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 `create()`, e.g., compressor.

zarr.save_group(

    _store : zarr.storage.StoreLike_,
    _* args: zarr.core.buffer.NDArrayLike_,
    _zarr_version : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _zarr_format : zarr.core.common.ZarrFormat | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _path : [str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _storage_options : [dict](https://docs.python.org/3/library/stdtypes.html#dict "\(in Python v3.13\)")[[str](https://docs.python.org/3/library/stdtypes.html#str "\(in Python v3.13\)"), Any] | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _** kwargs: zarr.core.buffer.NDArrayLike_,
) -> [None](https://docs.python.org/3/library/constants.html#None "\(in Python
v3.13\)")#

    

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.

zarr.tree(

    _grp : zarr.core.group.Group_,
    _expand : [bool](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
    _level : [int](https://docs.python.org/3/library/functions.html#int "\(in Python v3.13\)") | [None](https://docs.python.org/3/library/constants.html#None "\(in Python v3.13\)") = None_,
) -> Any#

    

Provide a rich display of the hierarchy.

Deprecated since version 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.

zarr.zeros(

    _shape : zarr.core.common.ChunkCoords_,
    _** 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 `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

zarr.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 `zarr.api.asynchronous.create()`.

Returns:

    

Array

    

The new array.

zarr.config#

    

## Release notes#

### 3.1.1 (2025-07-28)#

#### Features#

  * Add lightweight implementations of .getsize() and .getsize_prefix() for ObjectStore. ([#3227](https://github.com/zarr-developers/zarr-python/issues/3227))

#### Bugfixes#

  * Creating a Zarr format 2 array with the `order` keyword argument no longer raises a warning. ([#3112](https://github.com/zarr-developers/zarr-python/issues/3112))

  * Fixed the error message when passing both `config` and `write_empty_chunks` arguments to reflect the current behaviour (`write_empty_chunks` takes precedence). ([#3112](https://github.com/zarr-developers/zarr-python/issues/3112))

  * Creating a Zarr format 3 array with the `order` argument now conistently ignores this argument and raises a warning. ([#3112](https://github.com/zarr-developers/zarr-python/issues/3112))

  * When using `from_array` to copy a Zarr format 2 array to a Zarr format 3 array, if the memory order of the input array is `"F"` a warning is raised and the order ignored. This is because Zarr format 3 arrays are always stored in “C” order. ([#3112](https://github.com/zarr-developers/zarr-python/issues/3112))

  * The `config` argument to zarr.create (and functions that create arrays) is now used - previously it had no effect. ([#3112](https://github.com/zarr-developers/zarr-python/issues/3112))

  * Ensure that all abstract methods of `ZDType` raise a `NotImplementedError` when invoked. ([#3251](https://github.com/zarr-developers/zarr-python/issues/3251))

  * Register ‘gpu’ marker with pytest for downstream StoreTests. ([#3258](https://github.com/zarr-developers/zarr-python/issues/3258))

  * Expand the range of types accepted by `parse_data_type` to include strings and Sequences.

  * Move the functionality of `parse_data_type` to a new function called `parse_dtype`. This change ensures that nomenclature is consistent across the codebase. `parse_data_type` remains, so this change is not breaking. ([#3264](https://github.com/zarr-developers/zarr-python/issues/3264))

  * Fix a regression introduced in 3.1.0 that prevented `inf`, `-inf`, and `nan` values from being stored in `attributes`. ([#3280](https://github.com/zarr-developers/zarr-python/issues/3280))

  * Fixes Group.nmembers() ignoring depth when using consolidated metadata. ([#3287](https://github.com/zarr-developers/zarr-python/issues/3287))

#### Improved Documentation#

  * Expand the data type docs to include a demonstration of the `parse_data_type` function. Expand the docstring for the `parse_data_type` function. ([#3249](https://github.com/zarr-developers/zarr-python/issues/3249))

  * Add a section on codecs to the migration guide. ([#3273](https://github.com/zarr-developers/zarr-python/issues/3273))

#### Misc#

  * [#3268](https://github.com/zarr-developers/zarr-python/issues/3268)

### 3.1.0 (2025-07-14)#

#### Features#

  * Ensure that invocations of `create_array` use consistent keyword arguments, with consistent defaults.

`zarr.api.synchronous.create_array` now takes a `write_data` keyword argument
The `Group.create_array` method takes `data` and `write_data` keyword
arguments. The functions `api.asynchronous.create`,
`api.asynchronous.create_array` and the methods `Group.create_array`,
`Group.array`, had the default `fill_value` changed from `0` to the
`DEFAULT_FILL_VALUE` value, which instructs Zarr to use the default scalar
value associated with the array’s data type as the fill value. These are all
functions or methods for array creation that mirror, wrap or are wrapped by,
another function that already has a default `fill_value` set to
`DEFAULT_FILL_VALUE`. This change is necessary to make these functions
consistent across the entire codebase, but as this changes default values, new
data might have a different fill value than expected after this change.

For data types where 0 is meaningful, like integers or floats, the default
scalar is 0, so this change should not be noticeable. For data types where 0
is ambiguous, like fixed-length unicode strings, the default fill value might
be different after this change. Users who were relying on how Zarr interpreted
`0` as a non-numeric scalar value should set their desired fill value
explicitly after this change.

  * Added public API for Buffer ABCs and implementations.

Use `zarr.buffer` to access buffer implementations, and `zarr.abc.buffer` for
the interface to implement new buffer types.

Users previously importing buffer from `zarr.core.buffer` should update their
imports to use `zarr.buffer`. As a reminder, all of `zarr.core` is considered
a private API that’s not covered by zarr-python’s versioning policy.
([#2871](https://github.com/zarr-developers/zarr-python/issues/2871))

  * Adds zarr-specific data type classes.

This change adds a `ZDType` base class for Zarr V2 and Zarr V3 data types.
Child classes are defined for each NumPy data type. Each child class defines
routines for `JSON` serialization. New data types can be created and
registered dynamically.

Prior to this change, Zarr Python had two streams for handling data types. For
Zarr V2 arrays, we used NumPy data type identifiers. For Zarr V3 arrays, we
used a fixed set of string enums. Both of these systems proved hard to extend.

This change is largely internal, but it does change the type of the `dtype`
and `data_type` fields on the `ArrayV2Metadata` and `ArrayV3Metadata` classes.
Previously, `ArrayV2Metadata.dtype` was a NumPy `dtype` object, and
`ArrayV3Metadata.data_type` was an internally-defined `enum`. After this
change, both `ArrayV2Metadata.dtype` and `ArrayV3Metadata.data_type` are
instances of `ZDType`. A NumPy data type can be generated from a `ZDType` via
the `ZDType.to_native_dtype()` method. The internally-defined Zarr V3 `enum`
class is gone entirely, but the `ZDType.to_json(zarr_format=3)` method can be
used to generate either a string, or dictionary that has a string `name`
field, that represents the string value previously associated with that
`enum`.

For more on this new feature, see the [documentation](/user-
guide/data_types.html) ([#2874](https://github.com/zarr-developers/zarr-
python/issues/2874))

  * Added NDBuffer.empty method for faster ndbuffer initialization. ([#3191](https://github.com/zarr-developers/zarr-python/issues/3191))

  * The minimum version of NumPy has increased to 1.26. ([#3226](https://github.com/zarr-developers/zarr-python/issues/3226))

  * Add an alternate from_array_metadata_and_store constructor to CodecPipeline. ([#3233](https://github.com/zarr-developers/zarr-python/issues/3233))

#### Bugfixes#

  * Fixes a variety of issues related to string data types.

    * Brings the `VariableLengthUTF8` data type Zarr V3 identifier in alignment with Zarr Python 3.0.8

    * Disallows creation of 0-length fixed-length data types

    * Adds a regression test for the `VariableLengthUTF8` data type that checks against version 3.0.8

    * Allows users to request the `VariableLengthUTF8` data type with `str`, `"str"`, or `"string"`. ([#3170](https://github.com/zarr-developers/zarr-python/issues/3170))

  * Add human readable size for No. bytes stored to info_complete ([#3190](https://github.com/zarr-developers/zarr-python/issues/3190))

  * Restores the ability to create a Zarr V2 array with a `null` fill value by introducing a new class `DefaultFillValue`, and setting the default value of the `fill_value` parameter in array creation routines to an instance of `DefaultFillValue`. For Zarr V3 arrays, `None` will act as an alias for a `DefaultFillValue` instance, thus preserving compatibility with existing code. ([#3198](https://github.com/zarr-developers/zarr-python/issues/3198))

  * Fix the type of `ArrayV2Metadata.codec` to constrain it to `numcodecs.abc.Codec | None`. Previously the type was more permissive, allowing objects that can be parsed into Codecs (e.g., the codec name). The constructor of `ArrayV2Metadata` still allows the permissive input when creating new objects. ([#3232](https://github.com/zarr-developers/zarr-python/issues/3232))

#### Improved Documentation#

  * Add a self-contained example of data type extension to the `examples` directory, and expanded the documentation for data types. ([#3157](https://github.com/zarr-developers/zarr-python/issues/3157))

  *     * Add a description on how to create a RemoteStore of a specific filesystem to the Remote Store section in docsuser-guidestorage.rst.

    * State in the docstring of FsspecStore.from_url that the filesystem type is inferred from the URL scheme.

It should help a user handling the case when the type of FsspecStore doesn’t
match the URL scheme. ([#3212](https://github.com/zarr-developers/zarr-
python/issues/3212))

#### Deprecations and Removals#

  * Removes default chunk encoding settings (filters, serializer, compressors) from the global configuration object.

This removal is justified on the basis that storing chunk encoding settings in
the config required a brittle, confusing, and inaccurate categorization of
array data types, which was particularly unsuitable after the recent addition
of new data types that didn’t fit naturally into the pre-existing categories.

The default chunk encoding is the same (Zstandard compression, and the
required object codecs for variable length data types), but the chunk encoding
is now generated by functions that cannot be reconfigured at runtime. Users
who relied on setting the default chunk encoding via the global configuration
object should instead specify the desired chunk encoding explicitly when
creating an array.

This change also adds an extra validation step to the creation of Zarr V2
arrays, which ensures that arrays with a `VariableLengthUTF8` or
`VariableLengthBytes` data type cannot be created without the correct “object
codec”. ([#3228](https://github.com/zarr-developers/zarr-python/issues/3228))

  * Removes support for passing keyword-only arguments positionally to the following functions and methods: `save_array`, `open`, `group`, `open_group`, `create`, `get_basic_selection`, `set_basic_selection`, `get_orthogonal_selection`, `set_orthogonal_selection`, `get_mask_selection`, `set_mask_selection`, `get_coordinate_selection`, `set_coordinate_selection`, `get_block_selection`, `set_block_selection`, `Group.create_array`, `Group.empty`, `Group.zeroes`, `Group.ones`, `Group.empty_like`, `Group.full`, `Group.zeros_like`, `Group.ones_like`, `Group.full_like`, `Group.array`. Prior to this change, passing a keyword-only argument positionally to one of these functions or methods would raise a deprecation warning. That warning is now gone. Passing keyword-only arguments to these functions and methods positionally is now an error.

### 3.0.10 (2025-07-03)#

#### Bugfixes#

  * Removed an unnecessary check from `_fsspec._make_async` that would raise an exception when creating a read-only store backed by a local file system with `auto_mkdir` set to `False`. ([#3193](https://github.com/zarr-developers/zarr-python/issues/3193))

  * Add missing import for AsyncFileSystemWrapper for _make_async in _fsspec.py ([#3195](https://github.com/zarr-developers/zarr-python/issues/3195))

### 3.0.9 (2025-06-30)#

#### Features#

  * Add zarr.storage.FsspecStore.from_mapper() so that zarr.open() supports stores of type fsspec.mapping.FSMap. ([#2774](https://github.com/zarr-developers/zarr-python/issues/2774))

  * Implemented `move` for `LocalStore` and `ZipStore`. This allows users to move the store to a different root path. ([#3021](https://github.com/zarr-developers/zarr-python/issues/3021))

  * Added ~zarr.errors.GroupNotFoundError, which is raised when attempting to open a group that does not exist. ([#3066](https://github.com/zarr-developers/zarr-python/issues/3066))

  * Adds `fill_value` to the list of attributes displayed in the output of the `AsyncArray.info()` method. ([#3081](https://github.com/zarr-developers/zarr-python/issues/3081))

  * Use [`numpy.zeros()`](https://numpy.org/doc/stable/reference/generated/numpy.zeros.html#numpy.zeros "\(in NumPy v2.3\)") instead of `np.full()` for a performance speedup when creating a zarr.core.buffer.NDBuffer with fill_value=0. ([#3082](https://github.com/zarr-developers/zarr-python/issues/3082))

  * Port more stateful testing actions from [Icechunk](https://icechunk.io). ([#3130](https://github.com/zarr-developers/zarr-python/issues/3130))

  * Adds a with_read_only convenience method to the Store abstract base class (raises NotImplementedError) and implementations to the MemoryStore, ObjectStore, LocalStore, and FsspecStore classes. ([#3138](https://github.com/zarr-developers/zarr-python/issues/3138))

#### Bugfixes#

  * Ignore stale child metadata when reconsolidating metadata. ([#2921](https://github.com/zarr-developers/zarr-python/issues/2921))

  * For Zarr format 2, allow fixed-length string arrays to be created without automatically inserting a `Vlen-UT8` codec in the array of filters. Fixed-length string arrays do not need this codec. This change fixes a regression where fixed-length string arrays created with Zarr Python 3 could not be read with Zarr Python 2.18. ([#3100](https://github.com/zarr-developers/zarr-python/issues/3100))

  * When creating arrays without explicitly specifying a chunk size using zarr.create and other array creation routines, the chunk size will now set automatically instead of defaulting to the data shape. For large arrays this will result in smaller default chunk sizes. To retain previous behaviour, explicitly set the chunk shape to the data shape.

This fix matches the existing chunking behaviour of zarr.save_array and
zarr.api.asynchronous.AsyncArray.create. ([#3103](https://github.com/zarr-
developers/zarr-python/issues/3103))

  * When zarr.save has an argument path=some/path/ and multiple arrays in args, the path resulted in some/path/some/path due to using the path argument twice while building the array path. This is now fixed. ([#3127](https://github.com/zarr-developers/zarr-python/issues/3127))

  * Fix zarr.open default for argument mode when store is read_only ([#3128](https://github.com/zarr-developers/zarr-python/issues/3128))

  * Suppress FileNotFoundError when deleting non-existent keys in the obstore adapter.

When writing empty chunks (i.e. chunks where all values are equal to the
array’s fill value) to a zarr array, zarr will delete those chunks from the
underlying store. For zarr arrays backed by the obstore adapter, this will
potentially raise a FileNotFoundError if the chunk doesn’t already exist.
Since whether or not a delete of a non-existing object raises an error depends
on the behavior of the underlying store, suppressing the error in all cases
results in consistent behavior across stores, and is also what zarr seems to
expect from the store. ([#3140](https://github.com/zarr-developers/zarr-
python/issues/3140))

  * Trying to open a StorePath/Array with `mode='r'` when the store is not read-only creates a read-only copy of the store. ([#3156](https://github.com/zarr-developers/zarr-python/issues/3156))

### 3.0.8 (2025-05-19)#

Warning

In versions 3.0.0 to 3.0.7 opening arrays or groups with `mode='a'` (the
default for many builtin functions) would cause any existing paths in the
store to be deleted. This is fixed in 3.0.8, and we recommend all users
upgrade to avoid this bug that could cause unintentional data loss.

#### Features#

  * Added a print_debug_info function for bug reports. ([#2913](https://github.com/zarr-developers/zarr-python/issues/2913))

#### Bugfixes#

  * Fix a bug that prevented the number of initialized chunks being counted properly. ([#2862](https://github.com/zarr-developers/zarr-python/issues/2862))

  * Fixed sharding with GPU buffers. ([#2978](https://github.com/zarr-developers/zarr-python/issues/2978))

  * Fix structured dtype fill value serialization for consolidated metadata ([#2998](https://github.com/zarr-developers/zarr-python/issues/2998))

  * It is now possible to specify no compressor when creating a zarr format 2 array. This can be done by passing `compressor=None` to the various array creation routines.

The default behaviour of automatically choosing a suitable default compressor
remains if the compressor argument is not given. To reproduce the behaviour in
previous zarr-python versions when `compressor=None` was passed, pass
`compressor='auto'` instead. ([#3039](https://github.com/zarr-developers/zarr-
python/issues/3039))

  * Fixed the typing of `dimension_names` arguments throughout so that it now accepts iterables that contain None alongside str. ([#3045](https://github.com/zarr-developers/zarr-python/issues/3045))

  * Using various functions to open data with `mode='a'` no longer deletes existing data in the store. ([#3062](https://github.com/zarr-developers/zarr-python/issues/3062))

  * Internally use typesize constructor parameter for [`numcodecs.blosc.Blosc`](https://numcodecs.readthedocs.io/en/stable/compression/blosc.html#numcodecs.blosc.Blosc "\(in numcodecs v0.16.1\)") to improve compression ratios back to the v2-package levels. ([#2962](https://github.com/zarr-developers/zarr-python/issues/2962))

  * Specifying the memory order of Zarr format 2 arrays using the `order` keyword argument has been fixed. ([#2950](https://github.com/zarr-developers/zarr-python/issues/2950))

#### Misc#

  * [#2972](https://github.com/zarr-developers/zarr-python/issues/2972), [#3027](https://github.com/zarr-developers/zarr-python/issues/3027), [#3049](https://github.com/zarr-developers/zarr-python/issues/3049)

### 3.0.7 (2025-04-22)#

#### Features#

  * Add experimental ObjectStore storage class based on obstore. ([#1661](https://github.com/zarr-developers/zarr-python/issues/1661))

  * Add `zarr.from_array` using concurrent streaming of source data ([#2622](https://github.com/zarr-developers/zarr-python/issues/2622))

#### Bugfixes#

  * 0-dimensional arrays are now returning a scalar. Therefore, the return type of `__getitem__` changed to NDArrayLikeOrScalar. This change is to make the behavior of 0-dimensional arrays consistent with `numpy` scalars. ([#2718](https://github.com/zarr-developers/zarr-python/issues/2718))

  * Fix fill_value serialization for NaN in ArrayV2Metadata and add property-based testing of round-trip serialization ([#2802](https://github.com/zarr-developers/zarr-python/issues/2802))

  * Fixes ConsolidatedMetadata serialization of nan, inf, and -inf to be consistent with the behavior of ArrayMetadata. ([#2996](https://github.com/zarr-developers/zarr-python/issues/2996))

#### Improved Documentation#

  * Updated the 3.0 migration guide to include the removal of “.” syntax for getting group members. ([#2991](https://github.com/zarr-developers/zarr-python/issues/2991), [#2997](https://github.com/zarr-developers/zarr-python/issues/2997))

#### Misc#

  * Define a new versioning policy based on Effective Effort Versioning. This replaces the old Semantic Versioning-based policy. ([#2924](https://github.com/zarr-developers/zarr-python/issues/2924), [#2910](https://github.com/zarr-developers/zarr-python/issues/2910))

  * Make warning filters in the tests more specific, so warnings emitted by tests added in the future are more likely to be caught instead of ignored. ([#2714](https://github.com/zarr-developers/zarr-python/issues/2714))

  * Avoid an unnecessary memory copy when writing Zarr to a local file ([#2944](https://github.com/zarr-developers/zarr-python/issues/2944))

### 3.0.6 (2025-03-20)#

#### Bugfixes#

  * Restore functionality of del z.attrs[‘key’] to actually delete the key. ([#2908](https://github.com/zarr-developers/zarr-python/issues/2908))

### 3.0.5 (2025-03-07)#

#### Bugfixes#

  * Fixed a bug where `StorePath` creation would not apply standard path normalization to the `path` parameter, which led to the creation of arrays and groups with invalid keys. ([#2850](https://github.com/zarr-developers/zarr-python/issues/2850))

  * Prevent update_attributes calls from deleting old attributes ([#2870](https://github.com/zarr-developers/zarr-python/issues/2870))

#### Misc#

  * [#2796](https://github.com/zarr-developers/zarr-python/issues/2796)

### 3.0.4 (2025-02-23)#

#### Features#

  * Adds functions for concurrently creating multiple arrays and groups. ([#2665](https://github.com/zarr-developers/zarr-python/issues/2665))

#### Bugfixes#

  * Fixed a bug where `ArrayV2Metadata` could save `filters` as an empty array. ([#2847](https://github.com/zarr-developers/zarr-python/issues/2847))

  * Fix a bug when setting values of a smaller last chunk. ([#2851](https://github.com/zarr-developers/zarr-python/issues/2851))

#### Misc#

  * [#2828](https://github.com/zarr-developers/zarr-python/issues/2828)

### 3.0.3 (2025-02-14)#

#### Features#

  * Improves performance of FsspecStore.delete_dir for remote filesystems supporting concurrent/batched deletes, e.g., s3fs. ([#2661](https://github.com/zarr-developers/zarr-python/issues/2661))

  * Added `zarr.config.enable_gpu()` to update Zarr’s configuration to use GPUs. ([#2751](https://github.com/zarr-developers/zarr-python/issues/2751))

  * Avoid reading chunks during writes where possible. [#757](https://github.com/zarr-developers/zarr-python/issues/757) ([#2784](https://github.com/zarr-developers/zarr-python/issues/2784))

  * `LocalStore` learned to `delete_dir`. This makes array and group deletes more efficient. ([#2804](https://github.com/zarr-developers/zarr-python/issues/2804))

  * Add zarr.testing.strategies.array_metadata to generate ArrayV2Metadata and ArrayV3Metadata instances. ([#2813](https://github.com/zarr-developers/zarr-python/issues/2813))

  * Add arbitrary shards to Hypothesis strategy for generating arrays. ([#2822](https://github.com/zarr-developers/zarr-python/issues/2822))

#### Bugfixes#

  * Fixed bug with Zarr using device memory, instead of host memory, for storing metadata when using GPUs. ([#2751](https://github.com/zarr-developers/zarr-python/issues/2751))

  * The array returned by `zarr.empty` and an empty `zarr.core.buffer.cpu.NDBuffer` will now be filled with the specified fill value, or with zeros if no fill value is provided. This fixes a bug where Zarr format 2 data with no fill value was written with un-predictable chunk sizes. ([#2755](https://github.com/zarr-developers/zarr-python/issues/2755))

  * Fix zip-store path checking for stores with directories listed as files. ([#2758](https://github.com/zarr-developers/zarr-python/issues/2758))

  * Use removeprefix rather than replace when removing filename prefixes in FsspecStore.list ([#2778](https://github.com/zarr-developers/zarr-python/issues/2778))

  * Enable automatic removal of needs release notes with labeler action ([#2781](https://github.com/zarr-developers/zarr-python/issues/2781))

  * Use the proper label config ([#2785](https://github.com/zarr-developers/zarr-python/issues/2785))

  * Alters the behavior of `create_array` to ensure that any groups implied by the array’s name are created if they do not already exist. Also simplifies the type signature for any function that takes an ArrayConfig-like object. ([#2795](https://github.com/zarr-developers/zarr-python/issues/2795))

  * Enitialise empty chunks to the default fill value during writing and add default fill values for datetime, timedelta, structured, and other (void* fixed size) data types ([#2799](https://github.com/zarr-developers/zarr-python/issues/2799))

  * Ensure utf8 compliant strings are used to construct numpy arrays in property-based tests ([#2801](https://github.com/zarr-developers/zarr-python/issues/2801))

  * Fix pickling for ZipStore ([#2807](https://github.com/zarr-developers/zarr-python/issues/2807))

  * Update numcodecs to not overwrite codec configuration ever. Closes [#2800](https://github.com/zarr-developers/zarr-python/issues/2800). ([#2811](https://github.com/zarr-developers/zarr-python/issues/2811))

  * Fix fancy indexing (e.g. arr[5, [0, 1]]) with the sharding codec ([#2817](https://github.com/zarr-developers/zarr-python/issues/2817))

#### Improved Documentation#

  * Added new user guide on Using GPUs with Zarr. ([#2751](https://github.com/zarr-developers/zarr-python/issues/2751))

### 3.0.2 (2025-01-31)#

#### Features#

  * Test `getsize()` and `getsize_prefix()` in `StoreTests`. ([#2693](https://github.com/zarr-developers/zarr-python/issues/2693))

  * Test that a `ValueError` is raised for invalid byte range syntax in `StoreTests`. ([#2693](https://github.com/zarr-developers/zarr-python/issues/2693))

  * Separate instantiating and opening a store in `StoreTests`. ([#2693](https://github.com/zarr-developers/zarr-python/issues/2693))

  * Add a test for using Stores as a context managers in `StoreTests`. ([#2693](https://github.com/zarr-developers/zarr-python/issues/2693))

  * Implemented `LogingStore.open()`. ([#2693](https://github.com/zarr-developers/zarr-python/issues/2693))

  * `LoggingStore` is now a generic class. ([#2693](https://github.com/zarr-developers/zarr-python/issues/2693))

  * Change StoreTest’s `test_store_repr`, `test_store_supports_writes`, `test_store_supports_partial_writes`, and `test_store_supports_listing` to to be implemented using `@abstractmethod`, rather raising `NotImplementedError`. ([#2693](https://github.com/zarr-developers/zarr-python/issues/2693))

  * Test the error raised for invalid buffer arguments in `StoreTests`. ([#2693](https://github.com/zarr-developers/zarr-python/issues/2693))

  * Test that data can be written to a store that’s not yet open using the store.set method in `StoreTests`. ([#2693](https://github.com/zarr-developers/zarr-python/issues/2693))

  * Adds a new function `init_array` for initializing an array in storage, and refactors `create_array` to use `init_array`. `create_array` takes two new parameters: `data`, an optional array-like object, and `write_data`, a bool which defaults to `True`. If `data` is given to `create_array`, then the `dtype` and `shape` attributes of `data` are used to define the corresponding attributes of the resulting Zarr array. Additionally, if `data` given and `write_data` is `True`, then the values in `data` will be written to the newly created array. ([#2761](https://github.com/zarr-developers/zarr-python/issues/2761))

#### Bugfixes#

  * Wrap sync fsspec filesystems with `AsyncFileSystemWrapper`. ([#2533](https://github.com/zarr-developers/zarr-python/issues/2533))

  * Added backwards compatibility for Zarr format 2 structured arrays. ([#2681](https://github.com/zarr-developers/zarr-python/issues/2681))

  * Update equality for `LoggingStore` and `WrapperStore` such that ‘other’ must also be a `LoggingStore` or `WrapperStore` respectively, rather than only checking the types of the stores they wrap. ([#2693](https://github.com/zarr-developers/zarr-python/issues/2693))

  * Ensure that `ZipStore` is open before getting or setting any values. ([#2693](https://github.com/zarr-developers/zarr-python/issues/2693))

  * Use stdout rather than stderr as the default stream for `LoggingStore`. ([#2693](https://github.com/zarr-developers/zarr-python/issues/2693))

  * Match the errors raised by read only stores in `StoreTests`. ([#2693](https://github.com/zarr-developers/zarr-python/issues/2693))

  * Fixed `ZipStore` to make sure the correct attributes are saved when instances are pickled. This fixes a previous bug that prevent using `ZipStore` with a `ProcessPoolExecutor`. ([#2762](https://github.com/zarr-developers/zarr-python/issues/2762))

  * Updated the optional test dependencies to include `botocore` and `fsspec`. ([#2768](https://github.com/zarr-developers/zarr-python/issues/2768))

  * Fixed the fsspec tests to skip if `botocore` is not installed. Previously they would have failed with an import error. ([#2768](https://github.com/zarr-developers/zarr-python/issues/2768))

  * Optimize full chunk writes. ([#2782](https://github.com/zarr-developers/zarr-python/issues/2782))

#### Improved Documentation#

  * Changed the machinery for creating changelog entries. Now individual entries should be added as files to the changes directory in the zarr-python repository, instead of directly to the changelog file. ([#2736](https://github.com/zarr-developers/zarr-python/issues/2736))

#### Other#

  * Created a type alias `ChunkKeyEncodingLike` to model the union of `ChunkKeyEncoding` instances and the dict form of the parameters of those instances. `ChunkKeyEncodingLike` should be used by high-level functions to provide a convenient way for creating `ChunkKeyEncoding` objects. ([#2763](https://github.com/zarr-developers/zarr-python/issues/2763))

### 3.0.1 (Jan. 17, 2025)#

  * Implement `zarr.from_array` using concurrent streaming ([#2622](https://github.com/zarr-developers/zarr-python/issues/2622)).

#### Bug fixes#

  * Fixes `order` argument for Zarr format 2 arrays ([#2679](https://github.com/zarr-developers/zarr-python/issues/2679)).

  * Fixes a bug that prevented reading Zarr format 2 data with consolidated metadata written using `zarr-python` version 2 ([#2694](https://github.com/zarr-developers/zarr-python/issues/2694)).

  * Ensure that compressor=None results in no compression when writing Zarr format 2 data ([#2708](https://github.com/zarr-developers/zarr-python/issues/2708)).

  * Fix for empty consolidated metadata dataset: backwards compatibility with Zarr-Python 2 ([#2695](https://github.com/zarr-developers/zarr-python/issues/2695)).

#### Documentation#

  * Add v3.0.0 release announcement banner ([#2677](https://github.com/zarr-developers/zarr-python/issues/2677)).

  * Quickstart guide alignment with V3 API ([#2697](https://github.com/zarr-developers/zarr-python/issues/2697)).

  * Fix doctest failures related to numcodecs 0.15 ([#2727](https://github.com/zarr-developers/zarr-python/issues/2727)).

#### Other#

  * Removed some unnecessary files from the source distribution to reduce its size. ([#2686](https://github.com/zarr-developers/zarr-python/issues/2686)).

  * Enable codecov in GitHub actions ([#2682](https://github.com/zarr-developers/zarr-python/issues/2682)).

  * Speed up hypothesis tests ([#2650](https://github.com/zarr-developers/zarr-python/issues/2650)).

  * Remove multiple imports for an import name ([#2723](https://github.com/zarr-developers/zarr-python/issues/2723)).

### 3.0.0 (Jan. 9, 2025)#

3.0.0 is a new major release of Zarr-Python, with many breaking changes. See
the 3.0 Migration Guide for a listing of what’s changed.

Normal release note service will resume with further releases in the 3.0.0
series.

Release notes for the zarr-python 2.x and 1.x releases can be found here:
<https://zarr.readthedocs.io/en/support-v2/release.html>

## Developer’s Guide#

### Contributing to Zarr#

Zarr is a community maintained project. We welcome contributions in the form
of bug reports, bug fixes, documentation, enhancement proposals and more. This
page provides information on how best to contribute.

#### Asking for help#

If you have a question about how to use Zarr, please post your question on
StackOverflow using the [“zarr”
tag](https://stackoverflow.com/questions/tagged/zarr). If you don’t get a
response within a day or two, feel free to raise a [GitHub
issue](https://github.com/zarr-developers/zarr-python/issues/new) including a
link to your StackOverflow question. We will try to respond to questions as
quickly as possible, but please bear in mind that there may be periods where
we have limited time to answer questions due to other commitments.

#### Bug reports#

If you find a bug, please raise a [GitHub issue](https://github.com/zarr-
developers/zarr-python/issues/new). Please include the following items in a
bug report:

  1. A minimal, self-contained snippet of Python code reproducing the problem. You can format the code nicely using markdown, e.g.:
         
         ```python
         import zarr
         g = zarr.group()
         # etc.
         ```
         

  2. An explanation of why the current behaviour is wrong/not desired, and what you expect instead.

  3. Information about the version of Zarr, along with versions of dependencies and the Python interpreter, and installation information. The version of Zarr can be obtained from the `zarr.__version__` property. Please also state how Zarr was installed, e.g., “installed via pip into a virtual environment”, or “installed using conda”. Information about other packages installed can be obtained by executing `pip freeze` (if using pip to install packages) or `conda env export` (if using conda to install packages) from the operating system command prompt. The version of the Python interpreter can be obtained by running a Python interactive session, e.g.:
         
         $ python
           Python 3.12.7 | packaged by conda-forge | (main, Oct  4 2024, 15:57:01) [Clang 17.0.6 ] on darwin
         

#### Enhancement proposals#

If you have an idea about a new feature or some other improvement to Zarr,
please raise a [GitHub issue](https://github.com/zarr-developers/zarr-
python/issues/new) first to discuss.

We very much welcome ideas and suggestions for how to improve Zarr, but please
bear in mind that we are likely to be conservative in accepting proposals for
new features. The reasons for this are that we would like to keep the Zarr
code base lean and focused on a core set of functionalities, and available
time for development, review and maintenance of new features is limited. But
if you have a great idea, please don’t let that stop you from posting it on
GitHub, just please don’t be offended if we respond cautiously.

#### Contributing code and/or documentation#

##### Forking the repository#

The Zarr source code is hosted on GitHub at the following location:

  * [zarr-developers/zarr-python](https://github.com/zarr-developers/zarr-python)

You will need your own fork to work on the code. Go to the link above and hit
the [“Fork”](https://github.com/zarr-developers/zarr-python/fork) button. Then
clone your fork to your local machine:

    
    
    $ git clone git@github.com:your-user-name/zarr-python.git
    $ cd zarr-python
    $ git remote add upstream git@github.com:zarr-developers/zarr-python.git
    

##### Creating a development environment#

To work with the Zarr source code, it is recommended to use
[hatch](https://hatch.pypa.io/latest/index.html) to create and manage
development environments. Hatch will automatically install all Zarr
dependencies using the same versions as are used by the core developers and
continuous integration services. Assuming you have a Python 3 interpreter
already installed, and you have cloned the Zarr source code and your current
working directory is the root of the repository, you can do something like the
following:

    
    
    $ pip install hatch
    $ hatch env show  # list all available environments
    

To verify that your development environment is working, you can run the unit
tests for one of the test environments, e.g.:

    
    
    $ hatch env run --env test.py3.12-2.1-optional run-pytest
    

##### Creating a branch#

Before you do any new work or submit a pull request, please open an issue on
GitHub to report the bug or propose the feature you’d like to add.

It’s best to synchronize your fork with the upstream repository, then create a
new, separate branch for each piece of work you want to do. E.g.:

    
    
    git checkout main
    git fetch upstream
    git checkout -b shiny-new-feature upstream/main
    git push -u origin shiny-new-feature
    

This changes your working directory to the ‘shiny-new-feature’ branch. Keep
any changes in this branch specific to one bug or feature so it is clear what
the branch brings to Zarr.

To update this branch with latest code from Zarr, you can retrieve the changes
from the main branch and perform a rebase:

    
    
    git fetch upstream
    git rebase upstream/main
    

This will replay your commits on top of the latest Zarr git main. If this
leads to merge conflicts, these need to be resolved before submitting a pull
request. Alternatively, you can merge the changes in from upstream/main
instead of rebasing, which can be simpler:

    
    
    git pull upstream main
    

Again, any conflicts need to be resolved before submitting a pull request.

##### Running the test suite#

Zarr includes a suite of unit tests. The simplest way to run the unit tests is
to activate your development environment (see creating a development
environment above) and invoke:

    
    
    $ hatch env run --env test.py3.12-2.1-optional run-pytest
    

All tests are automatically run via GitHub Actions for every pull request and
must pass before code can be accepted. Test coverage is also collected
automatically via the Codecov service.

Note

Previous versions of Zarr-Python made extensive use of doctests. These tests
were not maintained during the 3.0 refactor but may be brought back in the
future. See [#2614](https://github.com/zarr-developers/zarr-
python/issues/2614) for more details.

##### Code standards - using pre-commit#

All code must conform to the PEP8 standard. Regarding line length, lines up to
100 characters are allowed, although please try to keep under 90 wherever
possible.

`Zarr` uses a set of `pre-commit` hooks and the `pre-commit` bot to format,
type-check, and prettify the codebase. `pre-commit` can be installed locally
by running:

    
    
    $ python -m pip install pre-commit
    

The hooks can be installed locally by running:

    
    
    $ pre-commit install
    

This would run the checks every time a commit is created locally. These checks
will also run on every commit pushed to an open PR, resulting in some
automatic styling fixes by the `pre-commit` bot. The checks will by default
only run on the files modified by a commit, but the checks can be triggered
for all the files by running:

    
    
    $ pre-commit run --all-files
    

If you would like to skip the failing checks and push the code for further
discussion, use the `--no-verify` option with `git commit`.

##### Test coverage#

Note

Test coverage for Zarr-Python 3 is currently not at 100%. This is a known
issue and help is welcome to bring test coverage back to 100%. See
[#2613](https://github.com/zarr-developers/zarr-python/issues/2613) for more
details.

Zarr strives to maintain 100% test coverage under the latest Python stable
release Both unit tests and docstring doctests are included when computing
coverage. Running:

    
    
    $ hatch env run --env test.py3.12-2.1-optional run-coverage
    

will automatically run the test suite with coverage and produce a XML coverage
report. This should be 100% before code can be accepted into the main code
base.

You can also generate an HTML coverage report by running:

    
    
    $ hatch env run --env test.py3.12-2.1-optional run-coverage-html
    

When submitting a pull request, coverage will also be collected across all
supported Python versions via the Codecov service, and will be reported back
within the pull request. Codecov coverage must also be 100% before code can be
accepted.

##### Documentation#

Docstrings for user-facing classes and functions should follow the
[numpydoc](https://numpydoc.readthedocs.io/en/stable/format.html#docstring-
standard) standard, including sections for Parameters and Examples. All
examples should run and pass as doctests under Python 3.11.

Zarr uses Sphinx for documentation, hosted on readthedocs.org. Documentation
is written in the RestructuredText markup language (.rst files) in the `docs`
folder. The documentation consists both of prose and API documentation. All
user-facing classes and functions are included in the API documentation, under
the `docs/api` folder using the [autodoc](https://www.sphinx-
doc.org/en/master/usage/extensions/autodoc.html) extension to sphinx. Any new
features or important usage information should be included in the user-guide
(`docs/user-guide`). Any changes should also be included as a new file in the
`changes` directory.

The documentation can be built locally by running:

    
    
    $ hatch --env docs run build
    

The resulting built documentation will be available in the `docs/_build/html`
folder.

Hatch can also be used to serve continuously updating version of the
documentation during development at <http://0.0.0.0:8000/>. This can be done
by running:

    
    
    $ hatch --env docs run serve
    

##### Changelog#

zarr-python uses
[towncrier](https://towncrier.readthedocs.io/en/stable/tutorial.html) to
manage release notes. Most pull requests should include at least one news
fragment describing the changes. To add a release note, you’ll need the GitHub
issue or pull request number and the type of your change (`feature`, `bugfix`,
`doc`, `removal`, `misc`). With that, run ``towncrier create`` with your
development environment, which will prompt you for the issue number, change
type, and the news text:

    
    
    towncrier create
    

Alternatively, you can manually create the files in the `changes` directory
using the naming convention `{issue-number}.{change-type}.rst`.

See the [towncrier](https://towncrier.readthedocs.io/en/stable/tutorial.html)
docs for more.

The following information is mainly for core developers, but may also be of
interest to contributors.

#### Merging pull requests#

Pull requests submitted by an external contributor should be reviewed and
approved by at least one core developer before being merged. Ideally, pull
requests submitted by a core developer should be reviewed and approved by at
least one other core developer before being merged.

Pull requests should not be merged until all CI checks have passed (GitHub
Actions Codecov) against code that has had the latest main merged in.

#### Compatibility and versioning policies#

##### Versioning#

Versions of this library are identified by a triplet of integers with the form
`<major>.<minor>.<patch>`, for example `3.0.4`. A release of `zarr-python` is
associated with a new version identifier. That new identifier is generated by
incrementing exactly one of the components of the previous version identifier
by 1. When incrementing the `major` component of the version identifier, the
`minor` and `patch` components is reset to 0. When incrementing the minor
component, the patch component is reset to 0.

Releases are classified by the library changes contained in that release. This
classification determines which component of the version identifier is
incremented on release.

  * `major` releases (for example, `2.18.0` -> `3.0.0`) are for changes that will require extensive adaptation efforts from many users and downstream projects. For example, breaking changes to widely-used user-facing APIs should only be applied in a major release.

Users and downstream projects should carefully consider the impact of a major
release before adopting it. In advance of a major release, developers should
communicate the scope of the upcoming changes, and help users prepare for
them.

  * `minor` releases (or example, `3.0.0` -> `3.1.0`) are for changes that do not require significant effort from most users or downstream downstream projects to respond to. API changes are possible in minor releases if the burden on users imposed by those changes is sufficiently small.

For example, a recently released API may need fixes or refinements that are
breaking, but low impact due to the recency of the feature. Such API changes
are permitted in a minor release.

Minor releases are safe for most users and downstream projects to adopt.

  * `patch` releases (for example, `3.1.0` -> `3.1.1`) are for changes that contain no breaking or behaviour changes for downstream projects or users. Examples of changes suitable for a patch release are bugfixes and documentation improvements.

Users should always feel safe upgrading to a the latest patch release.

Note that this versioning scheme is not consistent with [Semantic
Versioning](https://semver.org/). Contrary to SemVer, the Zarr library may
release breaking changes in `minor` releases, or even `patch` releases under
exceptional circumstances. But we should strive to avoid doing so.

A better model for our versioning scheme is [Intended Effort
Versioning](https://jacobtomlinson.dev/effver/), or “EffVer”. The guiding
principle off EffVer is to categorize releases based on the _expected effort
required to upgrade to that release_.

Zarr developers should make changes as smooth as possible for users. This
means making backwards-compatible changes wherever possible. When a backwards-
incompatible change is necessary, users should be notified well in advance,
e.g. via informative deprecation warnings.

###### Data format compatibility#

The Zarr library is an implementation of a file format standard defined
externally – see the [Zarr specifications website](https://zarr-
specs.readthedocs.io) for the list of Zarr file format specifications.

If an existing Zarr format version changes, or a new version of the Zarr
format is released, then the Zarr library will generally require changes. It
is very likely that a new Zarr format will require extensive breaking changes
to the Zarr library, and so support for a new Zarr format in the Zarr library
will almost certainly come in new `major` release. When the Zarr library adds
support for a new Zarr format, there may be a period of accelerated changes as
developers refine newly added APIs and deprecate old APIs. In such a
transitional phase breaking changes may be more frequent than usual.

#### Release procedure#

Open an issue on GitHub announcing the release using the release checklist
template: [zarr-developers/zarr-python#new](https://github.com/zarr-
developers/zarr-python/issues/new?template=release-checklist.md). The release
checklist includes all steps necessary for the release.

### Roadmap#

  * Status: active

  * Author: Joe Hamman

  * Created On: October 31, 2023

  * Input from:

    * Davis Bennett / @d-v-b

    * Norman Rzepka / @normanrz

    * Deepak Cherian @dcherian

    * Brian Davis / @monodeldiablo

    * Oliver McCormack / @olimcc

    * Ryan Abernathey / @rabernat

    * Jack Kelly / @JackKelly

    * Martin Durrant / @martindurant

Note

This document was written in the early stages of the 3.0 refactor. Some
aspects of the design have changed since this was originally written.
Questions and discussion about the contents of this document should be
directed to [this GitHub Discussion](https://github.com/zarr-developers/zarr-
python/discussions/1569).

#### Introduction#

This document lays out a design proposal for version 3.0 of the [Zarr-
Python](https://zarr.readthedocs.io/en/stable/) package. A specific focus of
the design is to bring Zarr-Python’s API up to date with the [Zarr V3
specification](https://zarr-specs.readthedocs.io/en/latest/v3/core/v3.0.html),
with the hope of enabling the development of the many features and extensions
that motivated the V3 Spec. The ideas presented here are expected to result in
a major release of Zarr-Python (version 3.0) including significant a number of
breaking API changes. For clarity, “V3” will be used to describe the version
of the Zarr specification and “3.0” will be used to describe the release tag
of the Zarr-Python project.

##### Current status of V3 in Zarr-Python#

During the development of the V3 Specification, a [prototype
implementation](https://github.com/zarr-developers/zarr-python/pull/898) was
added to the Zarr-Python library. Since that implementation, the V3 spec
evolved in significant ways and as a result, the Zarr-Python library is now
out of sync with the approved spec. Downstream libraries (e.g.
[Xarray](https://github.com/pydata/xarray)) have added support for this
implementation and will need to migrate to the accepted spec when its
available in Zarr-Python.

#### Goals#

  * Provide a complete implementation of Zarr V3 through the Zarr-Python API

  * Clear the way for exciting extensions / ZEPs (i.e. [sharding](https://zarr-specs.readthedocs.io/en/latest/v3/codecs/sharding-indexed/v1.0.html), [variable chunking](https://zarr.dev/zeps/draft/ZEP0003.html), etc.)

  * Provide a developer API that can be used to implement and register V3 extensions

  * Improve the performance of Zarr-Python by streamlining the interface between the Store layer and higher level APIs (e.g. Groups and Arrays)

  * Clean up the internal and user facing APIs

  * Improve code quality and robustness (e.g. achieve 100% type hint coverage)

  * Align the Zarr-Python array API with the [array API Standard](https://data-apis.org/array-api/latest/)

#### Examples of what 3.0 will enable?#

  1. Reading and writing V3 spec-compliant groups and arrays

  2. V3 extensions including sharding and variable chunking.

  3. Improved performance by leveraging concurrency when creating/reading/writing to stores (imagine a `create_hierarchy(zarr_objects)` function).

  4. User-developed extensions (e.g. storage-transformers) can be registered with Zarr-Python at runtime

#### Non-goals (of this document)#

  * Implementation of any unaccepted Zarr V3 extensions

  * Major revisions to the Zarr V3 spec

#### Requirements#

  1. Read and write spec compliant V2 and V3 data

  2. Limit unnecessary traffic to/from the store

  3. Cleanly define the Array/Group/Store abstractions

  4. Cleanly define how V2 will be supported going forward

  5. Provide a clear roadmap to help users upgrade to 3.0

  6. Developer tools / hooks for registering extensions

#### Design#

##### Async API#

Zarr-Python is an IO library. As such, supporting concurrent action against
the storage layer is critical to achieving acceptable performance. The Zarr-
Python 2 was not designed with asynchronous computation in mind and as a
result has struggled to effectively leverage the benefits of concurrency. At
one point, `getitems` and `setitems` support was added to the Zarr store model
but that is only used for operating on a set of chunks in a single variable.

With Zarr-Python 3.0, we have the opportunity to revisit this design. The
proposal here is as follows:

  1. The `Store` interface will be entirely async.

  2. On top of the async `Store` interface, we will provide an `AsyncArray` and `AsyncGroup` interface.

  3. Finally, the primary user facing API will be synchronous `Array` and `Group` classes that wrap the async equivalents.

**Examples**

  * **Store**
        
        class Store:
            ...
            async def get(self, key: str) -> bytes:
                ...
            async def get_partial_values(self, key_ranges: List[Tuple[str, Tuple[int, Optional[int]]]]) -> bytes:
                ...
        # (no sync interface here)
        

  * **Array**
        
        class AsyncArray:
            ...
        
            async def getitem(self, selection: Selection) -> np.ndarray:
               # the core logic for getitem goes here
        
        class Array:
            _async_array: AsyncArray
        
            def __getitem__(self, selection: Selection) -> np.ndarray:
                return sync(self._async_array.getitem(selection))
        

  * **Group**
        
        class AsyncGroup:
            ...
        
            async def create_group(self, path: str, **kwargs) -> AsyncGroup:
               # the core logic for create_group goes here
        
        class Group:
            _async_group: AsyncGroup
        
            def create_group(self, path: str, **kwargs) -> Group:
                return sync(self._async_group.create_group(path, **kwargs))
        

**Internal Synchronization API**

With the `Store` and core `AsyncArray`/ `AsyncGroup` classes being
predominantly async, Zarr-Python will need an internal API to provide a
synchronous API. The proposal here is to use the approach in
[fsspec](https://github.com/fsspec/filesystem_spec/blob/master/fsspec/asyn.py)
to provide a high-level `sync` function that takes an `awaitable` and runs it
in its managed IO Loop / thread.

**FAQ** 1\. Why two levels of Arrays/groups? a. First, this is an intentional
decision and departure from the current Zarrita implementation b. The idea is
that users rarely want to mix interfaces. Either they are working within an
async context (currently quite rare) or they are in a typical synchronous
context. c. Splitting the two will allow us to clearly define behavior on the
`AsyncObj` and simply wrap it in the `SyncObj`. 2. What if a store is only has
a synchronous backend? a. First off, this is expected to be a fairly rare
occurrence. Most storage backends have async interfaces. b. But in the event a
storage backend doesn’t have a async interface, there is nothing wrong with
putting synchronous code in `async` methods. There are approaches to enabling
concurrent action through wrappers like AsyncIO’s `loop.run_in_executor` ([ref
1](https://stackoverflow.com/questions/38865050/is-await-in-
python3-cooperative-multitasking), [ref
2](https://stackoverflow.com/a/43263397/732596), [ref
3](https://bbc.github.io/cloudfit-public-docs/asyncio/asyncio-part-5.html),
[ref 4](https://docs.python.org/3/library/asyncio-
eventloop.html#asyncio.loop.run_in_executor).

3\. Will Zarr help manage the async contexts encouraged by some libraries
(e.g.
[AioBotoCore](https://aiobotocore.readthedocs.io/en/latest/tutorial.html#using-
botocore))? a. Many async IO libraries require entering an async context
before interacting with the API. We expect some experimentation to be needed
here but the initial design will follow something close to what fsspec does
([example in
s3fs](https://github.com/fsspec/s3fs/blob/949442693ec940b35cda3420c17a864fbe426567/s3fs/core.py#L527)).
4\. Why not provide a synchronous Store interface? a. We could but this design
is simpler. It would mean supporting it in the `AsyncGroup` and `AsyncArray`
classes which, may be more trouble than its worth. Storage backends that do
not have an async API will be encouraged to wrap blocking calls in an async
wrapper (e.g. `loop.run_in_executor`).

##### Store API#

The `Store` API is specified directly in the V3 specification. All V3 stores
should implement this abstract API, omitting Write and List support as needed.
As described above, all stores will be expected to expose the required methods
as async methods.

**Example**

    
    
    class ReadWriteStore:
            ...
        async def get(self, key: str) -> bytes:
            ...
    
        async def get_partial_values(self, key_ranges: List[Tuple[str, int, int]) -> bytes:
            ...
    
        async def set(self, key: str, value: Union[bytes, bytearray, memoryview]) -> None:
            ...  # required for writable stores
    
        async def set_partial_values(self, key_start_values: List[Tuple[str, int, Union[bytes, bytearray, memoryview]]]) -> None:
            ...  # required for writable stores
    
        async def list(self) -> List[str]:
            ...  # required for listable stores
    
        async def list_prefix(self, prefix: str) -> List[str]:
            ...  # required for listable stores
    
        async def list_dir(self, prefix: str) -> List[str]:
            ...  # required for listable stores
    
        # additional (optional methods)
        async def getsize(self, prefix: str) -> int:
            ...
    
        async def rename(self, src: str, dest: str) -> None
            ...
    

Recognizing that there are many Zarr applications today that rely on the
`MutableMapping` interface supported by Zarr-Python 2, a wrapper store will be
developed to allow existing stores to plug directly into this API.

##### Array API#

The user facing array interface will implement a subset of the [Array API
Standard](https://data-apis.org/array-api/latest/). Most of the computational
parts of the Array API Standard don’t fit into Zarr right now. That’s okay.
What matters most is that we ensure we can give downstream applications a
compliant API.

_Note, Zarr already does most of this so this is more about formalizing the
relationship than a substantial change in API._

| Included | Not Included | Unknown / Maybe Possible  
---|---|---|---  
**Attributes** | `dtype` | `mT` | `device`  
| `ndim` | `T` |   
| `shape` |  |   
| `size` |  |   
**Methods** | `__getitem__` | `__array_namespace__` | `to_device`  
| `__setitem__` | `__abs__` | `__bool__`  
| `__eq__` | `__add__` | `__complex__`  
| `__bool__` | `__and__` | `__dlpack__`  
|  | `__floordiv__` | `__dlpack_device__`  
|  | `__ge__` | `__float__`  
|  | `__gt__` | `__index__`  
|  | `__invert__` | `__int__`  
|  | `__le__` |   
|  | `__lshift__` |   
|  | `__lt__` |   
|  | `__matmul__` |   
|  | `__mod__` |   
|  | `__mul__` |   
|  | `__ne__` |   
|  | `__neg__` |   
|  | `__or__` |   
|  | `__pos__` |   
|  | `__pow__` |   
|  | `__rshift__` |   
|  | `__sub__` |   
|  | `__truediv__` |   
|  | `__xor__` |   
**Creation functions** (`zarr.creation`) | `zeros` |  | `arange`  
| `zeros_like` |  | `asarray`  
| `ones` |  | `eye`  
| `ones_like` |  | `from_dlpack`  
| `full` |  | `linspace`  
| `full_like` |  | `meshgrid`  
| `empty` |  | `tril`  
| `empty_like` |  | `triu`  
  
In addition to the core array API defined above, the Array class should have
the following Zarr specific properties:

  * `.metadata` (see Metadata Interface below)

  * `.attrs` \- (pulled from metadata object)

  * `.info` \- (repolicated from existing property †)

_† In Zarr-Python 2, the info property listed the store to identify
initialized chunks. By default this will be turned off in 3.0 but will be
configurable._

**Indexing**

Zarr-Python currently supports `__getitem__` style indexing and the special
`oindex` and `vindex` indexers. These are not part of the current Array API
standard (see [data-apis/array-api#669](https://github.com/data-apis/array-
api/issues/669)) but they have been [proposed as a
NEP](https://numpy.org/neps/nep-0021-advanced-indexing.html). Zarr-Python will
maintain these in 3.0.

We are also exploring a new high-level indexing API that will enabled
optimized batch/concurrent loading of many chunks. We expect this to be
important to enable performant loading of data in the context of sharding. See
[this discussion](https://github.com/zarr-developers/zarr-
python/discussions/1569) for more detail.

Concurrent indexing across multiple arrays will be possible using the
AsyncArray API.

**Async and Sync Array APIs**

Most the logic to support Zarr Arrays will live in the `AsyncArray` class.
There are a few notable differences that should be called out.

Sync Method | Async Method  
---|---  
`__getitem__` | `getitem`  
`__setitem__` | `setitem`  
`__eq__` | `equals`  
  
**Metadata interface**

Zarr-Python 2.* closely mirrors the V2 spec metadata schema in the Array and
Group classes. In 3.0, we plan to move the underlying metadata representation
to a separate interface (e.g. `Array.metadata`). This interface will return
either a `V2ArrayMetadata` or `V3ArrayMetadata` object (both will inherit from
a parent `ArrayMetadataABC` class. The `V2ArrayMetadata` and `V3ArrayMetadata`
classes will be responsible for producing valid JSON representations of their
metadata, and yielding a consistent view to the `Array` or `Group` class.

##### Group API#

The main question is how closely we should follow the existing Zarr-Python
implementation / `MutableMapping` interface. The table below shows the primary
`Group` methods in Zarr-Python 2 and attempts to identify if and how they
would be implemented in 3.0.

V2 Group Methods | `AsyncGroup` | `Group` | `h5py_compat.Group`  
---|---|---|---  
`__len__` | `length` | `__len__` | `__len__`  
`__iter__` | `__aiter__` | `__iter__` | `__iter__`  
`__contains__` | `contains` | `__contains__` | `__contains__`  
`__getitem__` | `getitem` | `__getitem__` | `__getitem__`  
`__enter__` | N/A | N/A | `__enter__`  
`__exit__` | N/A | N/A | `__exit__`  
`group_keys` | `group_keys` | `group_keys` | N/A  
`groups` | `groups` | `groups` | N/A  
`array_keys` | `array_key` | `array_keys` | N/A  
`arrays` | `arrays` | `arrays` | N/A  
`visit` | ? | ? | `visit`  
`visitkeys` | ? | ? | ?  
`visitvalues` | ? | ? | ?  
`visititems` | ? | ? | `visititems`  
`tree` | `tree` | `tree` | `Both`  
`create_group` | `create_group` | `create_group` | `create_group`  
`require_group` | N/A | N/A | `require_group`  
`create_groups` | ? | ? | N/A  
`require_groups` | ? | ? | ?  
`create_dataset` | N/A | N/A | `create_dataset`  
`require_dataset` | N/A | N/A | `require_dataset`  
`create` | `create_array` | `create_array` | N/A  
`empty` | `empty` | `empty` | N/A  
`zeros` | `zeros` | `zeros` | N/A  
`ones` | `ones` | `ones` | N/A  
`full` | `full` | `full` | N/A  
`array` | `create_array` | `create_array` | N/A  
`empty_like` | `empty_like` | `empty_like` | N/A  
`zeros_like` | `zeros_like` | `zeros_like` | N/A  
`ones_like` | `ones_like` | `ones_like` | N/A  
`full_like` | `full_like` | `full_like` | N/A  
`move` | `move` | `move` | `move`  
  
**``zarr.h5compat.Group``** – Zarr-Python 2.* made an attempt to align its API
with that of [h5py](https://docs.h5py.org/en/stable/index.html). With 3.0, we
will relax this alignment in favor of providing an explicit compatibility
module (`zarr.h5py_compat`). This module will expose the `Group` and `Dataset`
APIs that map to Zarr-Python’s `Group` and `Array` objects.

##### Creation API#

Zarr-Python 2.* bundles together the creation and serialization of Zarr
objects. Zarr-Python 3.* will make it possible to create objects in memory
separate from serializing them. This will specifically enable writing
hierarchies of Zarr objects in a single batch step. For example:

    
    
    arr1 = Array(shape=(10, 10), path="foo/bar", dtype="i4", store=store)
    arr2 = Array(shape=(10, 10), path="foo/spam", dtype="f8", store=store)
    
    arr1.save()
    arr2.save()
    
    # or equivalently
    
    zarr.save_many([arr1 ,arr2])
    

_Note: this batch creation API likely needs additional design effort prior to
implementation._

##### Plugin API#

Zarr V3 was designed to be extensible at multiple layers. Zarr-Python will
support these extensions through a combination of [Abstract Base
Classes](https://docs.python.org/3/library/abc.html) (ABCs) and
[Entrypoints](https://packaging.python.org/en/latest/specifications/entry-
points/).

**ABCs**

Zarr V3 will expose Abstract base classes for the following objects:

  * `Store`, `ReadStore`, `ReadWriteStore`, `ReadListStore`, and `ReadWriteListStore`

  * `BaseArray`, `SynchronousArray`, and `AsynchronousArray`

  * `BaseGroup`, `SynchronousGroup`, and `AsynchronousGroup`

  * `Codec`, `ArrayArrayCodec`, `ArrayBytesCodec`, `BytesBytesCodec`

**Entrypoints**

Lots more thinking here but the idea here is to provide entrypoints for `data
type`, `chunk grid`, `chunk key encoding`, `codecs`, `storage_transformers`
and `stores`. These might look something like:

    
    
    entry_points="""
        [zarr.codecs]
        blosc_codec=codec_plugin:make_blosc_codec
        zlib_codec=codec_plugin:make_zlib_codec
    """
    

##### Python type hints and static analysis#

Target 100% Mypy coverage in 3.0 source.

##### Observability#

A persistent problem in Zarr-Python is diagnosing problems that span many
parts of the stack. To address this in 3.0, we will add a basic logging
framework that can be used to debug behavior at various levels of the stack.
We propose to add the separate loggers for the following namespaces:

  * `array`

  * `group`

  * `store`

  * `codec`

These should be documented such that users know how to activate them and
developers know how to use them when developing extensions.

##### Dependencies#

Today, Zarr-Python has the following required dependencies:

    
    
    dependencies = [
        'asciitree',
        'numpy>=1.20,!=1.21.0',
        'fasteners',
        'numcodecs>=0.10.0',
    ]
    

What other dependencies should be considered?

  1. Attrs - Zarrita makes extensive use of the Attrs library

  2. Fsspec - Zarrita has a hard dependency on Fsspec. This could be easily relaxed though.

#### Breaking changes relative to Zarr-Python 2.*#

  1. H5py compat moved to a stand alone module?

  2. `Group.__getitem__` support moved to `Group.members.__getitem__`?

  3. Others?

#### Open questions#

  1. How to treat V2

     1. Note: Zarrita currently implements a separate `V2Array` and `V3Array` classes. This feels less than ideal.

     2. We could easily convert metadata from v2 to the V3 Array, but what about writing?

     3. Ideally, we don’t have completely separate code paths. But if its too complicated to support both within one interface, its probably better.

  2. How and when to remove the current implementation of V3.

     1. It’s hidden behind a hard-to-use feature flag so we probably don’t need to do anything.

  3. How to model runtime configuration?

  4. Which extensions belong in Zarr-Python and which belong in separate packages?

     1. We don’t need to take a strong position on this here. It’s likely that someone will want to put Sharding in. That will be useful to develop in parallel because it will give us a good test case for the plugin interface.

#### Testing#

Zarr-python 3.0 adds a major new dimension to Zarr: Async support. This also
comes with a compatibility risk, we will need to thoroughly test support in
key execution environments. Testing plan: - Reuse the existing test suite for
testing the `v3` API. - `xfail` tests that expose breaking changes with `3.0 -
breaking change` description. This will help identify additional and/or
unintentional breaking changes - Rework tests that were only testing internal
APIs. - Add a set of functional / integration tests targeting real-world
workflows in various contexts (e.g. w/ Dask)

#### Development process#

Zarr-Python 3.0 will introduce a number of new APIs and breaking changes to
existing APIs. In order to facilitate ongoing support for Zarr-Python 2.*, we
will take on the following development process:

  * Create a `v3` branch that can be use for developing the core functionality apart from the `main` branch. This will allow us to support ongoing work and bug fixes on the `main` branch.

  * Put the `3.0` APIs inside a `zarr.v3` module. Imports from this namespace will all be new APIs that users can develop and test against once the `v3` branch is merged to `main`.

  * Kickstart the process by pulling in the current state of `zarrita` \- which has many of the features described in this design.

  * Release a series of 2.* releases with the `v3` namespace

  * When `v3` is complete, move contents of `v3` to the package root

**Milestones**

Below are a set of specific milestones leading toward the completion of this
process. As work begins, we expect this list to grow in specificity.

  1. Port current version of Zarrita to Zarr-Python

  2. Formalize Async interface by splitting `Array` and `Group` objects into Sync and Async versions

  3. Implement “fancy” indexing operations on the `AsyncArray`

  4. Implement an abstract base class for the `Store` interface and a wrapper `Store` to make use of existing `MutableMapping` stores.

  5. Rework the existing unit test suite to use the `v3` namespace.

  6. Develop a plugin interface for extensions

  7. Develop a set of functional and integration tests

  8. Work with downstream libraries (Xarray, Dask, etc.) to test new APIs

#### TODOs#

The following subjects are not covered in detail above but perhaps should be.
Including them here so they are not forgotten.

  1. [Store] Should Zarr provide an API for caching objects after first read/list/etc. Read only stores?

  2. [Array] buffer protocol support

  3. [Array] `meta_array` support

  4. [Extensions] Define how Zarr-Python will consume the various plugin types

  5. [Misc] H5py compatibility requires a bit more work and a champion to drive it forward.

  6. [Misc] Define `chunk_store` API in 3.0

  7. [Misc] Define `synchronizer` API in 3.0

#### References#

  1. [Zarr-Python repository](https://github.com/zarr-developers/zarr-python)

  2. [Zarr core specification (version 3.0) — Zarr specs documentation](https://zarr-specs.readthedocs.io/en/latest/v3/core/v3.0.html#)

  3. [Zarrita repository](https://github.com/scalableminds/zarrita)

  4. [Async-Zarr](https://github.com/martindurant/async-zarr)

  5. [Zarr-Python Discussion Topic](https://github.com/zarr-developers/zarr-python/discussions/1569)

## About#

Zarr is a format for the storage of chunked, compressed, N-dimensional arrays
inspired by [HDF5](https://www.hdfgroup.org/HDF5/),
[h5py](https://www.h5py.org/) and [bcolz](https://bcolz.readthedocs.io/).

These documents describe the Zarr-Python implementation. More information
about the Zarr format can be found on the [main website](https://zarr.dev).

### Projects using Zarr#

If you are using Zarr-Python, we would [love to hear about
it](https://github.com/zarr-developers/community/issues/19).

### Funding#

The project is fiscally sponsored by [NumFOCUS](https://numfocus.org/), a US
501(c)(3) public charity, and development is supported by the [MRC Centre for
Genomics and Global Health](https://github.com/cggh/) and the [Chan Zuckerberg
Initiative](https://chanzuckerberg.com/).

**Version** : 3.1.1

**Useful links** : [Source Repository](https://github.com/zarr-developers/zarr-python) | [Issue Tracker](https://github.com/zarr-developers/zarr-python/issues) | [Developer Chat](https://ossci.zulipchat.com/) | [Zarr specifications](https://zarr-specs.readthedocs.io)

Zarr-Python is a Python library for reading and writing Zarr groups and
arrays. Highlights include:

  * Specification support for both Zarr format 2 and 3.

  * Create and read from N-dimensional arrays using NumPy-like semantics.

  * Flexible storage enables reading and writing from local, cloud and in-memory stores.

  * High performance: Enables fast I/O with support for asynchronous I/O and multi-threading.

  * Extensible: Customizable with user-defined codecs and stores.

Quick Start

New to Zarr? Check out the quick start guide. It contains a brief introduction
to Zarr’s main concepts and links to additional tutorials.

To the Quick Start

Guide

A detailed guide for how to use Zarr-Python.

To the user guide

API Reference

The reference guide contains a detailed description of the functions, modules,
and objects included in Zarr. The reference describes how the methods work and
which parameters can be used. It assumes that you have an understanding of the
key concepts.

To the API reference

Contributor’s Guide

Want to contribute to Zarr? We welcome contributions in the form of bug
reports, bug fixes, documentation, enhancement proposals and more. The
contributing guidelines will guide you through the process of improving Zarr.

To the contributor’s guide

**Download documentation** : [PDF/Zipped
HTML](https://readthedocs.org/projects/zarr/downloads/)

__On this page

  * Quickstart
  * User guide
  * API reference
  * Release notes
  * Developer’s Guide
  * About

© Copyright 2025, Zarr Developers.  

Created using [Sphinx](https://www.sphinx-doc.org/) 8.1.3.  

Built with the [PyData Sphinx Theme](https://pydata-sphinx-
theme.readthedocs.io/en/stable/index.html) 0.16.1.