`zarr_metadata.pydantic`

zarr_metadata.pydantic ¶

Optional pydantic (v2) integration: field types over the core models.

Importing this module requires pydantic; the core package deliberately does not depend on it, so this module is never imported by zarr_metadata itself.

Each exported name is an Annotated field type over the corresponding core model class — the instances ARE the core classes, so values interoperate freely with non-pydantic code (equality, isinstance, nesting). Validation delegates to the library: a raw document routes through from_json (the single source of truth for validation and normalization, so pydantic's field-level coercion can never bypass it). A field type reads the fields of its document in the scope pydantic's validation context holds, as pydantic hands any validator its context: the context itself, when it is a Context, which every field type then reads in; or, when it is a mapping, its "zarr_metadata_context" item for the v3 field types and its "zarr_metadata_context_v2" item for the v2 ones, so a model holding both kinds of field names each format's scope; a format whose scope is not given reads in its own, CORE_AND_EXTENSIONS or CORE_V2:

TypeAdapter(zmp.ZarrV3ArrayMetadata).validate_python(document, context=SCOPE)
ArrayManifest.model_validate(data, context={"zarr_metadata_context": SCOPE})
Mixed.model_validate(data, context={"zarr_metadata_context": V3, "zarr_metadata_context_v2": V2})

An existing model instance passes through unchanged, as pydantic's does, and serialization emits the canonical document via to_json. A failed parse surfaces as a pydantic ValidationError with one line error per problem, as pydantic reports its own: its type the problem's kind, at the problem's loc under the field's, with the input found there and the problem's ctx (a message holding a ctx placeholder rides in the ctx as message, as _line_error says). Annotate a field with these types, not the core classes, which pydantic cannot build a schema for.

A node's attributes may hold NaN, Infinity or -Infinity, which the models read and write as zarr-python does. Pydantic writes JSON by its own rules, and by default writes such a number as null. A BaseModel holding one of these fields keeps it with ser_json_inf_nan="constants" in its model_config; a TypeAdapter over a field type takes no config, so write its value with the model's to_key_value instead.

Usage:

import zarr_metadata.pydantic as zmp

class ArrayManifest(BaseModel):
    path: str
    metadata: zmp.ZarrV3ArrayMetadata

Static type checkers see each field type as its core model class, so manifest.metadata is a zarr_metadata.model.ZarrV3ArrayMetadata.

CONTEXT_KEY `module-attribute` ¶

CONTEXT_KEY: Final = 'zarr_metadata_context'

The key of a mapping validation context under which the scope the v3 field types read in sits.

CONTEXT_KEY_V2 `module-attribute` ¶

CONTEXT_KEY_V2: Final = 'zarr_metadata_context_v2'

The key of a mapping validation context under which the scope the v2 field types read in sits.

ZarrV2ArrayMetadata `module-attribute` ¶

ZarrV2ArrayMetadata = Annotated[
    InstanceOf[_model.ZarrV2ArrayMetadata],
    BeforeValidator(
        _read_in_scope(
            _model.ZarrV2ArrayMetadata,
            _model.ZarrV2ArrayMetadata.from_json,
            CORE_V2,
            CONTEXT_KEY_V2,
        ),
        json_schema_input_type=_ZarrV2ArrayMetadataSchema,
    ),
    PlainSerializer(
        _model.ZarrV2ArrayMetadata.to_json,
        return_type=_ZarrV2ArrayMetadataSchema,
    ),
]

Field type for a v2 array metadata document (merged .zarray + .zattrs form).

ZarrV2ConsolidatedMetadata `module-attribute` ¶

ZarrV2ConsolidatedMetadata = Annotated[
    InstanceOf[_model.ZarrV2ConsolidatedMetadata],
    BeforeValidator(
        _read_in_scope(
            _model.ZarrV2ConsolidatedMetadata,
            _model.ZarrV2ConsolidatedMetadata.from_json,
            CORE_V2,
            CONTEXT_KEY_V2,
        ),
        json_schema_input_type=_ZarrV2ConsolidatedMetadataSchema,
    ),
    PlainSerializer(
        _model.ZarrV2ConsolidatedMetadata.to_json,
        return_type=_ZarrV2ConsolidatedMetadataSchema,
    ),
]

Field type for a v2 .zmetadata document.

ZarrV2GroupMetadata `module-attribute` ¶

ZarrV2GroupMetadata = Annotated[
    InstanceOf[_model.ZarrV2GroupMetadata],
    BeforeValidator(
        _read_in_scope(
            _model.ZarrV2GroupMetadata,
            _model.ZarrV2GroupMetadata.from_json,
            CORE_V2,
            CONTEXT_KEY_V2,
        ),
        json_schema_input_type=_ZarrV2GroupMetadataSchema,
    ),
    PlainSerializer(
        _model.ZarrV2GroupMetadata.to_json,
        return_type=_ZarrV2GroupMetadataSchema,
    ),
]

Field type for a v2 group metadata document (merged .zgroup + .zattrs form).

ZarrV3ArrayMetadata `module-attribute` ¶

ZarrV3ArrayMetadata = Annotated[
    InstanceOf[_model.ZarrV3ArrayMetadata],
    BeforeValidator(
        _read_in_scope(
            _model.ZarrV3ArrayMetadata,
            _model.ZarrV3ArrayMetadata.from_json,
            CORE_AND_EXTENSIONS,
            CONTEXT_KEY,
        ),
        json_schema_input_type=_ZarrV3ArrayMetadataSchema,
    ),
    PlainSerializer(
        _model.ZarrV3ArrayMetadata.to_json,
        return_type=_ZarrV3ArrayMetadataSchema,
    ),
]

Field type for a v3 array metadata document (zarr.json content).

ZarrV3ConsolidatedMetadata `module-attribute` ¶

ZarrV3ConsolidatedMetadata = Annotated[
    InstanceOf[_model.ZarrV3ConsolidatedMetadata],
    BeforeValidator(
        _read_in_scope(
            _model.ZarrV3ConsolidatedMetadata,
            _model.ZarrV3ConsolidatedMetadata.from_json,
            CORE_AND_EXTENSIONS,
            CONTEXT_KEY,
        ),
        json_schema_input_type=_ZarrV3ConsolidatedMetadataSchema,
    ),
    PlainSerializer(
        _model.ZarrV3ConsolidatedMetadata.to_json,
        return_type=_ZarrV3ConsolidatedMetadataSchema,
    ),
]

Field type for v3 inline consolidated metadata.

ZarrV3GroupMetadata `module-attribute` ¶

ZarrV3GroupMetadata = Annotated[
    InstanceOf[_model.ZarrV3GroupMetadata],
    BeforeValidator(
        _read_in_scope(
            _model.ZarrV3GroupMetadata,
            _model.ZarrV3GroupMetadata.from_json,
            CORE_AND_EXTENSIONS,
            CONTEXT_KEY,
        ),
        json_schema_input_type=_ZarrV3GroupMetadataSchema,
    ),
    PlainSerializer(
        _model.ZarrV3GroupMetadata.to_json,
        return_type=_ZarrV3GroupMetadataSchema,
    ),
]

Field type for a v3 group metadata document (zarr.json content).

all `module-attribute` ¶

__all__ = [
    "CONTEXT_KEY",
    "CONTEXT_KEY_V2",
    "ZarrV2ArrayMetadata",
    "ZarrV2ConsolidatedMetadata",
    "ZarrV2GroupMetadata",
    "ZarrV3ArrayMetadata",
    "ZarrV3ConsolidatedMetadata",
    "ZarrV3GroupMetadata",
]

zarr_metadata.pydantic