|
3 | 3 | import json |
4 | 4 | from collections.abc import Iterable, Mapping, Sequence |
5 | 5 | from dataclasses import dataclass, field, replace |
6 | | -from typing import TYPE_CHECKING, Any, Final, Literal, NotRequired, TypeGuard, cast |
| 6 | +from typing import TYPE_CHECKING, Any, Final, Literal, TypeGuard, cast |
7 | 7 |
|
8 | 8 | from typing_extensions import TypedDict |
| 9 | +from zarr_metadata.v3.array import ArrayMetadataV3, ExtensionFieldV3 |
9 | 10 |
|
10 | 11 | from zarr.abc.codec import ArrayArrayCodec, ArrayBytesCodec, BytesBytesCodec, Codec |
11 | 12 | from zarr.abc.metadata import Metadata |
@@ -139,14 +140,12 @@ def parse_storage_transformers(data: object) -> tuple[dict[str, JSON], ...]: |
139 | 140 | ) |
140 | 141 |
|
141 | 142 |
|
142 | | -class AllowedExtraField(TypedDict, extra_items=JSON): # type: ignore[call-arg] |
143 | | - """ |
144 | | - This class models allowed extra fields in array metadata. |
145 | | - They must have ``must_understand`` set to ``False``, and may contain |
146 | | - arbitrary additional JSON data. |
147 | | - """ |
| 143 | +AllowedExtraField = ExtensionFieldV3 |
| 144 | +"""Alias for `zarr_metadata.v3.array.ExtensionFieldV3`. |
148 | 145 |
|
149 | | - must_understand: Literal[False] |
| 146 | +`must_understand` is typed as `bool` to match the spec (extension authors that |
| 147 | +*understand* a field may produce `True`); the runtime guard |
| 148 | +`check_allowed_extra_field` enforces that zarr-python only accepts `False`.""" |
150 | 149 |
|
151 | 150 |
|
152 | 151 | def check_allowed_extra_field(data: object) -> TypeGuard[AllowedExtraField]: |
@@ -421,25 +420,12 @@ def parse_chunk_grid( |
421 | 420 | raise ValueError(f"Unknown chunk grid name: {name!r}") |
422 | 421 |
|
423 | 422 |
|
424 | | -class ArrayMetadataJSON_V3(TypedDict, extra_items=AllowedExtraField): # type: ignore[call-arg] |
425 | | - """ |
426 | | - A typed dictionary model for zarr v3 array metadata. |
427 | | -
|
428 | | - Extra keys are permitted if they conform to ``AllowedExtraField`` |
429 | | - (i.e. they are mappings with ``must_understand: false``). |
430 | | - """ |
| 423 | +ArrayMetadataJSON_V3 = ArrayMetadataV3 |
| 424 | +"""Alias for `zarr_metadata.v3.array.ArrayMetadataV3`. |
431 | 425 |
|
432 | | - zarr_format: Literal[3] |
433 | | - node_type: Literal["array"] |
434 | | - data_type: str | NamedConfig[str, Mapping[str, JSON]] |
435 | | - shape: tuple[int, ...] |
436 | | - chunk_grid: str | NamedConfig[str, Mapping[str, JSON]] |
437 | | - chunk_key_encoding: str | NamedConfig[str, Mapping[str, JSON]] |
438 | | - fill_value: JSON |
439 | | - codecs: tuple[str | NamedConfig[str, Mapping[str, JSON]], ...] |
440 | | - attributes: NotRequired[Mapping[str, JSON]] |
441 | | - storage_transformers: NotRequired[tuple[str | NamedConfig[str, Mapping[str, JSON]], ...]] |
442 | | - dimension_names: NotRequired[tuple[str | None, ...]] |
| 426 | +The TypedDict from the metadata package is the canonical model of the v3 |
| 427 | +array metadata document; this alias preserves the historical zarr-python |
| 428 | +name. Extra keys are permitted if they conform to `ExtensionFieldV3`.""" |
443 | 429 |
|
444 | 430 |
|
445 | 431 | """ |
@@ -671,6 +657,12 @@ def from_dict(cls, data: dict[str, JSON]) -> Self: |
671 | 657 | ) |
672 | 658 |
|
673 | 659 | def to_dict(self) -> dict[str, JSON]: |
| 660 | + """Serialize as a JSON-shaped dict matching `ArrayMetadataV3`. |
| 661 | +
|
| 662 | + Return type is `dict[str, JSON]` rather than `ArrayMetadataV3` so the |
| 663 | + result composes with other zarr-python metadata serialisation paths |
| 664 | + that traffic in `dict[str, JSON]` (notably consolidated metadata). |
| 665 | + """ |
674 | 666 | out_dict = super().to_dict() |
675 | 667 | extra_fields = out_dict.pop("extra_fields") |
676 | 668 | out_dict = out_dict | extra_fields # type: ignore[operator] |
|
0 commit comments