Skip to content

zarr_metadata.v3.chunk_grid

zarr_metadata.v3.chunk_grid

Zarr v3 chunk grid metadata types.

Each chunk grid lives in its own submodule:

  • regular -- core v3 spec
  • rectilinear -- zarr-extensions

The <X>ChunkGridMetadata aliases re-exported here are the canonical type for each grid's permitted JSON shapes. For the underlying <X>ChunkGridObject, <X>ChunkGridConfiguration, etc., import directly from the leaf submodule.

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

zarr_metadata.v3.chunk_grid.regular

Regular chunk grid (Zarr v3 core spec).

See https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html#regular-grids

REGULAR_CHUNK_GRID module-attribute 

REGULAR_CHUNK_GRID: Final = ChunkGridDefinition(
    name=REGULAR_CHUNK_GRID_NAME,
    configuration=RegularChunkGridConfiguration,
    rules=_rules,
    shape_rules=_shape_rules,
    chunk_lengths=_chunk_lengths,
)

The regular chunk grid.

REGULAR_CHUNK_GRID_NAME module-attribute 

REGULAR_CHUNK_GRID_NAME: Final = 'regular'

The name field value of the regular chunk grid.

RegularChunkGridMetadata module-attribute 

RegularChunkGridMetadata = RegularChunkGridObject

Permitted JSON shape for regular chunk grid metadata.

chunk_shape is required and has no default, so only the object form is valid; the short-hand-name form is not permitted by the spec for this grid. https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L528-L537 ("must be an object with the names name and configuration") https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1562-L1564

RegularChunkGridName module-attribute 

RegularChunkGridName = Literal['regular']

Literal type of the name field of the regular chunk grid.

__all__ module-attribute 

__all__ = [
    "REGULAR_CHUNK_GRID",
    "REGULAR_CHUNK_GRID_NAME",
    "RegularChunkGridConfiguration",
    "RegularChunkGridMetadata",
    "RegularChunkGridName",
    "RegularChunkGridObject",
]

RegularChunkGridConfiguration

Bases: TypedDict

Configuration for the regular chunk grid.

Source code in src/zarr_metadata/v3/chunk_grid/regular.py 
22
23
24
25
class RegularChunkGridConfiguration(TypedDict, closed=True):
    """Configuration for the regular chunk grid."""

    chunk_shape: tuple[int, ...]

chunk_shape instance-attribute 

chunk_shape: tuple[int, ...]

RegularChunkGridObject

Bases: TypedDict

Regular chunk grid metadata in object form.

Source code in src/zarr_metadata/v3/chunk_grid/regular.py 
28
29
30
31
32
33
class RegularChunkGridObject(TypedDict, closed=True):
    """Regular chunk grid metadata in object form."""

    name: RegularChunkGridName
    configuration: RegularChunkGridConfiguration
    must_understand: NotRequired[bool]

configuration instance-attribute 

configuration: RegularChunkGridConfiguration

must_understand instance-attribute 

must_understand: NotRequired[bool]

name instance-attribute 

name: RegularChunkGridName

zarr_metadata.v3.chunk_grid.rectilinear

Rectilinear chunk grid (zarr-extensions).

See https://github.com/zarr-developers/zarr-extensions/blob/4da7b37a84f76e660902f6d3de3eaef0e0febae6/chunk-grids/rectilinear/README.md

RECTILINEAR_CHUNK_GRID module-attribute 

RECTILINEAR_CHUNK_GRID: Final = ChunkGridDefinition(
    name=RECTILINEAR_CHUNK_GRID_NAME,
    configuration=RectilinearChunkGridConfiguration,
    rules=_rules,
    canonical=_canonical,
    shape_rules=_shape_rules,
    chunk_lengths=_chunk_lengths,
)

The rectilinear chunk grid.

RECTILINEAR_CHUNK_GRID_NAME module-attribute 

RECTILINEAR_CHUNK_GRID_NAME: Final = 'rectilinear'

The name field value of the rectilinear chunk grid.

RectilinearChunkGridMetadata module-attribute 

RectilinearChunkGridMetadata = RectilinearChunkGridObject

Permitted JSON shape for rectilinear chunk grid metadata.

kind and chunk_shapes are required, so only the object form is valid; the short-hand-name form is not permitted by the spec for this grid. https://github.com/zarr-developers/zarr-extensions/blob/4da7b37a84f76e660902f6d3de3eaef0e0febae6/chunk-grids/rectilinear/README.md#L59-L62 https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1562-L1564

RectilinearChunkGridName module-attribute 

RectilinearChunkGridName = Literal['rectilinear']

Literal type of the name field of the rectilinear chunk grid.

RectilinearDimSpec module-attribute 

RectilinearDimSpec = int | tuple[int | tuple[int, int], ...]

JSON shape for one dimension's rectilinear spec.

Either a bare integer (uniform shorthand for a regular dimension within a rectilinear grid), or a tuple of integers and/or [value, count] RLE pairs.

__all__ module-attribute 

__all__ = [
    "RECTILINEAR_CHUNK_GRID",
    "RECTILINEAR_CHUNK_GRID_NAME",
    "RectilinearChunkGridConfiguration",
    "RectilinearChunkGridMetadata",
    "RectilinearChunkGridName",
    "RectilinearChunkGridObject",
    "RectilinearDimSpec",
    "canonical_chunk_shapes",
    "canonical_dim_spec",
]

RectilinearChunkGridConfiguration

Bases: TypedDict

Configuration for the rectilinear chunk grid.

Source code in src/zarr_metadata/v3/chunk_grid/rectilinear.py 
31
32
33
34
35
class RectilinearChunkGridConfiguration(TypedDict, closed=True):
    """Configuration for the rectilinear chunk grid."""

    kind: Literal["inline"]
    chunk_shapes: tuple[RectilinearDimSpec, ...]

chunk_shapes instance-attribute 

chunk_shapes: tuple[RectilinearDimSpec, ...]

kind instance-attribute 

kind: Literal['inline']

RectilinearChunkGridObject

Bases: TypedDict

Rectilinear chunk grid metadata in object form.

Source code in src/zarr_metadata/v3/chunk_grid/rectilinear.py 
38
39
40
41
42
43
class RectilinearChunkGridObject(TypedDict, closed=True):
    """Rectilinear chunk grid metadata in object form."""

    name: RectilinearChunkGridName
    configuration: RectilinearChunkGridConfiguration
    must_understand: NotRequired[bool]

configuration instance-attribute 

configuration: RectilinearChunkGridConfiguration

must_understand instance-attribute 

must_understand: NotRequired[bool]

name instance-attribute 

name: RectilinearChunkGridName

canonical_chunk_shapes 

canonical_chunk_shapes(
    chunk_shapes: tuple[RectilinearDimSpec, ...],
) -> tuple[RectilinearDimSpec, ...]

Every dimension's chunk sizes in their simplest equivalent form.

Source code in src/zarr_metadata/v3/chunk_grid/rectilinear.py 
111
112
113
114
115
def canonical_chunk_shapes(
    chunk_shapes: tuple[RectilinearDimSpec, ...],
) -> tuple[RectilinearDimSpec, ...]:
    """Every dimension's chunk sizes in their simplest equivalent form."""
    return tuple(canonical_dim_spec(spec) for spec in chunk_shapes)

canonical_dim_spec 

canonical_dim_spec(
    spec: RectilinearDimSpec,
) -> RectilinearDimSpec

One dimension's chunk sizes in their simplest equivalent form.

Runs of equal sizes collapse to [size, count] pairs, because that is the spelling that does not grow with the number of chunks: a million equal chunks is two numbers, not a million. A run of one stays a bare size, and [size, 1] collapses to one, since a pair says nothing extra there. Adjacent spellings of the same size merge, which is what makes this idempotent: [[32, 2], 32] and [32, [32, 2]] both become [[32, 3]].

A dimension-level bare integer is left alone. It is a step that repeats until it covers the extent, so it is not equivalent to any fixed list: expanding it would pin a grid that currently adapts, and the two would diverge the moment the array were resized. For the same reason a one-element list is never collapsed to a bare integer: [32] declares exactly one chunk and 32 declares as many as it takes.

Assumes a spec the rules have accepted.

Source code in src/zarr_metadata/v3/chunk_grid/rectilinear.py 
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
def canonical_dim_spec(spec: RectilinearDimSpec) -> RectilinearDimSpec:
    """One dimension's chunk sizes in their simplest equivalent form.

    Runs of equal sizes collapse to `[size, count]` pairs, because that is
    the spelling that does not grow with the number of chunks: a million
    equal chunks is two numbers, not a million. A run of one stays a bare
    size, and `[size, 1]` collapses to one, since a pair says nothing extra
    there. Adjacent spellings of the same size merge, which is what makes
    this idempotent: `[[32, 2], 32]` and `[32, [32, 2]]` both become
    `[[32, 3]]`.

    A dimension-level bare integer is left alone. It is a *step* that
    repeats until it covers the extent, so it is not equivalent to any
    fixed list: expanding it would pin a grid that currently adapts, and
    the two would diverge the moment the array were resized. For the same
    reason a one-element list is never collapsed to a bare integer:
    `[32]` declares exactly one chunk and `32` declares as many as it takes.

    Assumes a spec the rules have accepted.
    """
    if not isinstance(spec, tuple):
        return spec
    runs: list[tuple[int, int]] = []
    for entry in spec:
        size, count = entry if isinstance(entry, tuple) else (entry, 1)
        if len(runs) != 0 and runs[-1][0] == size:
            runs[-1] = (size, runs[-1][1] + count)
        else:
            runs.append((size, count))
    return tuple(size if count == 1 else (size, count) for size, count in runs)