Skip to content

Convenience sub-module

zarr.convenience

Convenience helpers.

Deprecated

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

consolidate_metadata 

consolidate_metadata(
    store: StoreLike,
    path: str | None = None,
    zarr_format: ZarrFormat | None = None,
) -> 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, default: None ) –

    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), default: 2 ) –

    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.

Source code in zarr/api/synchronous.py 
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
def consolidate_metadata(
    store: StoreLike,
    path: str | None = None,
    zarr_format: ZarrFormat | None = None,
) -> 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``.

    """
    return Group(sync(async_api.consolidate_metadata(store, path=path, zarr_format=zarr_format)))

copy 

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

Not implemented.

Source code in zarr/api/synchronous.py 
114
115
116
117
118
def copy(*args: Any, **kwargs: Any) -> tuple[int, int, int]:
    """
    Not implemented.
    """
    return sync(async_api.copy(*args, **kwargs))

copy_all 

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

Not implemented.

Source code in zarr/api/synchronous.py 
121
122
123
124
125
def copy_all(*args: Any, **kwargs: Any) -> tuple[int, int, int]:
    """
    Not implemented.
    """
    return sync(async_api.copy_all(*args, **kwargs))

copy_store 

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

Not implemented.

Source code in zarr/api/synchronous.py 
128
129
130
131
132
def copy_store(*args: Any, **kwargs: Any) -> tuple[int, int, int]:
    """
    Not implemented.
    """
    return sync(async_api.copy_store(*args, **kwargs))

load 

load(
    store: StoreLike,
    path: str | None = None,
    zarr_format: ZarrFormat | None = None,
    zarr_version: ZarrFormat | None = None,
) -> NDArrayLikeOrScalar | dict[str, NDArrayLikeOrScalar]

Load data from an array or group into memory.

Parameters:

  • store (StoreLike) –

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

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

    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.

Source code in zarr/api/synchronous.py 
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
def load(
    store: StoreLike,
    path: str | None = None,
    zarr_format: ZarrFormat | None = None,
    zarr_version: ZarrFormat | None = None,
) -> NDArrayLikeOrScalar | dict[str, NDArrayLikeOrScalar]:
    """Load data from an array or group into memory.

    Parameters
    ----------
    store : StoreLike
        Store or path to directory in file system or name of zip file.
    path : str or None, optional
        The path within the store from which to load.

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

    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.
    """
    return sync(
        async_api.load(store=store, zarr_version=zarr_version, zarr_format=zarr_format, path=path)
    )

open 

open(
    store: StoreLike | None = None,
    *,
    mode: AccessModeLiteral | None = None,
    zarr_version: ZarrFormat | None = None,
    zarr_format: ZarrFormat | None = None,
    path: str | None = None,
    storage_options: dict[str, Any] | None = None,
    **kwargs: Any,
) -> Array | Group

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

Parameters:

  • store (StoreLike or None, default: None ) –

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

  • mode (('r', 'r+', 'a', 'w', 'w-'), default: 'r' ) –

    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), default: 2 ) –

    The zarr format to use when saving.

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

    The path within the store to open.

  • storage_options (dict, default: None ) –

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

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

    Additional parameters are passed through to zarr.creation.open_array or open_group.

Returns:

  • z ( array or group ) –

    Return type depends on what exists in the given store.

Source code in zarr/api/synchronous.py 
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
def open(
    store: StoreLike | None = None,
    *,
    mode: AccessModeLiteral | None = None,
    zarr_version: ZarrFormat | None = None,  # deprecated
    zarr_format: ZarrFormat | None = None,
    path: str | None = None,
    storage_options: dict[str, Any] | None = None,
    **kwargs: Any,  # TODO: type kwargs as valid args to async_api.open
) -> Array | Group:
    """Open a group or array using file-mode-like semantics.

    Parameters
    ----------
    store : StoreLike or None, default=None
        Store or path to directory in file system or name of zip file.
    mode : {'r', 'r+', 'a', 'w', 'w-'}, optional
        Persistence mode: 'r' means read only (must exist); 'r+' means
        read/write (must exist); 'a' means read/write (create if doesn't
        exist); 'w' means create (overwrite if exists); 'w-' means create
        (fail if exists).
        If the store is read-only, the default is 'r'; otherwise, it is 'a'.
    zarr_format : {2, 3, None}, optional
        The zarr format to use when saving.
    path : str or None, optional
        The path within the store to open.
    storage_options : dict
        If using an fsspec URL to create the store, these will be passed to
        the backend implementation. Ignored otherwise.
    **kwargs
        Additional parameters are passed through to [`zarr.creation.open_array`][] or
        [`open_group`][zarr.api.asynchronous.open_group].

    Returns
    -------
    z : array or group
        Return type depends on what exists in the given store.
    """
    obj = sync(
        async_api.open(
            store=store,
            mode=mode,
            zarr_version=zarr_version,
            zarr_format=zarr_format,
            path=path,
            storage_options=storage_options,
            **kwargs,
        )
    )
    if isinstance(obj, AsyncArray):
        return Array(obj)
    else:
        return Group(obj)

open_consolidated 

open_consolidated(
    *args: Any,
    use_consolidated: Literal[True] = True,
    **kwargs: Any,
) -> Group

Alias for open_group with use_consolidated=True.

Source code in zarr/api/synchronous.py 
226
227
228
229
230
231
232
def open_consolidated(*args: Any, use_consolidated: Literal[True] = True, **kwargs: Any) -> Group:
    """
    Alias for [`open_group`][zarr.api.synchronous.open_group] with ``use_consolidated=True``.
    """
    return Group(
        sync(async_api.open_consolidated(*args, use_consolidated=use_consolidated, **kwargs))
    )

save 

save(
    store: StoreLike,
    *args: NDArrayLike,
    zarr_version: ZarrFormat | None = None,
    zarr_format: ZarrFormat | None = None,
    path: str | None = None,
    **kwargs: Any,
) -> None

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

Parameters:

  • store (StoreLike) –

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

  • *args (ndarray, default: () ) –

    NumPy arrays with data to save.

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

    The zarr format to use when saving.

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

    The path within the group where the arrays will be saved.

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

    NumPy arrays with data to save.

Source code in zarr/api/synchronous.py 
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
def save(
    store: StoreLike,
    *args: NDArrayLike,
    zarr_version: ZarrFormat | None = None,  # deprecated
    zarr_format: ZarrFormat | None = None,
    path: str | None = None,
    **kwargs: Any,  # TODO: type kwargs as valid args to async_api.save
) -> None:
    """Save an array or group of arrays to the local file system.

    Parameters
    ----------
    store : StoreLike
        Store or path to directory in file system or name of zip file.
    *args : ndarray
        NumPy arrays with data to save.
    zarr_format : {2, 3, None}, optional
        The zarr format to use when saving.
    path : str or None, optional
        The path within the group where the arrays will be saved.
    **kwargs
        NumPy arrays with data to save.
    """
    return sync(
        async_api.save(
            store, *args, zarr_version=zarr_version, zarr_format=zarr_format, path=path, **kwargs
        )
    )

save_array 

save_array(
    store: StoreLike,
    arr: NDArrayLike,
    *,
    zarr_version: ZarrFormat | None = None,
    zarr_format: ZarrFormat | None = None,
    path: str | None = None,
    storage_options: dict[str, Any] | None = None,
    **kwargs: Any,
) -> None

Save a NumPy array to the local file system.

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

Parameters:

  • store (StoreLike) –

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

  • arr (ndarray) –

    NumPy array with data to save.

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

    The zarr format to use when saving. The default is None, which will use the default Zarr format defined in the global configuration object.

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

    The path within the store where the array will be saved.

  • storage_options (dict, default: None ) –

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

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

    Passed through to create, e.g., compressor.

Source code in zarr/api/synchronous.py 
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
def save_array(
    store: StoreLike,
    arr: NDArrayLike,
    *,
    zarr_version: ZarrFormat | None = None,  # deprecated
    zarr_format: ZarrFormat | None = None,
    path: str | None = None,
    storage_options: dict[str, Any] | None = None,
    **kwargs: Any,  # TODO: type kwargs as valid args to async_api.save_array
) -> None:
    """Save a NumPy array to the local file system.

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

    Parameters
    ----------
    store : StoreLike
        Store or path to directory in file system or name of zip file.
    arr : ndarray
        NumPy array with data to save.
    zarr_format : {2, 3, None}, optional
        The zarr format to use when saving. The default is ``None``, which will
        use the default Zarr format defined in the global configuration object.
    path : str or None, optional
        The path within the store where the array will be saved.
    storage_options : dict
        If using an fsspec URL to create the store, these will be passed to
        the backend implementation. Ignored otherwise.
    **kwargs
        Passed through to [`create`][zarr.api.asynchronous.create], e.g., compressor.
    """
    return sync(
        async_api.save_array(
            store=store,
            arr=arr,
            zarr_version=zarr_version,
            zarr_format=zarr_format,
            path=path,
            storage_options=storage_options,
            **kwargs,
        )
    )

save_group 

save_group(
    store: StoreLike,
    *args: NDArrayLike,
    zarr_version: ZarrFormat | None = None,
    zarr_format: ZarrFormat | None = None,
    path: str | None = None,
    storage_options: dict[str, Any] | None = None,
    **kwargs: NDArrayLike,
) -> None

Save several NumPy arrays to the local file system.

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

Parameters:

  • store (StoreLike) –

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

  • *args (ndarray, default: () ) –

    NumPy arrays with data to save.

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

    The zarr format to use when saving.

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

    Path within the store where the group will be saved.

  • storage_options (dict, default: None ) –

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

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

    NumPy arrays with data to save.

Source code in zarr/api/synchronous.py 
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
def save_group(
    store: StoreLike,
    *args: NDArrayLike,
    zarr_version: ZarrFormat | None = None,  # deprecated
    zarr_format: ZarrFormat | None = None,
    path: str | None = None,
    storage_options: dict[str, Any] | None = None,
    **kwargs: NDArrayLike,
) -> None:
    """Save several NumPy arrays to the local file system.

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

    Parameters
    ----------
    store : StoreLike
        Store or path to directory in file system or name of zip file.
    *args : ndarray
        NumPy arrays with data to save.
    zarr_format : {2, 3, None}, optional
        The zarr format to use when saving.
    path : str or None, optional
        Path within the store where the group will be saved.
    storage_options : dict
        If using an fsspec URL to create the store, these will be passed to
        the backend implementation. Ignored otherwise.
    **kwargs
        NumPy arrays with data to save.
    """

    return sync(
        async_api.save_group(
            store,
            *args,
            zarr_version=zarr_version,
            zarr_format=zarr_format,
            path=path,
            storage_options=storage_options,
            **kwargs,
        )
    )

tree 

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

Provide a rich display of the hierarchy.

Deprecated

zarr.tree() is deprecated since v3.0.0 and will be removed in a future release. Use group.tree() instead.

Parameters:

  • grp (Group) –

    Zarr or h5py group.

  • expand (bool, default: None ) –

    Only relevant for HTML representation. If True, tree will be fully expanded.

  • level (int, default: None ) –

    Maximum depth to descend into hierarchy.

Returns:

  • TreeRepr –

    A pretty-printable object displaying the hierarchy.

Source code in zarr/api/synchronous.py 
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
@deprecated("Use Group.tree instead.", category=ZarrDeprecationWarning)
def tree(grp: Group, expand: bool | None = None, level: int | None = None) -> Any:
    """Provide a rich display of the hierarchy.

    !!! warning "Deprecated"
        `zarr.tree()` is deprecated since v3.0.0 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.
    """
    return sync(async_api.tree(grp._async_group, expand=expand, level=level))