Skip to content

zarr_metadata.v3.chunk_key_encoding

zarr_metadata.v3.chunk_key_encoding

Zarr v3 chunk key encoding metadata types.

Each chunk key encoding lives in its own submodule:

  • default -- v3 default encoding (/-separated)
  • v2 -- v2-compatibility encoding (.-separated by default)

Both are defined by the v3 core spec.

The <X>ChunkKeyEncodingMetadata aliases re-exported here are the canonical type for each encoding's permitted JSON shapes. For the underlying <X>ChunkKeyEncodingObject, <X>ChunkKeyEncodingConfiguration, etc., import directly from the leaf submodule.

See https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html#chunk-key-encoding

zarr_metadata.v3.chunk_key_encoding.default

Default chunk key encoding (Zarr v3 core spec).

The chunk key for a chunk with grid index (k, j, i, ...) is formed by appending c<sep>k<sep>j<sep>i... (where <sep> is separator).

See https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html#chunk-key-encoding

DEFAULT_CHUNK_KEY_ENCODING_NAME module-attribute 

DEFAULT_CHUNK_KEY_ENCODING_NAME: Final = 'default'

The name field value of the default chunk key encoding.

DEFAULT_CHUNK_KEY_ENCODING_SEPARATOR module-attribute 

DEFAULT_CHUNK_KEY_ENCODING_SEPARATOR: Final = ('/', '.')

Tuple of permitted values for the separator field of the default chunk key encoding.

DefaultChunkKeyEncodingMetadata module-attribute 

DefaultChunkKeyEncodingMetadata = (
    DefaultChunkKeyEncodingObject
    | DefaultChunkKeyEncodingName
)

Permitted JSON shapes for the default chunk-key encoding metadata.

The configuration has no required keys (separator defaults to "/"), so the short-hand-name form is permitted in addition to the object form.

DefaultChunkKeyEncodingName module-attribute 

DefaultChunkKeyEncodingName = Literal['default']

Literal type of the name field of the default chunk key encoding.

DefaultChunkKeyEncodingSeparator module-attribute 

DefaultChunkKeyEncodingSeparator = Literal['/', '.']

Literal type of permitted separator values for the default chunk key encoding.

Defaults to "/" if absent.

__all__ module-attribute 

__all__ = [
    "DEFAULT_CHUNK_KEY_ENCODING_NAME",
    "DEFAULT_CHUNK_KEY_ENCODING_SEPARATOR",
    "DefaultChunkKeyEncodingConfiguration",
    "DefaultChunkKeyEncodingMetadata",
    "DefaultChunkKeyEncodingName",
    "DefaultChunkKeyEncodingObject",
    "DefaultChunkKeyEncodingSeparator",
]

DefaultChunkKeyEncodingConfiguration

Bases: TypedDict

Configuration for the default chunk key encoding.

separator is optional and defaults to "/" per spec.

Source code in src/zarr_metadata/v3/chunk_key_encoding/default.py 
32
33
34
35
36
37
38
class DefaultChunkKeyEncodingConfiguration(TypedDict, extra_items=JSONValue):
    """Configuration for the default chunk key encoding.

    `separator` is optional and defaults to `"/"` per spec.
    """

    separator: NotRequired[DefaultChunkKeyEncodingSeparator]

separator instance-attribute 

separator: NotRequired[DefaultChunkKeyEncodingSeparator]

DefaultChunkKeyEncodingObject

Bases: TypedDict

Default chunk key encoding metadata in object form.

Source code in src/zarr_metadata/v3/chunk_key_encoding/default.py 
41
42
43
44
45
class DefaultChunkKeyEncodingObject(TypedDict, extra_items=JSONValue):
    """Default chunk key encoding metadata in object form."""

    name: DefaultChunkKeyEncodingName
    configuration: NotRequired[DefaultChunkKeyEncodingConfiguration]

configuration instance-attribute 

configuration: NotRequired[
    DefaultChunkKeyEncodingConfiguration
]

name instance-attribute 

name: DefaultChunkKeyEncodingName

zarr_metadata.v3.chunk_key_encoding.v2

v2-compatibility chunk key encoding (Zarr v3 core spec).

Intended only to allow existing v2 arrays to be converted to v3 without having to rename chunks. Not recommended for new arrays.

Naming note: these are Zarr v3 types. The leading V2 in V2ChunkKeyEncodingMetadata (and friends) is the encoding's registered entity name ("v2"), not the format-version marker that ZarrV2... names carry — this package's version-prefixed names always spell it ZarrV2 / ZarrV3.

See https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html#chunk-key-encoding

V2ChunkKeyEncodingMetadata module-attribute 

V2ChunkKeyEncodingMetadata = (
    V2ChunkKeyEncodingObject | V2ChunkKeyEncodingName
)

Permitted JSON shapes for the v2-compatibility chunk-key encoding metadata.

The configuration has no required keys (separator defaults to "."), so the short-hand-name form is permitted in addition to the object form.

V2ChunkKeyEncodingName module-attribute 

V2ChunkKeyEncodingName = Literal['v2']

Literal type of the name field of the v2 chunk key encoding.

V2ChunkKeyEncodingSeparator module-attribute 

V2ChunkKeyEncodingSeparator = Literal['/', '.']

Literal type of permitted separator values for the v2 chunk key encoding.

Defaults to "." if absent.

V2_CHUNK_KEY_ENCODING_NAME module-attribute 

V2_CHUNK_KEY_ENCODING_NAME: Final = 'v2'

The name field value of the v2 chunk key encoding.

V2_CHUNK_KEY_ENCODING_SEPARATOR module-attribute 

V2_CHUNK_KEY_ENCODING_SEPARATOR: Final = ('/', '.')

Tuple of permitted values for the separator field of the v2 chunk key encoding.

__all__ module-attribute 

__all__ = [
    "V2_CHUNK_KEY_ENCODING_NAME",
    "V2_CHUNK_KEY_ENCODING_SEPARATOR",
    "V2ChunkKeyEncodingConfiguration",
    "V2ChunkKeyEncodingMetadata",
    "V2ChunkKeyEncodingName",
    "V2ChunkKeyEncodingObject",
    "V2ChunkKeyEncodingSeparator",
]

V2ChunkKeyEncodingConfiguration

Bases: TypedDict

Configuration for the v2 chunk key encoding.

separator is optional and defaults to "." per spec.

Source code in src/zarr_metadata/v3/chunk_key_encoding/v2.py 
38
39
40
41
42
43
44
class V2ChunkKeyEncodingConfiguration(TypedDict, extra_items=JSONValue):
    """Configuration for the v2 chunk key encoding.

    `separator` is optional and defaults to `"."` per spec.
    """

    separator: NotRequired[V2ChunkKeyEncodingSeparator]

separator instance-attribute 

separator: NotRequired[V2ChunkKeyEncodingSeparator]

V2ChunkKeyEncodingObject

Bases: TypedDict

v2-compatibility chunk key encoding metadata in object form.

Source code in src/zarr_metadata/v3/chunk_key_encoding/v2.py 
47
48
49
50
51
class V2ChunkKeyEncodingObject(TypedDict, extra_items=JSONValue):
    """v2-compatibility chunk key encoding metadata in object form."""

    name: V2ChunkKeyEncodingName
    configuration: NotRequired[V2ChunkKeyEncodingConfiguration]

configuration instance-attribute 

configuration: NotRequired[V2ChunkKeyEncodingConfiguration]

name instance-attribute 

name: V2ChunkKeyEncodingName