Skip to content

abczarr.metadata.base

The version-independent metadata model.

Every node in a Zarr hierarchy, a group or an array, is described by a small JSON document: zarr.json in Zarr v3, .zarray or .zgroup plus .zattrs in v2, and .zarray plus .zattrs in v1. This module defines the typed classes that document holds, one set per format version, and the shared vocabulary that lets code work with a node's metadata without caring which version produced it: ArrayMetadata and GroupMetadata.

ArrayMetadata.to_version converts a node's metadata to another format version. Not every version can represent everything another version can. ConversionPolicy controls how such a conversion treats a field it cannot carry over.

This file contains code from the Zarr project https://github.com/zarr-developers/zarr-python

Attributes

ConversionPolicy module-attribute 

ConversionPolicy = tx.Literal['lossy', 'warn', 'strict']

Classes

FlexibleMetadata 

FlexibleMetadata(*, extra_items: Iterable[tuple[str | bytes, Real | floating | bool | bool | int | str | bytes | Iterable[()] | None]] | Mapping[str | bytes, Real | floating | bool | bool | int | str | bytes | Iterable[()] | None] = FrozenDict({}))

Bases: Metadata

A Metadata subclass that keeps every unrecognized JSON key instead of rejecting it.

A key in a JSON document that names none of a subclass's own fields is collected into extra_items rather than raised as an error, and to_json writes those extra items back alongside the typed fields.

Methods:

Metadata 

Metadata()

A frozen, JSON-serializable metadata document.

An instance's fields are set at construction and never change afterward. to_json serializes the fields, recursing into any field that is itself a Metadata instance, and from_json rebuilds an instance from the result. A field also supports dict-like read access: metadata["field"] and iteration work alongside the usual attribute access.

Methods:

__new__ 
__new__(*args, **kwargs) -> Self
__getitem__ 
__getitem__(key: str) -> Any

Get a field's value by name, or an extra item's value by key on a subclass that carries extra_items.

Raises KeyError when key names neither.

__iter__ 
__iter__() -> Iterator[tuple[str, Any]]

Iterate over the field names, and, on a subclass that carries extra_items, the keys of those extra items afterward.

keys 
keys() -> tuple[str, ...]

The field names, and any extra item keys, as a tuple.

to_json 
to_json() -> JsonDict

Convert this metadata to a JSON-serializable dict.

Serializes this object's own fields. A nested metadata value is serialized through its own to_json, so a subclass that overrides it (an Extension that writes itself as a bare name) is respected.

from_json classmethod 
from_json(data: JsonDict) -> Self

Build an instance from a JSON document.

data is ordinarily a dict, keyed by each field's JSON key. When it is not a mapping, it is treated as the value of the class's first positional field, provided the class has one. Otherwise, TypeError is raised. The class actually constructed may be a subclass more specific than cls, chosen by register_subclass's discriminators. Any key in data that names no field of the chosen class is collected into extra_items, on a subclass that carries one.

Parameters:

Name Type Description Default
data dict or Any

The JSON document, or a single positional value.

 required

Returns:

Type Description
Self

The constructed instance, of cls or one of its registered subclasses.

Raises:

Type Description
TypeError

When data is not a mapping and cls has no positional field to hold it.

NodeMetadata 

NodeMetadata(attributes: Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] = {}, zarr_format: Literal[1, 2, 3] = 3, node_type: Literal['group', 'array'] = 'group')

Bases: Metadata

The metadata common to every node in a Zarr hierarchy.

A node is either a group or an array. Both kinds carry user attributes and a format version. GroupMetadata, ArrayMetadata, and their per-version subclasses are the classes to construct. This class holds only what they share.

Attributes

attributes instance-attribute 
attributes: JsonDict

The node's user-defined attributes, stored as arbitrary JSON.

zarr_format class-attribute instance-attribute 
zarr_format: ZarrVersion = 3

The Zarr format version the metadata is written in: 1, 2 or 3.

node_type class-attribute instance-attribute 
node_type: NodeType = 'group'

Either "group" or "array".

Methods:

update_attributes 
update_attributes(attributes: JsonDict) -> Self

Return a copy of this metadata with new attributes.

Every other field, such as shape, dtype, and chunking, is unchanged.

Parameters:

Name Type Description Default
attributes dict

The user attributes the returned metadata carries, replacing the current ones in full.

 required

Returns:

Type Description
NodeMetadata

A new metadata object with attributes replaced.
from_file classmethod 
from_file(root: PathLike) -> Self

Load a node's metadata from its directory.

The Zarr format version is detected from which metadata file is present under root: zarr.json for v3, .zarray or .zgroup for v2, or .zarray for v1. The metadata is returned as an instance of the matching version's class.

Parameters:

Name Type Description Default
root PathLike

The directory holding the node's metadata files.

 required

Returns:

Type Description
NodeMetadata

The loaded metadata, as an instance of the class matching the detected format version.

Raises:

Type Description
FileNotFoundError

If root holds no recognized metadata file.

GroupMetadata 

GroupMetadata(attributes: Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] = {}, zarr_format: Literal[1, 2, 3] = 3, node_type: Literal['group'] = 'group')

Bases: NodeMetadata

A group's metadata: user attributes and a format version.

A group holds no data of its own, so beyond what NodeMetadata already defines, this class adds nothing but its node_type. A member and its metadata are reached through the store, not through this object.

Attributes

node_type class-attribute instance-attribute 
node_type: Literal['group'] = 'group'

Always "group".

Methods:

to_version 
to_version(version: ZarrVersion, policy: ConversionPolicy = 'lossy') -> GroupMetadata

Convert this group's metadata to another Zarr version.

A group carries only user attributes and a format version. Converting between v2 and v3 re-stamps the format and carries the attributes across unchanged, so nothing is lost and policy is never invoked. Zarr v1 has no group concept, so converting a group to v1 raises regardless of policy.

Parameters:

Name Type Description Default
version ZarrVersion

The target Zarr format version: 1, 2 or 3.

 required
policy ConversionPolicy

How to treat a field the target version cannot hold. This parameter exists to match the signature of ArrayMetadata.to_version. No field of a group's metadata is affected by it between v2 and v3.

 'lossy'

Returns:

Type Description
GroupMetadata

Equivalent metadata for version. Converting to the group's own version returns this object unchanged.

Raises:

Type Description
ValueError

If version is not 1, 2 or 3.
UnsupportedConversion

If version is 1, which has no group concept.

ArrayMetadata 

ArrayMetadata(attributes: Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] = {}, zarr_format: Literal[1, 2, 3] = 3, node_type: Literal['array'] = 'array')

Bases: NodeMetadata

An array's metadata: shape, data type, chunking and codecs.

The exact fields depend on the Zarr format version. See ArrayMetadataV1, ArrayMetadataV2 and ArrayMetadataV3 for the concrete field sets. Every version shares to_version, which converts the metadata between versions, and required_features, which reports what a driver needs to support in order to read or write the array.

Attributes

node_type class-attribute instance-attribute 
node_type: Literal['array'] = 'array'

Always "array".

Methods:

required_features 
required_features() -> FrozenSet[str]

Report the features a driver needs to read or write this array.

Each feature is a namespaced key built from the array's codecs, chunk grid, chunk-key encoding, and data type, such as "v3:codec:zstd" or "v2:filter:delta". A driver compares this set against what it supports to decide whether it can open the array. That names an unsupported codec up front, before a read ever starts.

Every concrete array metadata class overrides this method with its own version-specific keys.

Returns:

Type Description
frozenset of str

The feature keys this array requires. The base implementation returns an empty set.

NodeMetadataV1 

NodeMetadataV1(attributes: Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] = {}, zarr_format: Literal[1] = 1, node_type: Literal['group', 'array'] = 'group')

Bases: NodeMetadata

A Zarr v1 node's metadata.

Zarr v1 has no groups, so every node is an array. Use ArrayMetadataV1 directly, or build one through this class with from_file or from_json.

Attributes

zarr_format class-attribute instance-attribute 
zarr_format: Literal[1] = 1

Always 1.

Methods:

from_file classmethod 
from_file(root: PathLike) -> Self

Load a v1 array's metadata from its directory.

The array's metadata is read from .zarray. Its user attributes are read from .zattrs, when that file is present.

Parameters:

Name Type Description Default
root PathLike

The directory holding .zarray and, optionally, .zattrs.

 required

Returns:

Type Description
ArrayMetadataV1

The loaded array metadata. Zarr v1 has no groups, so called on this class the result is always an array.
from_json classmethod 
from_json(data: JsonDict) -> Self

Build v1 metadata from a plain JSON-compatible dict.

Called on this class directly, the method returns ArrayMetadataV1 metadata, since Zarr v1 has no groups.

Parameters:

Name Type Description Default
data dict

The merged content of .zarray and .zattrs, with the attributes under the key "attributes". This is the same shape to_json produces.

 required

Returns:

Type Description
ArrayMetadataV1

The metadata built from data.

ArrayMetadataV1 

ArrayMetadataV1(attributes: Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] = {}, zarr_format: Literal[1] = 1, node_type: Literal['array'] = 'array')

Bases: NodeMetadataV1, ArrayMetadata

The array-specific fields shared by every Zarr v1 array.

See ArrayMetadata for the concrete class that adds the shape, chunking, data type and codec fields, and for its to_version method, which converts to v2 and v3.

Methods:

NodeMetadataV2 

NodeMetadataV2(attributes: Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] = {}, zarr_format: Literal[2] = 2, node_type: Literal['group', 'array'] = 'group')

Bases: NodeMetadata

A Zarr v2 node's metadata.

Use GroupMetadataV2 or ArrayMetadataV2 for the concrete field sets. Called on this class directly, from_file works out which one applies.

Attributes

zarr_format class-attribute instance-attribute 
zarr_format: Literal[2] = 2

Always 2.

Methods:

from_file classmethod 
from_file(root: PathLike) -> Self

Load a v2 node's metadata from its directory.

The node's metadata is read from .zarray or .zgroup, and its user attributes from .zattrs. Called on this class directly, the node type is detected from which of .zarray and .zgroup is present. Called on a group or array subclass, that subclass's own file is read directly.

Parameters:

Name Type Description Default
root PathLike

The directory holding the node's metadata files.

 required

Returns:

Type Description
NodeMetadataV2

The loaded metadata, as a GroupMetadataV2 or an ArrayMetadataV2.

Raises:

Type Description
FileNotFoundError

If root holds neither .zarray nor .zgroup.
to_file 
to_file(root: PathLike) -> None

Write this metadata to its directory.

The array or group fields are written to .zarray or .zgroup, and the user attributes to .zattrs. Each file is merged with whatever content is already there. Neither file is overwritten wholesale.

Parameters:

Name Type Description Default
root PathLike

The directory the metadata files are written under.

 required

GroupMetadataV2 

GroupMetadataV2(attributes: Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] = {}, zarr_format: Literal[2] = 2, node_type: Literal['group'] = 'group')

Bases: NodeMetadataV2, GroupMetadata

A Zarr v2 group's metadata: user attributes only.

Methods:

ArrayMetadataV2 

ArrayMetadataV2(attributes: Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] = {}, zarr_format: Literal[2] = 2, node_type: Literal['array'] = 'array')

Bases: NodeMetadataV2, ArrayMetadata

The array-specific fields shared by every Zarr v2 array.

See ArrayMetadata for the concrete class that adds the shape, chunking, data type, compressor and filter fields, and for its to_version method, which converts to v1 and v3.

Methods:

NodeMetadataV3 

NodeMetadataV3(attributes: Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] = {}, zarr_format: Literal[3] = 3, node_type: Literal['group', 'array'] = 'group')

Bases: NodeMetadata

A Zarr v3 node's metadata.

Use GroupMetadataV3 or ArrayMetadataV3 for the concrete field sets. A v3 node's type is recorded in its own zarr.json, so its node_type need not be known in advance to load it.

Attributes

zarr_format class-attribute instance-attribute 
zarr_format: Literal[3] = 3

Always 3.

Methods:

from_file classmethod 
from_file(root: PathLike) -> Self

Load a v3 node's metadata from its zarr.json.

Parameters:

Name Type Description Default
root PathLike

The directory holding zarr.json.

 required

Returns:

Type Description
NodeMetadataV3

The loaded metadata.

Raises:

Type Description
FileNotFoundError

If root holds no zarr.json.
to_file 
to_file(root: PathLike) -> None

Write this metadata to its zarr.json.

The write merges into whatever content is already at the path. The file is not overwritten wholesale.

Parameters:

Name Type Description Default
root PathLike

The directory zarr.json is written under.

 required

GroupMetadataV3 

GroupMetadataV3(attributes: Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] = {}, zarr_format: Literal[3] = 3, node_type: Literal['group'] = 'group')

Bases: NodeMetadataV3, GroupMetadata

A Zarr v3 group's metadata: user attributes only.

Methods:

ArrayMetadataV3 

ArrayMetadataV3(attributes: Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] = {}, zarr_format: Literal[3] = 3, node_type: Literal['array'] = 'array')

Bases: NodeMetadataV3, ArrayMetadata

The array-specific fields shared by every Zarr v3 array.

See ArrayMetadata for the concrete class that adds the shape, data type, chunk grid, chunk-key encoding and codec-pipeline fields, and for its to_version method, which converts to v1 and v2.

Methods: