Skills › Scientific Agent Skills › zarr-python › api_reference.md

api_reference.md

68 lines · skills/zarr-python/references/api_reference.md at 5f2bc03

1# Zarr-Python 3.4.0 API reference

3These are selected callable forms, not exhaustive copied signatures. Explicitly select

4format/mode when behavior matters; defaults can also be affected by runtime configuration.

6| Operation | Current form / behavior |

7|---|---|

8| New array | `zarr.create_array(store, shape=..., dtype=..., chunks="auto", shards=None, compressors="auto", overwrite=False)`; `store=None` gives memory. |

9| From NumPy | `zarr.create_array(store, data=values, chunks=...)`; omit both shape and dtype. |

10| Copy array | `zarr.from_array(store, data=source, chunks="keep", shards="keep")`; preserve tested source semantics, validate destination after copying. |

11| Convenience | `zarr.zeros(shape, **kwargs)`, `ones`, `empty`, `full(shape, fill_value, **kwargs)`, `array(data, **kwargs)`, `zeros_like(source, **kwargs)`. `empty` does not establish scientifically meaningful values. |

12| Open array | `zarr.open_array(store, mode="r", path="", zarr_format=None, storage_options=None)`; mode is forwarded through kwargs. |

13| Open unknown node | `zarr.open(store, mode="r")` detects array/group; default signature mode is `None`, resolved from store writability (normally `"a"`). |

14| Open group | `zarr.open_group(store, mode="r", path=None, use_consolidated=None)`; `None` uses consolidation if available, `False` bypasses, `True` requires it. |

15| Create/require child | `group.create_array(name, ...)`, `require_array(name, shape=..., dtype=...)`, `create_group(name)`, `require_group(name)`. |

16| Resize/append | `array.resize(new_shape_tuple)` returns None; `array.append(data, axis=0)` returns the new shape. |

17| Metadata | `array.attrs`, `group.attrs` hold JSON-compatible values; native v3 `dimension_names` are not coordinate arrays. |

18| Sizing | `array.nbytes` is logical bytes; **`array.nbytes_stored()`** computes stored bytes. `array.info` is metadata; `array.info_complete()` obtains storage-dependent details. |

19| Consolidate | `zarr.consolidate_metadata(store, path=None, zarr_format=None)` returns Group; supply a configured store for credentials. |

20| Require consolidation | `zarr.open_consolidated(store, mode="r", ...)` returns Group, not Array. |

22Modes: `r` existing read-only; `r+` existing read/write; `a` open or create; `w` replace;

23`w-` create only. Creation flags are not distributed exclusive-writer locks.

25On an existing array, `open_array(..., config=...)` does not forward that configuration

26in 3.4.0. Use a `zarr.config.set` context before opening when enforcing missing-chunk

27policy; see the tested example in [performance](performance_and_patterns.md).

Zarr-Python 3.4.0 API reference

These are selected callable forms, not exhaustive copied signatures. Explicitly select format/mode when behavior matters; defaults can also be affected by runtime configuration.

Operation	Current form / behavior
New array	`zarr.create_array(store, shape=..., dtype=..., chunks="auto", shards=None, compressors="auto", overwrite=False)`; `store=None` gives memory.
From NumPy	`zarr.create_array(store, data=values, chunks=...)`; omit both shape and dtype.
Copy array	`zarr.from_array(store, data=source, chunks="keep", shards="keep")`; preserve tested source semantics, validate destination after copying.
Convenience	`zarr.zeros(shape, kwargs)`, `ones`, `empty`, `full(shape, fill_value, kwargs)`, `array(data, kwargs)`, `zeros_like(source, kwargs)`. `empty` does not establish scientifically meaningful values.
Open array	`zarr.open_array(store, mode="r", path="", zarr_format=None, storage_options=None)`; mode is forwarded through kwargs.
Open unknown node	`zarr.open(store, mode="r")` detects array/group; default signature mode is `None`, resolved from store writability (normally `"a"`).
Open group	`zarr.open_group(store, mode="r", path=None, use_consolidated=None)`; `None` uses consolidation if available, `False` bypasses, `True` requires it.
Create/require child	`group.create_array(name, ...)`, `require_array(name, shape=..., dtype=...)`, `create_group(name)`, `require_group(name)`.
Resize/append	`array.resize(new_shape_tuple)` returns None; `array.append(data, axis=0)` returns the new shape.
Metadata	`array.attrs`, `group.attrs` hold JSON-compatible values; native v3 `dimension_names` are not coordinate arrays.
Sizing	`array.nbytes` is logical bytes; `array.nbytes_stored()` computes stored bytes. `array.info` is metadata; `array.info_complete()` obtains storage-dependent details.
Consolidate	`zarr.consolidate_metadata(store, path=None, zarr_format=None)` returns Group; supply a configured store for credentials.
Require consolidation	`zarr.open_consolidated(store, mode="r", ...)` returns Group, not Array.

Modes: r existing read-only; r+ existing read/write; a open or create; w replace; w- create only. Creation flags are not distributed exclusive-writer locks.

On an existing array, open_array(..., config=...) does not forward that configuration in 3.4.0. Use a zarr.config.set context before opening when enforcing missing-chunk policy; see the tested example in performance.

Raw lines 1 to 28

29## Selection semantics

31For a 2-D array, `z.vindex[[0, 5], [2, 7]]` pairs coordinates and returns two values;

32`z.oindex[[0, 5], [2, 7]]` returns a 2-by-2 Cartesian product. Explicit coordinate

33selection takes a tuple of per-axis coordinate arrays:

34`z.get_coordinate_selection(([0, 5], [2, 7]))`. `z.blocks[i, j]` selects chunks.

35Negative-step slices are unsupported. Rectilinear grids require an experimental flag;

36`Array.chunks` cannot describe every rectilinear layout with one tuple.

Selection semantics

For a 2-D array, z.vindex[[0, 5], [2, 7]] pairs coordinates and returns two values; z.oindex[[0, 5], [2, 7]] returns a 2-by-2 Cartesian product. Explicit coordinate selection takes a tuple of per-axis coordinate arrays: z.get_coordinate_selection(([0, 5], [2, 7])). z.blocks[i, j] selects chunks. Negative-step slices are unsupported. Rectilinear grids require an experimental flag; Array.chunks cannot describe every rectilinear layout with one tuple.

Raw lines 29 to 37

38## Stores and codecs

40`LocalStore`, `MemoryStore`, `ZipStore`, `FsspecStore`, and `ObjectStore` live in

41`zarr.storage`. ObjectStore requires obstore; FsspecStore requires fsspec plus the

42selected protocol backend. `FsspecStore.from_url(url, storage_options=None,

43read_only=False)` resolves the URI. Old DirectoryStore/FSStore names are replaced;

44legacy database/N5 stores are removed. S3Map/GCSMap are backend mappings, not newly

45supported Zarr store classes.

47For format 3, use `zarr.codecs.BloscCodec`, `GzipCodec`, `ZstdCodec`;

48pass `shuffle="bitshuffle"` to BloscCodec (the BloscShuffle enum is deprecated).

49`compressors=None` disables compression, not serialization. Format-2 arrays use

50NumCodecs (e.g. `numcodecs.Blosc`) through `compressors=` in `create_array`. Numeric

51format-3 defaults are Zstd; use `"auto"`, not the invalid `"default"` string.

Stores and codecs

LocalStore, MemoryStore, ZipStore, FsspecStore, and ObjectStore live in zarr.storage. ObjectStore requires obstore; FsspecStore requires fsspec plus the selected protocol backend. FsspecStore.from_url(url, storage_options=None, read_only=False) resolves the URI. Old DirectoryStore/FSStore names are replaced; legacy database/N5 stores are removed. S3Map/GCSMap are backend mappings, not newly supported Zarr store classes.

For format 3, use zarr.codecs.BloscCodec, GzipCodec, ZstdCodec; pass shuffle="bitshuffle" to BloscCodec (the BloscShuffle enum is deprecated). compressors=None disables compression, not serialization. Format-2 arrays use NumCodecs (e.g. numcodecs.Blosc) through compressors= in create_array. Numeric format-3 defaults are Zstd; use "auto", not the invalid "default" string.

Raw lines 38 to 52

53## Exceptions and coordination

55Missing nodes use `NodeNotFoundError` / `ArrayNotFoundError` / `GroupNotFoundError`;

56`PathNotFoundError` and `ReadOnlyError` are not exported by this release. Read-only

57mutation raises ValueError. `UnknownCodecError` subclasses ValueError; malformed

58metadata may raise `MetadataValidationError`. Preserve the original error context;

59authentication errors must not be treated as missing chunks.

61Use one writer per stored object (per **shard** if sharded), including boundaries.

62No working v2 synchronizers are provided. Neither consolidation nor `require_array`

63is a transaction or a lock. Current concurrency configuration keys include

64`async.concurrency` and `threading.max_workers`.

66Sources: [API](https://zarr.readthedocs.io/en/stable/api/zarr/),

67[released sync API](https://github.com/zarr-developers/zarr-python/blob/v3.4.0/src/zarr/api/synchronous.py),

68[released errors](https://github.com/zarr-developers/zarr-python/blob/v3.4.0/src/zarr/errors.py).

Exceptions and coordination

Missing nodes use NodeNotFoundError / ArrayNotFoundError / GroupNotFoundError; PathNotFoundError and ReadOnlyError are not exported by this release. Read-only mutation raises ValueError. UnknownCodecError subclasses ValueError; malformed metadata may raise MetadataValidationError. Preserve the original error context; authentication errors must not be treated as missing chunks.

Use one writer per stored object (per shard if sharded), including boundaries. No working v2 synchronizers are provided. Neither consolidation nor require_array is a transaction or a lock. Current concurrency configuration keys include async.concurrency and threading.max_workers.

Sources: API, released sync API, released errors.

Raw lines 53 to 68