Skip to content

zarr_metadata.v3.codec

zarr_metadata.v3.codec

Zarr v3 codec spec types.

Each codec defined by the spec or by zarr-extensions has its own submodule (blosc, bytes, cast_value, crc32c, gzip, scale_offset, sharding_indexed, transpose, vlen_bytes, vlen_utf8, zstd). Import a codec's types and its definition from its submodule, or from this package, which re-exports every name its submodules export: <X>CodecMetadata, the canonical type for the codec's permitted JSON shapes (object form plus, where the spec allows, a bare-string short-hand form), <X>CodecObject, <X>_CODEC, and, for a codec that has a configuration, <X>CodecConfiguration.

For the JSON of any codec entry (one of the entries in array metadata's codecs), import ZarrV3MetadataFieldJSON from zarr_metadata.v3. A configuration member that holds a codec, such as sharding's inner pipelines, is annotated ZarrV3CodecField from zarr_metadata.v3.definition instead, so that the reader reads it as a codec.

Each codec's pipeline position (array -> array, array -> bytes, bytes -> bytes) is its definition's kind, in zarr_metadata.v3.definition.

See https://zarr-specs.readthedocs.io/en/latest/v3/codecs/index.html

zarr_metadata.v3.codec.blosc

Blosc codec types.

See https://zarr-specs.readthedocs.io/en/latest/v3/codecs/blosc/index.html

BLOSC_CNAME module-attribute 

BLOSC_CNAME: Final = (
    "lz4",
    "lz4hc",
    "blosclz",
    "snappy",
    "zlib",
    "zstd",
)

Tuple of permitted values for the cname field of the blosc codec.

BLOSC_CODEC module-attribute 

BLOSC_CODEC: Final = CodecDefinition(
    name=BLOSC_CODEC_NAME,
    configuration=BloscCodecConfiguration,
    kind="bytes_bytes",
    size="dynamic",
    rules=_rules,
    canonical=_canonical,
)

The blosc codec.

BLOSC_CODEC_NAME module-attribute 

BLOSC_CODEC_NAME: Final = 'blosc'

The name field value of the blosc codec.

BLOSC_NO_SHUFFLE module-attribute 

BLOSC_NO_SHUFFLE: Final = 'noshuffle'

The shuffle value under which typesize carries no information.

The spec requires typesize "unless shuffle is "noshuffle", in which case the value is ignored", so this is the one value that changes whether another member is required.

BLOSC_SHUFFLE module-attribute 

BLOSC_SHUFFLE: Final = (
    "noshuffle",
    "shuffle",
    "bitshuffle",
)

Tuple of permitted values for the shuffle field of the blosc codec.

BloscCName module-attribute 

BloscCName = Literal[
    "lz4", "lz4hc", "blosclz", "snappy", "zlib", "zstd"
]

Literal type of blosc compressor identifiers.

BloscCodecMetadata module-attribute 

BloscCodecMetadata = BloscCodecObject

Permitted JSON shape for blosc codec metadata.

The configuration has multiple required keys (cname, clevel, shuffle, blocksize), so only the object form is valid; the short-hand-name form is not permitted by the spec for this codec. https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/codecs/blosc/index.rst#L57-L98 (configuration parameters) https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1562-L1564 (short-hand names only "if no configuration metadata is required")

BloscCodecName module-attribute 

BloscCodecName = Literal['blosc']

Literal type of the name field of the blosc codec.

BloscShuffle module-attribute 

BloscShuffle = Literal["noshuffle", "shuffle", "bitshuffle"]

Literal type of blosc shuffle mode names.

__all__ module-attribute 

__all__ = [
    "BLOSC_CNAME",
    "BLOSC_CODEC",
    "BLOSC_CODEC_NAME",
    "BLOSC_NO_SHUFFLE",
    "BLOSC_SHUFFLE",
    "BloscCName",
    "BloscCodecConfiguration",
    "BloscCodecMetadata",
    "BloscCodecName",
    "BloscCodecObject",
    "BloscShuffle",
]

BloscCodecConfiguration

Bases: TypedDict

Configuration for the Zarr v3 blosc codec.

Source code in src/zarr_metadata/v3/codec/blosc.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
class BloscCodecConfiguration(TypedDict, closed=True):
    """Configuration for the Zarr v3 `blosc` codec."""

    cname: BloscCName
    """The compressor blosc applies to each block, one of `BLOSC_CNAME`."""
    clevel: Annotated[int, Interval(ge=0, le=9)]
    """The compression level, an integer from 0 to 9.

    0 turns compression off; 1 is the fastest and compresses least, 9 the
    slowest and compresses most.
    """
    shuffle: BloscShuffle
    """The shuffling applied before compression.

    `"noshuffle"` for none, `"shuffle"` for byte-wise, `"bitshuffle"` for
    bit-wise.
    """
    blocksize: Annotated[int, Ge(0)]
    """The size in bytes of the blocks the buffer is divided into before compression.

    At least 0; 0 lets blosc choose the size.
    """
    typesize: NotRequired[int]
    """The stride in bytes over which shuffling is performed.

    Required, and at least 1, unless `shuffle` is `"noshuffle"`, under
    which the spec ignores it and `canonicalize` drops it.
    """

blocksize instance-attribute 

blocksize: Annotated[int, Ge(0)]

The size in bytes of the blocks the buffer is divided into before compression.

At least 0; 0 lets blosc choose the size.

clevel instance-attribute 

clevel: Annotated[int, Interval(ge=0, le=9)]

The compression level, an integer from 0 to 9.

0 turns compression off; 1 is the fastest and compresses least, 9 the slowest and compresses most.

cname instance-attribute 

cname: BloscCName

The compressor blosc applies to each block, one of BLOSC_CNAME.

shuffle instance-attribute 

shuffle: BloscShuffle

The shuffling applied before compression.

"noshuffle" for none, "shuffle" for byte-wise, "bitshuffle" for bit-wise.

typesize instance-attribute 

typesize: NotRequired[int]

The stride in bytes over which shuffling is performed.

Required, and at least 1, unless shuffle is "noshuffle", under which the spec ignores it and canonicalize drops it.

BloscCodecObject

Bases: TypedDict

blosc codec metadata in object form.

Source code in src/zarr_metadata/v3/codec/blosc.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
79
class BloscCodecObject(TypedDict, closed=True):
    """`blosc` codec metadata in object form."""

    name: BloscCodecName
    """The codec's name, `"blosc"`."""
    configuration: BloscCodecConfiguration
    """The codec's parameters."""
    must_understand: NotRequired[bool]
    """Whether a reader that does not recognize this codec must refuse the document.

    Absent means `true`. The spec permits `false` for a codec
    (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581),
    though `resolve` reports a `false` as a problem at every extension point.
    """

configuration instance-attribute 

configuration: BloscCodecConfiguration

The codec's parameters.

must_understand instance-attribute 

must_understand: NotRequired[bool]

Whether a reader that does not recognize this codec must refuse the document.

Absent means true. The spec permits false for a codec (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581), though resolve reports a false as a problem at every extension point.

name instance-attribute 

name: BloscCodecName

The codec's name, "blosc".

zarr_metadata.v3.codec.bytes

Bytes codec types.

See https://zarr-specs.readthedocs.io/en/latest/v3/codecs/bytes/index.html

BYTES_CODEC module-attribute 

BYTES_CODEC: Final = CodecDefinition(
    name=BYTES_CODEC_NAME,
    configuration=BytesCodecConfiguration,
    kind="array_bytes",
    size="static",
    chunk_rules=_chunk_rules,
)

The bytes codec.

BYTES_CODEC_NAME module-attribute 

BYTES_CODEC_NAME: Final = 'bytes'

The name field value of the bytes codec.

BytesCodecMetadata module-attribute 

BytesCodecMetadata = BytesCodecObject | BytesCodecName

Permitted JSON shapes for bytes codec metadata.

The configuration has no required keys (endian is conditionally required at runtime based on data type), so the spec's short-hand-name form is permitted in addition to the object form, and the object form may itself omit configuration entirely. https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/codecs/bytes/index.rst#L64-L69 ("endian: Required for data types for which endianness is applicable") https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1562-L1564

BytesCodecName module-attribute 

BytesCodecName = Literal['bytes']

Literal type of the name field of the bytes codec.

ENDIANNESS module-attribute 

ENDIANNESS: Final = ('little', 'big')

Tuple of permitted values for the endian field of the bytes codec.

Endianness module-attribute 

Endianness = Literal['little', 'big']

Literal type of byte order of multi-byte numeric data.

__all__ module-attribute 

__all__ = [
    "BYTES_CODEC",
    "BYTES_CODEC_NAME",
    "ENDIANNESS",
    "BytesCodecConfiguration",
    "BytesCodecMetadata",
    "BytesCodecName",
    "BytesCodecObject",
    "Endianness",
]

BytesCodecConfiguration

Bases: TypedDict

Configuration for the Zarr v3 bytes codec.

The endian field is required for multi-byte data types.

Source code in src/zarr_metadata/v3/codec/bytes.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
class BytesCodecConfiguration(TypedDict, closed=True):
    """
    Configuration for the Zarr v3 `bytes` codec.

    The `endian` field is required for multi-byte data types.
    """

    endian: NotRequired[Endianness]
    """The byte order in which each value is written.

    Required when the values of the data type the codec is handed take more
    than one byte; a single-byte type such as `uint8` or `bool` does not
    depend on it.
    """

endian instance-attribute 

endian: NotRequired[Endianness]

The byte order in which each value is written.

Required when the values of the data type the codec is handed take more than one byte; a single-byte type such as uint8 or bool does not depend on it.

BytesCodecObject

Bases: TypedDict

bytes codec metadata in object form.

configuration is itself optional — when no configuration fields are set, the entire configuration key may be omitted. This matches the bare-string short-hand form (BytesCodecName) at the canonical data level; both encodings describe a bytes codec with default settings.

Source code in src/zarr_metadata/v3/codec/bytes.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
class BytesCodecObject(TypedDict, closed=True):
    """`bytes` codec metadata in object form.

    `configuration` is itself optional — when no configuration fields are
    set, the entire `configuration` key may be omitted. This matches the
    bare-string short-hand form (`BytesCodecName`) at the canonical data
    level; both encodings describe a `bytes` codec with default settings.
    """

    name: BytesCodecName
    """The codec's name, `"bytes"`."""
    configuration: NotRequired[BytesCodecConfiguration]
    """The codec's parameters.

    May be absent when no parameter is set.
    """
    must_understand: NotRequired[bool]
    """Whether a reader that does not recognize this codec must refuse the document.

    Absent means `true`. The spec permits `false` for a codec
    (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581),
    though `resolve` reports a `false` as a problem at every extension point.
    """

configuration instance-attribute 

configuration: NotRequired[BytesCodecConfiguration]

The codec's parameters.

May be absent when no parameter is set.

must_understand instance-attribute 

must_understand: NotRequired[bool]

Whether a reader that does not recognize this codec must refuse the document.

Absent means true. The spec permits false for a codec (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581), though resolve reports a false as a problem at every extension point.

name instance-attribute 

name: BytesCodecName

The codec's name, "bytes".

zarr_metadata.v3.codec.cast_value

Cast-value codec types.

See https://github.com/zarr-developers/zarr-extensions/blob/4da7b37a84f76e660902f6d3de3eaef0e0febae6/codecs/cast_value/README.md

CAST_OUT_OF_RANGE_MODE module-attribute 

CAST_OUT_OF_RANGE_MODE: Final = ('clamp', 'wrap')

Tuple of permitted values for the out_of_range field of the cast_value codec.

CAST_ROUNDING_MODE module-attribute 

CAST_ROUNDING_MODE: Final = (
    "nearest-even",
    "towards-zero",
    "towards-positive",
    "towards-negative",
    "nearest-away",
)

Tuple of permitted values for the rounding field of the cast_value codec.

CAST_VALUE_CODEC module-attribute 

CAST_VALUE_CODEC: Final = CodecDefinition(
    name=CAST_VALUE_CODEC_NAME,
    configuration=CastValueCodecConfiguration,
    kind="array_array",
    size="static",
    rules=_rules,
    chunk_rules=_chunk_rules,
    transition=_transition,
)

The cast_value codec.

The target data type is a nested field. It is read in the same scope as the codec, and it becomes the data type of the output chunk.

CAST_VALUE_CODEC_NAME module-attribute 

CAST_VALUE_CODEC_NAME: Final = 'cast_value'

The name field value of the cast_value codec.

CastOutOfRangeMode module-attribute 

CastOutOfRangeMode = Literal['clamp', 'wrap']

Literal type of permitted values for the out_of_range configuration field.

If absent, out-of-range values are an encoding/decoding error.

CastRoundingMode module-attribute 

CastRoundingMode = Literal[
    "nearest-even",
    "towards-zero",
    "towards-positive",
    "towards-negative",
    "nearest-away",
]

Literal type of permitted values for the rounding configuration field.

Defaults to "nearest-even" if absent.

CastValueCodecMetadata module-attribute 

CastValueCodecMetadata = CastValueCodecObject

Permitted JSON shape for cast_value codec metadata.

configuration.data_type is required, so only the object form is valid; the short-hand-name form is not permitted by the spec for this codec. https://github.com/zarr-developers/zarr-extensions/blob/4da7b37a84f76e660902f6d3de3eaef0e0febae6/codecs/cast_value/README.md#L33-L36 and #L46-L48 (required fields) https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1562-L1564 (short-hand names only "if no configuration metadata is required")

CastValueCodecName module-attribute 

CastValueCodecName = Literal['cast_value']

Literal type of the name field of the cast_value codec.

ScalarMapEntry module-attribute 

ScalarMapEntry = tuple[JSONValue, JSONValue]

A single [input, output] mapping in a scalar_map direction.

Each scalar is encoded as a fill value of its data type. For a float, the infinities are "Infinity" and "-Infinity", as the core encoding writes them. The codec's own example writes "+Infinity" instead.

__all__ module-attribute 

__all__ = [
    "CAST_OUT_OF_RANGE_MODE",
    "CAST_ROUNDING_MODE",
    "CAST_VALUE_CODEC",
    "CAST_VALUE_CODEC_NAME",
    "CastOutOfRangeMode",
    "CastRoundingMode",
    "CastValueCodecConfiguration",
    "CastValueCodecMetadata",
    "CastValueCodecName",
    "CastValueCodecObject",
    "ScalarMap",
    "ScalarMapEntry",
]

CastValueCodecConfiguration

Bases: TypedDict

Configuration for the Zarr v3 cast_value codec.

data_type is the target data type that input values are cast to. It is the same shape as the top-level array data_type field: either a bare-string primitive name or a {name, configuration} envelope.

Source code in src/zarr_metadata/v3/codec/cast_value.py 
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
class CastValueCodecConfiguration(TypedDict, closed=True):
    """
    Configuration for the Zarr v3 `cast_value` codec.

    `data_type` is the target data type that input values are cast to. It
    is the same shape as the top-level array `data_type` field: either a
    bare-string primitive name or a `{name, configuration}` envelope.
    """

    data_type: ZarrV3DataTypeField
    """The data type values are cast to when encoding, and the one the decoder is handed.

    The codec is defined only for data types that model real numbers, the
    integer and floating-point types: a boolean, raw-bits, string, bytes,
    struct or complex type is refused, here and as the data type the codec
    is handed.
    """
    rounding: NotRequired[CastRoundingMode]
    """How a value `data_type` cannot represent exactly is rounded.

    Absent means `"nearest-even"`.
    """
    out_of_range: NotRequired[CastOutOfRangeMode]
    """How a value outside the range of `data_type` is brought into it, after rounding.

    `"clamp"` takes the nearest bound; `"wrap"` takes the value congruent
    modulo 2^N, N being the width in bits of `data_type`, and is permitted
    only when `data_type` is an integral type. Absent means an out-of-range
    value is an encoding or decoding error.
    """
    scalar_map: NotRequired[ScalarMap]
    """Scalars mapped explicitly, in place of `rounding` and `out_of_range`."""

data_type instance-attribute 

data_type: ZarrV3DataTypeField

The data type values are cast to when encoding, and the one the decoder is handed.

The codec is defined only for data types that model real numbers, the integer and floating-point types: a boolean, raw-bits, string, bytes, struct or complex type is refused, here and as the data type the codec is handed.

out_of_range instance-attribute 

out_of_range: NotRequired[CastOutOfRangeMode]

How a value outside the range of data_type is brought into it, after rounding.

"clamp" takes the nearest bound; "wrap" takes the value congruent modulo 2^N, N being the width in bits of data_type, and is permitted only when data_type is an integral type. Absent means an out-of-range value is an encoding or decoding error.

rounding instance-attribute 

rounding: NotRequired[CastRoundingMode]

How a value data_type cannot represent exactly is rounded.

Absent means "nearest-even".

scalar_map instance-attribute 

scalar_map: NotRequired[ScalarMap]

Scalars mapped explicitly, in place of rounding and out_of_range.

CastValueCodecObject

Bases: TypedDict

cast_value codec metadata in object form.

Source code in src/zarr_metadata/v3/codec/cast_value.py 
122
123
124
125
126
127
128
129
130
131
132
133
134
135
class CastValueCodecObject(TypedDict, closed=True):
    """`cast_value` codec metadata in object form."""

    name: CastValueCodecName
    """The codec's name, `"cast_value"`."""
    configuration: CastValueCodecConfiguration
    """The codec's parameters."""
    must_understand: NotRequired[bool]
    """Whether a reader that does not recognize this codec must refuse the document.

    Absent means `true`. The spec permits `false` for a codec
    (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581),
    though `resolve` reports a `false` as a problem at every extension point.
    """

configuration instance-attribute 

configuration: CastValueCodecConfiguration

The codec's parameters.

must_understand instance-attribute 

must_understand: NotRequired[bool]

Whether a reader that does not recognize this codec must refuse the document.

Absent means true. The spec permits false for a codec (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581), though resolve reports a false as a problem at every extension point.

name instance-attribute 

name: CastValueCodecName

The codec's name, "cast_value".

ScalarMap

Bases: TypedDict

Optional encode/decode scalar overrides for the cast_value codec.

Source code in src/zarr_metadata/v3/codec/cast_value.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
class ScalarMap(TypedDict, closed=True):
    """Optional encode/decode scalar overrides for the cast_value codec."""

    encode: NotRequired[tuple[ScalarMapEntry, ...]]
    """The `[input, output]` pairs applied when encoding: input in the array's data type, output in `data_type`.

    Each scalar is written in its data type's fill value encoding. Where an
    input repeats, the first pair applies.
    """
    decode: NotRequired[tuple[ScalarMapEntry, ...]]
    """The `[input, output]` pairs applied when decoding: input in `data_type`, output in the array's data type.

    Each scalar is written in its data type's fill value encoding. Where an
    input repeats, the first pair applies.
    """

decode instance-attribute 

decode: NotRequired[tuple[ScalarMapEntry, ...]]

The [input, output] pairs applied when decoding: input in data_type, output in the array's data type.

Each scalar is written in its data type's fill value encoding. Where an input repeats, the first pair applies.

encode instance-attribute 

encode: NotRequired[tuple[ScalarMapEntry, ...]]

The [input, output] pairs applied when encoding: input in the array's data type, output in data_type.

Each scalar is written in its data type's fill value encoding. Where an input repeats, the first pair applies.

zarr_metadata.v3.codec.crc32c

CRC32C codec types.

See https://zarr-specs.readthedocs.io/en/latest/v3/codecs/crc32c/index.html

The CRC32C codec has no configuration fields, so the configuration key is absent from the metadata.

CRC32C_CODEC module-attribute 

CRC32C_CODEC: Final = CodecDefinition(
    name=CRC32C_CODEC_NAME,
    configuration=EmptyConfiguration,
    kind="bytes_bytes",
    size="static",
)

The crc32c codec. A checksum has no configuration.

CRC32C_CODEC_NAME module-attribute 

CRC32C_CODEC_NAME: Final = 'crc32c'

The name field value of the crc32c codec.

Crc32cCodecMetadata module-attribute 

Crc32cCodecMetadata = Crc32cCodecObject | Crc32cCodecName

Permitted JSON shapes for crc32c codec metadata.

The spec's Extension definition allows extensions with no required configuration to be encoded as a bare short-hand name. CRC32C has no configuration, so both forms are valid. https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1562-L1564

Crc32cCodecName module-attribute 

Crc32cCodecName = Literal['crc32c']

Literal type of the name field of the crc32c codec.

__all__ module-attribute 

__all__ = [
    "CRC32C_CODEC",
    "CRC32C_CODEC_NAME",
    "Crc32cCodecMetadata",
    "Crc32cCodecName",
    "Crc32cCodecObject",
]

Crc32cCodecObject

Bases: TypedDict

crc32c codec metadata in object form.

Per spec the codec has no configuration fields. configuration is optional and, if present, should be an empty mapping. https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/codecs/crc32c/index.rst#L63-L66

Source code in src/zarr_metadata/v3/codec/crc32c.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
class Crc32cCodecObject(TypedDict, closed=True):
    """`crc32c` codec metadata in object form.

    Per spec the codec has no configuration fields. `configuration` is
    optional and, if present, should be an empty mapping.
      https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/codecs/crc32c/index.rst#L63-L66
    """

    name: Crc32cCodecName
    """The codec's name, `"crc32c"`."""
    configuration: NotRequired[EmptyConfiguration]
    """The codec's parameters, of which there are none.

    Absent, or an empty mapping.
    """
    must_understand: NotRequired[bool]
    """Whether a reader that does not recognize this codec must refuse the document.

    Absent means `true`. The spec permits `false` for a codec
    (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581),
    though `resolve` reports a `false` as a problem at every extension point.
    """

configuration instance-attribute 

configuration: NotRequired[EmptyConfiguration]

The codec's parameters, of which there are none.

Absent, or an empty mapping.

must_understand instance-attribute 

must_understand: NotRequired[bool]

Whether a reader that does not recognize this codec must refuse the document.

Absent means true. The spec permits false for a codec (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581), though resolve reports a false as a problem at every extension point.

name instance-attribute 

name: Crc32cCodecName

The codec's name, "crc32c".

zarr_metadata.v3.codec.gzip

Gzip codec types.

See https://zarr-specs.readthedocs.io/en/latest/v3/codecs/gzip/index.html

GZIP_CODEC module-attribute 

GZIP_CODEC: Final = CodecDefinition(
    name=GZIP_CODEC_NAME,
    configuration=GzipCodecConfiguration,
    kind="bytes_bytes",
    size="dynamic",
)

The gzip codec.

GZIP_CODEC_NAME module-attribute 

GZIP_CODEC_NAME: Final = 'gzip'

The name field value of the gzip codec.

GzipCodecMetadata module-attribute 

GzipCodecMetadata = GzipCodecObject

Permitted JSON shape for gzip codec metadata.

configuration.level is required (it determines the codec's output bytes and is therefore part of the metadata's reproducibility contract), so only the object form is valid; the short-hand-name form is not permitted.

GzipCodecName module-attribute 

GzipCodecName = Literal['gzip']

Literal type of the name field of the gzip codec.

__all__ module-attribute 

__all__ = [
    "GZIP_CODEC",
    "GZIP_CODEC_NAME",
    "GzipCodecConfiguration",
    "GzipCodecMetadata",
    "GzipCodecName",
    "GzipCodecObject",
]

GzipCodecConfiguration

Bases: TypedDict

Configuration for the Zarr v3 gzip codec.

level is an integer in the range 0-9; 0 disables compression and 9 is slowest with the best compression ratio. The codec's compressed output depends on level, so metadata that omits it cannot reproducibly identify the chunk bytes produced by a writer — level is required for the metadata to fulfill its reproducibility role, even though the spec text does not mark it required with RFC 2119 keywords. https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/codecs/gzip/index.rst#L57-L66

Source code in src/zarr_metadata/v3/codec/gzip.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
class GzipCodecConfiguration(TypedDict, closed=True):
    """
    Configuration for the Zarr v3 `gzip` codec.

    `level` is an integer in the range 0-9; 0 disables compression and 9
    is slowest with the best compression ratio. The codec's compressed
    output depends on `level`, so metadata that omits it cannot
    reproducibly identify the chunk bytes produced by a writer — `level`
    is required for the metadata to fulfill its reproducibility role,
    even though the spec text does not mark it required with RFC 2119
    keywords.
      https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/codecs/gzip/index.rst#L57-L66
    """

    level: Annotated[int, Interval(ge=0, le=9)]
    """The compression level, an integer from 0 to 9.

    0 turns compression off; 1 is the fastest and compresses least, 9 the
    slowest and compresses most.
    """

level instance-attribute 

level: Annotated[int, Interval(ge=0, le=9)]

The compression level, an integer from 0 to 9.

0 turns compression off; 1 is the fastest and compresses least, 9 the slowest and compresses most.

GzipCodecObject

Bases: TypedDict

gzip codec metadata in object form.

Source code in src/zarr_metadata/v3/codec/gzip.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
class GzipCodecObject(TypedDict, closed=True):
    """`gzip` codec metadata in object form."""

    name: GzipCodecName
    """The codec's name, `"gzip"`."""
    configuration: GzipCodecConfiguration
    """The codec's parameters."""
    must_understand: NotRequired[bool]
    """Whether a reader that does not recognize this codec must refuse the document.

    Absent means `true`. The spec permits `false` for a codec
    (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581),
    though `resolve` reports a `false` as a problem at every extension point.
    """

configuration instance-attribute 

configuration: GzipCodecConfiguration

The codec's parameters.

must_understand instance-attribute 

must_understand: NotRequired[bool]

Whether a reader that does not recognize this codec must refuse the document.

Absent means true. The spec permits false for a codec (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581), though resolve reports a false as a problem at every extension point.

name instance-attribute 

name: GzipCodecName

The codec's name, "gzip".

zarr_metadata.v3.codec.scale_offset

Scale-offset codec types.

See https://github.com/zarr-developers/zarr-extensions/blob/4da7b37a84f76e660902f6d3de3eaef0e0febae6/codecs/scale_offset/README.md

SCALE_OFFSET_CODEC module-attribute 

SCALE_OFFSET_CODEC: Final = CodecDefinition(
    name=SCALE_OFFSET_CODEC_NAME,
    configuration=ScaleOffsetCodecConfiguration,
    kind="array_array",
    size="static",
    rules=_rules,
    chunk_rules=_chunk_rules,
    transition=_transition,
)

The scale_offset codec.

SCALE_OFFSET_CODEC_NAME module-attribute 

SCALE_OFFSET_CODEC_NAME: Final = 'scale_offset'

The name field value of the scale_offset codec.

ScaleOffsetCodecMetadata module-attribute 

ScaleOffsetCodecMetadata = (
    ScaleOffsetCodecObject | ScaleOffsetCodecName
)

Permitted JSON shapes for scale_offset codec metadata.

The configuration has no required keys (both offset and scale are optional, and the configuration itself is optional), so the short-hand-name form is permitted in addition to the object form.

ScaleOffsetCodecName module-attribute 

ScaleOffsetCodecName = Literal['scale_offset']

Literal type of the name field of the scale_offset codec.

__all__ module-attribute 

__all__ = [
    "SCALE_OFFSET_CODEC",
    "SCALE_OFFSET_CODEC_NAME",
    "ScaleOffsetCodecConfiguration",
    "ScaleOffsetCodecMetadata",
    "ScaleOffsetCodecName",
    "ScaleOffsetCodecObject",
]

ScaleOffsetCodecConfiguration

Bases: TypedDict

Configuration for the Zarr v3 scale_offset codec.

Both fields are optional. A missing offset is the additive identity (e.g. 0 for numeric types); a missing scale is the multiplicative identity (e.g. 1). Each scalar is encoded as a fill value of the input data type of the codec: an integer for an integer type, and for a float type a number, "NaN", "Infinity", "-Infinity" or a hex string.

Source code in src/zarr_metadata/v3/codec/scale_offset.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
class ScaleOffsetCodecConfiguration(TypedDict, closed=True):
    """
    Configuration for the Zarr v3 `scale_offset` codec.

    Both fields are optional. A missing `offset` is the additive identity
    (e.g. 0 for numeric types); a missing `scale` is the multiplicative
    identity (e.g. 1). Each scalar is encoded as a fill value of the input
    data type of the codec: an integer for an integer type, and for a
    float type a number, `"NaN"`, `"Infinity"`, `"-Infinity"` or a hex
    string.
    """

    offset: NotRequired[JSONValue]
    """The quantity subtracted from each value when encoding.

    Absent means the additive identity, e.g. 0. A fill value of the data
    type the codec is handed.
    """
    scale: NotRequired[JSONValue]
    """The quantity each value is multiplied by when encoding, after `offset` is subtracted.

    Absent means the multiplicative identity, e.g. 1. A fill value of the
    data type the codec is handed.
    """

offset instance-attribute 

offset: NotRequired[JSONValue]

The quantity subtracted from each value when encoding.

Absent means the additive identity, e.g. 0. A fill value of the data type the codec is handed.

scale instance-attribute 

scale: NotRequired[JSONValue]

The quantity each value is multiplied by when encoding, after offset is subtracted.

Absent means the multiplicative identity, e.g. 1. A fill value of the data type the codec is handed.

ScaleOffsetCodecObject

Bases: TypedDict

scale_offset codec metadata in object form.

configuration is itself optional per spec — when both offset and scale are at their identity defaults, the codec is a no-op and the entire configuration field may be omitted. https://github.com/zarr-developers/zarr-extensions/blob/4da7b37a84f76e660902f6d3de3eaef0e0febae6/codecs/scale_offset/README.md#L18 and #L35

Source code in src/zarr_metadata/v3/codec/scale_offset.py 
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
class ScaleOffsetCodecObject(TypedDict, closed=True):
    """`scale_offset` codec metadata in object form.

    `configuration` is itself optional per spec — when both `offset` and
    `scale` are at their identity defaults, the codec is a no-op and the
    entire `configuration` field may be omitted.
      https://github.com/zarr-developers/zarr-extensions/blob/4da7b37a84f76e660902f6d3de3eaef0e0febae6/codecs/scale_offset/README.md#L18 and #L35
    """

    name: ScaleOffsetCodecName
    """The codec's name, `"scale_offset"`."""
    configuration: NotRequired[ScaleOffsetCodecConfiguration]
    """The codec's parameters.

    May be absent when neither `offset` nor `scale` is set, which makes the
    codec a no-op.
    """
    must_understand: NotRequired[bool]
    """Whether a reader that does not recognize this codec must refuse the document.

    Absent means `true`. The spec permits `false` for a codec
    (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581),
    though `resolve` reports a `false` as a problem at every extension point.
    """

configuration instance-attribute 

configuration: NotRequired[ScaleOffsetCodecConfiguration]

The codec's parameters.

May be absent when neither offset nor scale is set, which makes the codec a no-op.

must_understand instance-attribute 

must_understand: NotRequired[bool]

Whether a reader that does not recognize this codec must refuse the document.

Absent means true. The spec permits false for a codec (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581), though resolve reports a false as a problem at every extension point.

name instance-attribute 

name: ScaleOffsetCodecName

The codec's name, "scale_offset".

zarr_metadata.v3.codec.sharding_indexed

Sharding-indexed codec types.

See https://zarr-specs.readthedocs.io/en/latest/v3/codecs/sharding-indexed/index.html

SHARDING_INDEXED_CODEC module-attribute 

SHARDING_INDEXED_CODEC: Final = CodecDefinition(
    name=SHARDING_INDEXED_CODEC_NAME,
    configuration=ShardingIndexedCodecConfiguration,
    canonical=_canonical,
    kind="array_bytes",
    size="dynamic",
    chunk_rules=_chunk_rules,
    pipelines=_pipelines,
)

The sharding_indexed codec.

Its two pipelines are nested fields. Each codec in them is read in the same scope as the shard, and each pipeline is read as a pipeline: the inner codecs receive the inner chunks, and the index codecs receive the shard index.

SHARDING_INDEXED_CODEC_NAME module-attribute 

SHARDING_INDEXED_CODEC_NAME: Final = 'sharding_indexed'

The name field value of the sharding_indexed codec.

SHARDING_INDEX_LOCATION module-attribute 

SHARDING_INDEX_LOCATION: Final = ('start', 'end')

Tuple of permitted values for the index_location field of the sharding_indexed codec.

ShardingIndexLocation module-attribute 

ShardingIndexLocation = Literal['start', 'end']

Literal type of the position of the shard index within the encoded shard.

ShardingIndexedCodecMetadata module-attribute 

ShardingIndexedCodecMetadata = ShardingIndexedCodecObject

Permitted JSON shape for sharding_indexed codec metadata.

The configuration has multiple required keys (chunk_shape, codecs, index_codecs), so only the object form is valid; the short-hand-name form is not permitted by the spec for this codec. https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/codecs/sharding-indexed/index.rst#L129-L138 (chunk_shape) https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/codecs/sharding-indexed/index.rst#L141-L155 (codecs and index_codecs, the members the spec marks required) https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1562-L1564 (short-hand names only "if no configuration metadata is required")

ShardingIndexedCodecName module-attribute 

ShardingIndexedCodecName = Literal['sharding_indexed']

Literal type of the name field of the sharding_indexed codec.

__all__ module-attribute 

__all__ = [
    "SHARDING_INDEXED_CODEC",
    "SHARDING_INDEXED_CODEC_NAME",
    "SHARDING_INDEX_LOCATION",
    "ShardingIndexLocation",
    "ShardingIndexedCodecConfiguration",
    "ShardingIndexedCodecMetadata",
    "ShardingIndexedCodecName",
    "ShardingIndexedCodecObject",
]

ShardingIndexedCodecConfiguration

Bases: TypedDict

Configuration for the Zarr v3 sharding_indexed codec.

chunk_shape is the shape of inner chunks along each dimension; it must evenly divide the shard shape.

codecs is the codec pipeline applied to each inner chunk; exactly one array-to-bytes codec is required.

index_codecs is the codec pipeline applied to the shard index. It may contain only codecs of static size, because a reader locates the index by a size that it knows before reading it. A compressor in this pipeline is therefore rejected. https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/codecs/sharding-indexed/index.rst#L147-L155

index_location defaults to "end" per the spec. https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/codecs/sharding-indexed/index.rst#L157-L161

Source code in src/zarr_metadata/v3/codec/sharding_indexed.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
class ShardingIndexedCodecConfiguration(TypedDict, closed=True):
    """
    Configuration for the Zarr v3 `sharding_indexed` codec.

    `chunk_shape` is the shape of inner chunks along each dimension;
    it must evenly divide the shard shape.

    `codecs` is the codec pipeline applied to each inner chunk; exactly
    one array-to-bytes codec is required.

    `index_codecs` is the codec pipeline applied to the shard index. It may
    contain only codecs of static size, because a reader locates the index
    by a size that it knows before reading it. A compressor in this
    pipeline is therefore rejected.
      https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/codecs/sharding-indexed/index.rst#L147-L155

    `index_location` defaults to `"end"` per the spec.
      https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/codecs/sharding-indexed/index.rst#L157-L161
    """

    chunk_shape: tuple[Annotated[int, Ge(1)], ...]
    """The shape of the inner chunks a shard is divided into.

    One length, at least 1, per axis of the shard the codec is handed, each
    dividing the shard's length along that axis.
    """
    codecs: tuple[ZarrV3CodecField, ...]
    """The codec pipeline that encodes each inner chunk.

    Like an array's `codecs`, it holds exactly one array -> bytes codec.
    """
    index_codecs: tuple[ZarrV3StaticCodecField, ...]
    """The codec pipeline that encodes the shard index.

    It holds exactly one array -> bytes codec, and only codecs whose output
    size is fixed by the size of their input, so no compressor. The spec
    recommends a little-endian `bytes` codec followed by `crc32c`.
    """
    index_location: NotRequired[ShardingIndexLocation]
    """Whether the shard index sits at the `"start"` or the `"end"` of the encoded shard.

    Absent means `"end"`.
    """

chunk_shape instance-attribute 

chunk_shape: tuple[Annotated[int, Ge(1)], ...]

The shape of the inner chunks a shard is divided into.

One length, at least 1, per axis of the shard the codec is handed, each dividing the shard's length along that axis.

codecs instance-attribute 

codecs: tuple[ZarrV3CodecField, ...]

The codec pipeline that encodes each inner chunk.

Like an array's codecs, it holds exactly one array -> bytes codec.

index_codecs instance-attribute 

index_codecs: tuple[ZarrV3StaticCodecField, ...]

The codec pipeline that encodes the shard index.

It holds exactly one array -> bytes codec, and only codecs whose output size is fixed by the size of their input, so no compressor. The spec recommends a little-endian bytes codec followed by crc32c.

index_location instance-attribute 

index_location: NotRequired[ShardingIndexLocation]

Whether the shard index sits at the "start" or the "end" of the encoded shard.

Absent means "end".

ShardingIndexedCodecObject

Bases: TypedDict

sharding_indexed codec metadata in object form.

Source code in src/zarr_metadata/v3/codec/sharding_indexed.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
class ShardingIndexedCodecObject(TypedDict, closed=True):
    """`sharding_indexed` codec metadata in object form."""

    name: ShardingIndexedCodecName
    """The codec's name, `"sharding_indexed"`."""
    configuration: ShardingIndexedCodecConfiguration
    """The codec's parameters."""
    must_understand: NotRequired[bool]
    """Whether a reader that does not recognize this codec must refuse the document.

    Absent means `true`. The spec permits `false` for a codec
    (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581),
    though `resolve` reports a `false` as a problem at every extension point.
    """

configuration instance-attribute 

configuration: ShardingIndexedCodecConfiguration

The codec's parameters.

must_understand instance-attribute 

must_understand: NotRequired[bool]

Whether a reader that does not recognize this codec must refuse the document.

Absent means true. The spec permits false for a codec (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581), though resolve reports a false as a problem at every extension point.

name instance-attribute 

name: ShardingIndexedCodecName

The codec's name, "sharding_indexed".

zarr_metadata.v3.codec.transpose

Transpose codec types.

See https://zarr-specs.readthedocs.io/en/latest/v3/codecs/transpose/index.html

TRANSPOSE_CODEC module-attribute 

TRANSPOSE_CODEC: Final = CodecDefinition(
    name=TRANSPOSE_CODEC_NAME,
    configuration=TransposeCodecConfiguration,
    kind="array_array",
    size="static",
    rules=_rules,
    chunk_rules=_chunk_rules,
    transition=_transition,
)

The transpose codec.

TRANSPOSE_CODEC_NAME module-attribute 

TRANSPOSE_CODEC_NAME: Final = 'transpose'

The name field value of the transpose codec.

TransposeCodecMetadata module-attribute 

TransposeCodecMetadata = TransposeCodecObject

Permitted JSON shape for transpose codec metadata.

order is required, so only the object form is valid; the short-hand-name form is not permitted by the spec for this codec. https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/codecs/transpose/index.rst#L60-L66 ("order: Required") https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1562-L1564 (short-hand names only "if no configuration metadata is required")

TransposeCodecName module-attribute 

TransposeCodecName = Literal['transpose']

Literal type of the name field of the transpose codec.

__all__ module-attribute 

__all__ = [
    "TRANSPOSE_CODEC",
    "TRANSPOSE_CODEC_NAME",
    "TransposeCodecConfiguration",
    "TransposeCodecMetadata",
    "TransposeCodecName",
    "TransposeCodecObject",
]

TransposeCodecConfiguration

Bases: TypedDict

Configuration for the Zarr v3 transpose codec.

order is a permutation of the dimension indices 0..n-1 that specifies the dimension reordering applied during encoding.

Source code in src/zarr_metadata/v3/codec/transpose.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
class TransposeCodecConfiguration(TypedDict, closed=True):
    """
    Configuration for the Zarr v3 `transpose` codec.

    `order` is a permutation of the dimension indices 0..n-1 that
    specifies the dimension reordering applied during encoding.
    """

    order: tuple[int, ...]
    """The reordering of axes applied when encoding: axis `i` of the encoded chunk is axis `order[i]` of the chunk the codec is handed.

    A permutation of `0, 1, ..., n-1`, `n` being the number of axes of the
    chunk the codec is handed.
    """

order instance-attribute 

order: tuple[int, ...]

The reordering of axes applied when encoding: axis i of the encoded chunk is axis order[i] of the chunk the codec is handed.

A permutation of 0, 1, ..., n-1, n being the number of axes of the chunk the codec is handed.

TransposeCodecObject

Bases: TypedDict

transpose codec metadata in object form.

Source code in src/zarr_metadata/v3/codec/transpose.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
class TransposeCodecObject(TypedDict, closed=True):
    """`transpose` codec metadata in object form."""

    name: TransposeCodecName
    """The codec's name, `"transpose"`."""
    configuration: TransposeCodecConfiguration
    """The codec's parameters."""
    must_understand: NotRequired[bool]
    """Whether a reader that does not recognize this codec must refuse the document.

    Absent means `true`. The spec permits `false` for a codec
    (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581),
    though `resolve` reports a `false` as a problem at every extension point.
    """

configuration instance-attribute 

configuration: TransposeCodecConfiguration

The codec's parameters.

must_understand instance-attribute 

must_understand: NotRequired[bool]

Whether a reader that does not recognize this codec must refuse the document.

Absent means true. The spec permits false for a codec (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581), though resolve reports a false as a problem at every extension point.

name instance-attribute 

name: TransposeCodecName

The codec's name, "transpose".

zarr_metadata.v3.codec.vlen_bytes

vlen-bytes codec types (zarr-extensions).

See https://github.com/zarr-developers/zarr-extensions/blob/cadd1dab6c9aebafb66080b78b583f6507466b3d/codecs/vlen-bytes/README.md

The codec has no configuration fields, so the configuration key is optional. The spec's example leaves it out, and zarr-python writes an empty object, "configuration": {}.

VLEN_BYTES_CODEC module-attribute 

VLEN_BYTES_CODEC: Final = CodecDefinition(
    name=VLEN_BYTES_CODEC_NAME,
    configuration=EmptyConfiguration,
    kind="array_bytes",
    size="dynamic",
    chunk_rules=_chunk_rules,
)

The vlen-bytes codec, which serializes variable-length byte strings.

It is "only compatible with the "bytes" data type" (https://github.com/zarr-developers/zarr-extensions/blob/cadd1dab6c9aebafb66080b78b583f6507466b3d/codecs/vlen-bytes/README.md?plain=1#L30). The size of its output depends on the values, so it is dynamic.

VLEN_BYTES_CODEC_NAME module-attribute 

VLEN_BYTES_CODEC_NAME: Final = 'vlen-bytes'

The name field value of the vlen-bytes codec.

VlenBytesCodecMetadata module-attribute 

VlenBytesCodecMetadata = (
    VlenBytesCodecObject | VlenBytesCodecName
)

Permitted JSON shapes for vlen-bytes codec metadata: the object form, or the bare name, since the codec has no configuration.

VlenBytesCodecName module-attribute 

VlenBytesCodecName = Literal['vlen-bytes']

Literal type of the name field of the vlen-bytes codec.

__all__ module-attribute 

__all__ = [
    "VLEN_BYTES_CODEC",
    "VLEN_BYTES_CODEC_NAME",
    "VlenBytesCodecMetadata",
    "VlenBytesCodecName",
    "VlenBytesCodecObject",
]

VlenBytesCodecObject

Bases: TypedDict

vlen-bytes codec metadata in object form. The codec has no configuration fields.

Source code in src/zarr_metadata/v3/codec/vlen_bytes.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
class VlenBytesCodecObject(TypedDict, closed=True):
    """`vlen-bytes` codec metadata in object form. The codec has no configuration fields."""

    name: VlenBytesCodecName
    """The codec's name, `"vlen-bytes"`."""
    configuration: NotRequired[EmptyConfiguration]
    """The codec's parameters, of which there are none.

    Absent, or an empty mapping.
    """
    must_understand: NotRequired[bool]
    """Whether a reader that does not recognize this codec must refuse the document.

    Absent means `true`. The spec permits `false` for a codec
    (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581),
    though `resolve` reports a `false` as a problem at every extension point.
    """

configuration instance-attribute 

configuration: NotRequired[EmptyConfiguration]

The codec's parameters, of which there are none.

Absent, or an empty mapping.

must_understand instance-attribute 

must_understand: NotRequired[bool]

Whether a reader that does not recognize this codec must refuse the document.

Absent means true. The spec permits false for a codec (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581), though resolve reports a false as a problem at every extension point.

name instance-attribute 

name: VlenBytesCodecName

The codec's name, "vlen-bytes".

zarr_metadata.v3.codec.vlen_utf8

vlen-utf8 codec types (zarr-extensions).

See https://github.com/zarr-developers/zarr-extensions/blob/cadd1dab6c9aebafb66080b78b583f6507466b3d/codecs/vlen-utf8/README.md

The codec has no configuration fields, so the configuration key is optional. The spec's example leaves it out, and zarr-python writes an empty object, "configuration": {}.

VLEN_UTF8_CODEC module-attribute 

VLEN_UTF8_CODEC: Final = CodecDefinition(
    name=VLEN_UTF8_CODEC_NAME,
    configuration=EmptyConfiguration,
    kind="array_bytes",
    size="dynamic",
    chunk_rules=_chunk_rules,
)

The vlen-utf8 codec, which serializes variable-length UTF-8 strings.

It is "only compatible with the "string" data type" (https://github.com/zarr-developers/zarr-extensions/blob/cadd1dab6c9aebafb66080b78b583f6507466b3d/codecs/vlen-utf8/README.md?plain=1#L30). The size of its output depends on the values, so it is dynamic.

VLEN_UTF8_CODEC_NAME module-attribute 

VLEN_UTF8_CODEC_NAME: Final = 'vlen-utf8'

The name field value of the vlen-utf8 codec.

VlenUtf8CodecMetadata module-attribute 

VlenUtf8CodecMetadata = (
    VlenUtf8CodecObject | VlenUtf8CodecName
)

Permitted JSON shapes for vlen-utf8 codec metadata: the object form, or the bare name, since the codec has no configuration.

VlenUtf8CodecName module-attribute 

VlenUtf8CodecName = Literal['vlen-utf8']

Literal type of the name field of the vlen-utf8 codec.

__all__ module-attribute 

__all__ = [
    "VLEN_UTF8_CODEC",
    "VLEN_UTF8_CODEC_NAME",
    "VlenUtf8CodecMetadata",
    "VlenUtf8CodecName",
    "VlenUtf8CodecObject",
]

VlenUtf8CodecObject

Bases: TypedDict

vlen-utf8 codec metadata in object form. The codec has no configuration fields.

Source code in src/zarr_metadata/v3/codec/vlen_utf8.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
class VlenUtf8CodecObject(TypedDict, closed=True):
    """`vlen-utf8` codec metadata in object form. The codec has no configuration fields."""

    name: VlenUtf8CodecName
    """The codec's name, `"vlen-utf8"`."""
    configuration: NotRequired[EmptyConfiguration]
    """The codec's parameters, of which there are none.

    Absent, or an empty mapping.
    """
    must_understand: NotRequired[bool]
    """Whether a reader that does not recognize this codec must refuse the document.

    Absent means `true`. The spec permits `false` for a codec
    (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581),
    though `resolve` reports a `false` as a problem at every extension point.
    """

configuration instance-attribute 

configuration: NotRequired[EmptyConfiguration]

The codec's parameters, of which there are none.

Absent, or an empty mapping.

must_understand instance-attribute 

must_understand: NotRequired[bool]

Whether a reader that does not recognize this codec must refuse the document.

Absent means true. The spec permits false for a codec (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581), though resolve reports a false as a problem at every extension point.

name instance-attribute 

name: VlenUtf8CodecName

The codec's name, "vlen-utf8".

zarr_metadata.v3.codec.zstd

Zstandard codec types.

See https://github.com/zarr-developers/zarr-extensions/blob/4da7b37a84f76e660902f6d3de3eaef0e0febae6/codecs/zstd/README.md (the zarr-extensions registry entry; zarr-specs PR #256, which first proposed the codec, was never merged).

ZSTD_CODEC module-attribute 

ZSTD_CODEC: Final = CodecDefinition(
    name=ZSTD_CODEC_NAME,
    configuration=ZstdCodecConfiguration,
    canonical=_canonical,
    kind="bytes_bytes",
    size="dynamic",
)

The zstd codec.

ZSTD_CODEC_NAME module-attribute 

ZSTD_CODEC_NAME: Final = 'zstd'

The name field value of the zstd codec.

ZSTD_MAX_LEVEL module-attribute 

ZSTD_MAX_LEVEL: Final = 22

The highest level zstd accepts: ZSTD_maxCLevel().

ZSTD_MIN_LEVEL module-attribute 

ZSTD_MIN_LEVEL: Final = -131072

The lowest level zstd accepts: ZSTD_minCLevel(), -(1 << 17).

ZstdCodecMetadata module-attribute 

ZstdCodecMetadata = ZstdCodecObject

Permitted JSON shape for zstd codec metadata.

level is required, so only the object form is valid; the short-hand-name form is not permitted by the spec for this codec. https://github.com/zarr-developers/zarr-extensions/blob/4da7b37a84f76e660902f6d3de3eaef0e0febae6/codecs/zstd/README.md#L9-L19 https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1562-L1564 (short-hand names only "if no configuration metadata is required")

ZstdCodecName module-attribute 

ZstdCodecName = Literal['zstd']

Literal type of the name field of the zstd codec.

__all__ module-attribute 

__all__ = [
    "ZSTD_CODEC",
    "ZSTD_CODEC_NAME",
    "ZSTD_MAX_LEVEL",
    "ZSTD_MIN_LEVEL",
    "ZstdCodecConfiguration",
    "ZstdCodecMetadata",
    "ZstdCodecName",
    "ZstdCodecObject",
]

ZstdCodecConfiguration

Bases: TypedDict

Configuration for the Zarr v3 zstd codec.

level is required; checksum is optional ("Should be omitted if false"). https://github.com/zarr-developers/zarr-extensions/blob/4da7b37a84f76e660902f6d3de3eaef0e0febae6/codecs/zstd/README.md#L9-L19

Source code in src/zarr_metadata/v3/codec/zstd.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
class ZstdCodecConfiguration(TypedDict, closed=True):
    """
    Configuration for the Zarr v3 `zstd` codec.

    `level` is required; `checksum` is optional ("Should be omitted if
    false").
      https://github.com/zarr-developers/zarr-extensions/blob/4da7b37a84f76e660902f6d3de3eaef0e0febae6/codecs/zstd/README.md#L9-L19
    """

    level: Annotated[int, Interval(ge=ZSTD_MIN_LEVEL, le=ZSTD_MAX_LEVEL)]
    """The compression level, an integer from `ZSTD_MIN_LEVEL` (-131072) to `ZSTD_MAX_LEVEL` (22).

    0 means zstd's default level; otherwise a higher level compresses more,
    more slowly. It has no effect on decoding.
    """
    checksum: NotRequired[bool]
    """Whether a checksum is stored when writing and verified when reading.

    Absent means `false`; the registry says to omit it rather than write
    `false`.
    """

checksum instance-attribute 

checksum: NotRequired[bool]

Whether a checksum is stored when writing and verified when reading.

Absent means false; the registry says to omit it rather than write false.

level instance-attribute 

level: Annotated[
    int, Interval(ge=ZSTD_MIN_LEVEL, le=ZSTD_MAX_LEVEL)
]

The compression level, an integer from ZSTD_MIN_LEVEL (-131072) to ZSTD_MAX_LEVEL (22).

0 means zstd's default level; otherwise a higher level compresses more, more slowly. It has no effect on decoding.

ZstdCodecObject

Bases: TypedDict

zstd codec metadata in object form.

Source code in src/zarr_metadata/v3/codec/zstd.py 
52
53
54
55
56
57
58
59
60
61
62
63
64
65
class ZstdCodecObject(TypedDict, closed=True):
    """`zstd` codec metadata in object form."""

    name: ZstdCodecName
    """The codec's name, `"zstd"`."""
    configuration: ZstdCodecConfiguration
    """The codec's parameters."""
    must_understand: NotRequired[bool]
    """Whether a reader that does not recognize this codec must refuse the document.

    Absent means `true`. The spec permits `false` for a codec
    (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581),
    though `resolve` reports a `false` as a problem at every extension point.
    """

configuration instance-attribute 

configuration: ZstdCodecConfiguration

The codec's parameters.

must_understand instance-attribute 

must_understand: NotRequired[bool]

Whether a reader that does not recognize this codec must refuse the document.

Absent means true. The spec permits false for a codec (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1581), though resolve reports a false as a problem at every extension point.

name instance-attribute 

name: ZstdCodecName

The codec's name, "zstd".