Skip to content

abczarr.metadata.v3.array

Zarr v3 array metadata.

Zarr v3 describes an array with three things: a chunk grid, which says how the array is divided into chunks, a chunk-key encoding, which says how a chunk's index maps to its key in the store, and an ordered pipeline of codecs applied to each chunk. ArrayMetadata.to_version converts to v2 or v1 by folding the codec pipeline back into v2's compressor, filters and byte-order-bearing dtype. That conversion requires a regular chunk grid.

Classes

ChunkGrid 

ChunkGrid(name: str | bytes = '', configuration: TypedConfig | JsonDict = TypedConfig(extra_items=FrozenDict({})), must_understand: Literal[True] = True)

Bases: MustUnderstandExtension

How an array is divided into chunks.

Use RegularChunkGrid for a fixed chunk shape, or RectilinearChunkGrid for chunks that vary in size along an axis.

Methods:

RegularChunkGridConfig 

RegularChunkGridConfig(chunk_shape: Iterable[Integral | integer | bool] = ())

Bases: TypedConfig

Holds the regular chunk grid's parameters: the shared chunk shape.

Attributes

chunk_shape instance-attribute 
chunk_shape: Shape

The shape of every chunk, one entry per dimension of the array.

Methods:

RegularChunkGrid 

RegularChunkGrid(configuration: RegularChunkGridConfig | JsonDict | Shape = RegularChunkGridConfig(chunk_shape=()), must_understand: Literal[True] = True, *, name: Literal['regular'] = 'regular')

Bases: ChunkGrid

A chunk grid where every chunk has the same shape.

configuration.chunk_shape gives that shape, one entry per dimension of the array. This is the only chunk grid Zarr v2 and v1 can represent, so it is required for conversion to those versions.

Attributes

name class-attribute instance-attribute 
name: Literal['regular'] = field(kw_only=True)

Always "regular".

configuration instance-attribute 
configuration: RegularChunkGridConfig

The chunk grid's parameters.

Methods:

RectilinearChunkGridConfig 

RectilinearChunkGridConfig(kind: Literal['inline'] = 'inline', chunk_shapes: Iterable[Integral | integer | bool] = ())

Bases: TypedConfig

Holds the rectilinear chunk grid's parameters: the per-axis chunk shapes.

Attributes

kind instance-attribute 
kind: Literal['inline']

Always "inline".

chunk_shapes instance-attribute 
chunk_shapes: Shape

The chunk shapes along the axis that varies.

Methods:

RectilinearChunkGrid 

RectilinearChunkGrid(configuration: RectilinearChunkGridConfig | JsonDict | Literal['inline'] = RectilinearChunkGridConfig(kind='inline', chunk_shapes=()), must_understand: Literal[True] = True, *, name: Literal['rectilinear'] = 'rectilinear')

Bases: ChunkGrid

A chunk grid whose chunk sizes vary along an axis.

Unlike RegularChunkGrid, which fixes one shape for every chunk, this grid's chunks need not all be the same size. It has no representation in Zarr v2 or v1.

Attributes

name class-attribute instance-attribute 
name: Literal['rectilinear'] = field(kw_only=True)

Always "rectilinear".

configuration instance-attribute 
configuration: RectilinearChunkGridConfig

The chunk grid's parameters.

Methods:

ChunkKeyEncodingConfig 

ChunkKeyEncodingConfig(*, extra_items: Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] = FrozenDict({}))

Bases: TypedConfig

This class is the base for a chunk-key encoding's own configuration parameters.

Methods:

CommonChunkKeyEncodingConfig 

CommonChunkKeyEncodingConfig(separator: Literal['.', '/'] = '/')

Bases: ChunkKeyEncodingConfig

Holds the parameter every chunk-key encoding shares: the separator joining a chunk index into its key.

Attributes

separator class-attribute instance-attribute 
separator: DimensionSeparator = '/'

The character joining a chunk index into its store key.

Methods:

ChunkKeyEncoding 

ChunkKeyEncoding(name: str | bytes = '', configuration: ChunkKeyEncodingConfig | JsonDict = ChunkKeyEncodingConfig(extra_items=FrozenDict({})), must_understand: Literal[True] = True)

Bases: MustUnderstandExtension

How a chunk's index maps to its key in the store.

Use the default encoding for v3's own scheme, or V2ChunkKeyEncoding to keep the key layout Zarr v2 uses. A v2 array converts to V2ChunkKeyEncoding, and a v3 array must use it to convert back to v2 or v1.

Attributes

name instance-attribute 
name: str

The name of the encoding, such as "default" or "v2".

configuration instance-attribute 
configuration: ChunkKeyEncodingConfig

The encoding's own parameters.

Methods:

DefaultChunkKeyEncodingConfig 

DefaultChunkKeyEncodingConfig(separator: Literal['.', '/'] = '/')

Bases: CommonChunkKeyEncodingConfig

Holds the default chunk-key encoding's parameters: the separator, defaulting to "/".

Methods:

DefaultChunkKeyEncoding 

DefaultChunkKeyEncoding(configuration: DefaultChunkKeyEncodingConfig | JsonDict | Literal['.', '/'] = DefaultChunkKeyEncodingConfig(separator='/'), must_understand: Literal[True] = True, *, name: Literal['default'] = 'default')

Bases: ChunkKeyEncoding

Zarr v3's own chunk-key layout.

A chunk index like (1, 2) becomes the key c/1/2, joined by configuration.separator (/ by default).

Attributes

name class-attribute instance-attribute 
name: Literal['default'] = field(kw_only=True)

Always "default".

configuration instance-attribute 
configuration: DefaultChunkKeyEncodingConfig

The encoding's parameters.

Methods:

V2ChunkKeyEncodingConfig 

V2ChunkKeyEncodingConfig(separator: Literal['.', '/'] = '.')

Bases: CommonChunkKeyEncodingConfig

Holds the v2 chunk-key encoding's parameters: the separator, defaulting to ".".

Methods:

V2ChunkKeyEncoding 

V2ChunkKeyEncoding(configuration: V2ChunkKeyEncodingConfig | JsonDict | Literal['.', '/'] = V2ChunkKeyEncodingConfig(separator='.'), must_understand: Literal[True] = True, *, name: Literal['v2'] = 'v2')

Bases: ChunkKeyEncoding

Zarr v2's chunk-key layout, usable from a v3 array.

A chunk index like (1, 2) becomes the key 1.2, joined by configuration.separator (. by default, v2's own default). A v3 array must use this encoding to convert to v2 or v1. A v2 array converts to this encoding, not to the default one.

Attributes

name class-attribute instance-attribute 
name: Literal['v2'] = field(kw_only=True)

Always "v2".

configuration instance-attribute 
configuration: V2ChunkKeyEncodingConfig

The encoding's parameters.

Methods:

ArrayMetadata 

ArrayMetadata(zarr_format: Literal[3] = 3, node_type: Literal['array'] = 'array', *, attributes: Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] = FrozenDict({}), shape: Iterable[Integral | integer | bool] = (), data_type: DType | JsonDict | str = Raw(name='r8', configuration=DTypeConfigImpl()), chunk_grid: ChunkGrid | JsonDict | str = RegularChunkGrid(name='regular', configuration=RegularChunkGridConfig(chunk_shape=())), chunk_key_encoding: ChunkKeyEncoding | JsonDict | str = DefaultChunkKeyEncoding(name='default', configuration=DefaultChunkKeyEncodingConfig(separator='/')), fill_value: Number | number | bool | tuple[Real | floating | bool, Real | floating | bool] | None = None, codecs: Iterable[Codec | JsonDict | str] = (), dimension_names: Iterable[str | bytes | None] | None = None, storage_transformers: Iterable[Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any]] = (), extra_items: Iterable[tuple[str | bytes, ExtraField | JsonDict | str]] | Mapping[str | bytes, ExtraField | JsonDict | str] = FrozenDict({}))

Bases: ArrayMetadataV3

A Zarr v3 array's metadata: shape, dtype, chunking, codecs.

Corresponds to the contents of zarr.json for an array node. codecs is an ordered pipeline: zero or more array-to-array codecs, exactly one array-to-bytes codec (a plain serializer, or a ShardingCodec that groups several chunks into one shard file), then zero or more bytes-to-bytes codecs such as a compressor.

Example

>>> from abczarr.metadata import v1
>>> meta = v1.ArrayMetadata.from_json({
...     "zarr_format": 1,
...     "shape": [10],
...     "chunks": [5],
...     "dtype": "<f8",
...     "compression": "zlib",
...     "compression_opts": {"level": 1},
...     "fill_value": 0,
...     "order": "C",
...     "attributes": {},
... })
>>> v3_meta = meta.to_version(3)
>>> v3_meta.chunk_grid.configuration.chunk_shape
(5,)
>>> [codec.name for codec in v3_meta.codecs]
['bytes', 'zlib']

Attributes

shape instance-attribute 
shape: Shape

The array's shape, one entry per dimension.

data_type instance-attribute 
data_type: DType

The array's Zarr v3 data type.

chunk_grid instance-attribute 
chunk_grid: ChunkGrid

How the array is divided into chunks.

chunk_key_encoding instance-attribute 
chunk_key_encoding: ChunkKeyEncoding

How a chunk's index maps to its key in the store.

fill_value class-attribute instance-attribute 
fill_value: _FillValue | None = field(eq=eq_safenan)

The value an unwritten element of the array reads as. A complex fill value is a two-element (real, imag) pair.

codecs instance-attribute 
codecs: tuple[Codec, ...]

The codec pipeline applied to each chunk: zero or more array-to-array codecs, exactly one array-to-bytes codec, then zero or more bytes-to-bytes codecs.

attributes instance-attribute 
attributes: FrozenJsonDict

The array's user-defined attributes.

dimension_names instance-attribute 
dimension_names: _AxisNames | None

An optional name for each dimension of the array. An entry may be None when that dimension is unnamed.

storage_transformers instance-attribute 
storage_transformers: tuple[FrozenJsonDict, ...]

Extra transformations a store applies to the array's chunks, beyond the codec pipeline.

Methods:

to_json 
to_json() -> JsonDict

Serialize this metadata to the contents of zarr.json.

dimension_names and storage_transformers are omitted from the document when they carry nothing, instead of written as null or an empty list, matching how the Zarr v3 specification represents an array with neither.

Returns:

Type Description
dict

The JSON-compatible representation of this metadata.
to_version 
to_version(version: ZarrVersion, policy: ConversionPolicy = 'lossy') -> ArrayMetadata

Convert this array's metadata to another Zarr version.

Requires a RegularChunkGrid -- v2 and v1 have no other kind. Sharding is unwrapped into its inner codecs (subject to policy, since the sharding structure itself is then lost), the codec pipeline is split back into v2's filters, byte order and compressor around its one array-to-bytes codec, and an order other than "C" or more than one bytes-to-bytes codec is likewise subject to 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 can't hold.

 'lossy'

Returns:

Type Description
ArrayMetadata

Equivalent metadata for version. Converting to 3 returns this object unchanged.

Raises:

Type Description
ValueError

If version is not 1, 2 or 3, or if chunk_grid is not a RegularChunkGrid.
UnsupportedConversion

If policy is "strict" and a field cannot be represented in version.
required_features 
required_features() -> FrozenSet[str]

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

Returns:

Type Description
frozenset of str

One key each for the chunk grid, the chunk-key encoding and the data type, plus one per codec in codecs, including the codecs nested inside a ShardingCodec, and one per named storage transformer.