Skip to content

Commit 629e565

Browse files
committed
refactor: bring in types from zarr-metadata
1 parent 7c2f372 commit 629e565

7 files changed

Lines changed: 124 additions & 81 deletions

File tree

‎.pre-commit-config.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ repos:
4242
- typing_extensions
4343
- universal-pathlib
4444
- obstore>=0.5.1
45+
- zarr-metadata>=0.1.1
4546
# Tests
4647
- pytest
4748
- hypothesis

‎pyproject.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ dependencies = [
3838
'google-crc32c>=1.5',
3939
'typing_extensions>=4.13',
4040
'donfig>=0.8',
41+
'zarr-metadata>=0.1.1',
4142
]
4243

4344
dynamic = [

‎src/zarr/codecs/blosc.py‎

Lines changed: 18 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,22 @@
99
import numcodecs
1010
from numcodecs.blosc import Blosc
1111
from packaging.version import Version
12+
from zarr_metadata.v3.codec.blosc import (
13+
BloscCName as _BloscCName,
14+
)
15+
from zarr_metadata.v3.codec.blosc import (
16+
BloscCodecConfiguration as _BloscCodecConfiguration,
17+
)
18+
from zarr_metadata.v3.codec.blosc import (
19+
BloscCodecObject as _BloscCodecObject,
20+
)
21+
from zarr_metadata.v3.codec.blosc import (
22+
BloscShuffle as _BloscShuffle,
23+
)
1224

1325
from zarr.abc.codec import BytesBytesCodec
1426
from zarr.core.buffer.cpu import as_numpy_array_wrapper
15-
from zarr.core.common import JSON, NamedRequiredConfig, parse_enum, parse_named_configuration
27+
from zarr.core.common import JSON, parse_enum, parse_named_configuration
1628
from zarr.core.dtype.common import HasItemSize
1729

1830
if TYPE_CHECKING:
@@ -21,14 +33,14 @@
2133
from zarr.core.array_spec import ArraySpec
2234
from zarr.core.buffer import Buffer
2335

24-
Shuffle = Literal["noshuffle", "shuffle", "bitshuffle"]
25-
"""The shuffle values permitted for the blosc codec"""
36+
# Re-export under zarr-python's historical names.
37+
Shuffle = _BloscShuffle
38+
CName = _BloscCName
39+
BloscConfigV3 = _BloscCodecConfiguration
40+
BloscJSON_V3 = _BloscCodecObject
2641

2742
SHUFFLE: Final = ("noshuffle", "shuffle", "bitshuffle")
2843

29-
CName = Literal["lz4", "lz4hc", "blosclz", "snappy", "zlib", "zstd"]
30-
"""The codec identifiers used in the blosc codec """
31-
3244

3345
class BloscConfigV2(TypedDict):
3446
"""Configuration for the V2 Blosc codec"""
@@ -40,22 +52,6 @@ class BloscConfigV2(TypedDict):
4052
typesize: NotRequired[int]
4153

4254

43-
class BloscConfigV3(TypedDict):
44-
"""Configuration for the V3 Blosc codec"""
45-
46-
cname: CName
47-
clevel: int
48-
shuffle: Shuffle
49-
blocksize: int
50-
typesize: int
51-
52-
53-
class BloscJSON_V3(NamedRequiredConfig[Literal["blosc"], BloscConfigV3]):
54-
"""
55-
The JSON form of the Blosc codec in Zarr V3.
56-
"""
57-
58-
5955
class BloscShuffle(Enum):
6056
"""
6157
Enum for shuffle filter used by blosc.

‎src/zarr/codecs/cast_value.py‎

Lines changed: 3 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212

1313
from collections.abc import Mapping
1414
from dataclasses import dataclass, replace
15-
from typing import TYPE_CHECKING, Final, Literal, TypedDict, cast
15+
from typing import TYPE_CHECKING, Final, TypedDict, cast
1616

1717
import numpy as np
1818

@@ -23,6 +23,8 @@
2323
if TYPE_CHECKING:
2424
from typing import NotRequired, Self
2525

26+
from zarr_metadata.v3.codec.cast_value import OutOfRangeMode, RoundingMode
27+
2628
from zarr.core.array_spec import ArraySpec
2729
from zarr.core.buffer import NDBuffer
2830
from zarr.core.dtype.wrapper import TBaseDType, TBaseScalar, ZDType
@@ -33,17 +35,6 @@ class ScalarMapJSON(TypedDict):
3335
decode: NotRequired[list[tuple[object, object]]]
3436

3537

36-
RoundingMode = Literal[
37-
"nearest-even",
38-
"towards-zero",
39-
"towards-positive",
40-
"towards-negative",
41-
"nearest-away",
42-
]
43-
44-
OutOfRangeMode = Literal["clamp", "wrap"]
45-
46-
4738
class ScalarMap(TypedDict, total=False):
4839
"""
4940
The normalized, in-memory form of a scalar map.

‎src/zarr/core/metadata/v2.py‎

Lines changed: 5 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
import warnings
44
from collections.abc import Iterable, Sequence
55
from functools import cached_property
6-
from typing import TYPE_CHECKING, Any, TypedDict, cast
6+
from typing import TYPE_CHECKING, Any, cast
77

88
from zarr.abc.metadata import Metadata
99
from zarr.abc.numcodec import Numcodec, _is_numcodec
@@ -29,8 +29,11 @@
2929
from dataclasses import dataclass, field, fields, replace
3030

3131
import numpy as np
32+
from zarr_metadata.v2.array import ArrayMetadataV2 as _ArrayMetadataV2
3233

3334
from zarr.core.array_spec import ArrayConfig, ArraySpec
35+
36+
# Re-export the v2 array metadata JSON shape under zarr-python's historical name.
3437
from zarr.core.chunk_key_encodings import parse_separator
3538
from zarr.core.common import (
3639
JSON,
@@ -42,18 +45,9 @@
4245
from zarr.core.config import config, parse_indexing_order
4346
from zarr.core.metadata.common import parse_attributes
4447

45-
46-
class ArrayV2MetadataDict(TypedDict):
47-
"""
48-
A typed dictionary model for Zarr format 2 metadata.
49-
"""
50-
51-
zarr_format: Literal[2]
52-
attributes: dict[str, JSON]
53-
54-
5548
# Union of acceptable types for v2 compressors
5649
type CompressorLikev2 = dict[str, JSON] | Numcodec | None
50+
ArrayV2MetadataDict = _ArrayMetadataV2
5751

5852

5953
@dataclass(frozen=True, kw_only=True)

‎src/zarr/core/metadata/v3.py‎

Lines changed: 18 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,10 @@
33
import json
44
from collections.abc import Iterable, Mapping, Sequence
55
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
77

88
from typing_extensions import TypedDict
9+
from zarr_metadata.v3.array import ArrayMetadataV3, ExtensionFieldV3
910

1011
from zarr.abc.codec import ArrayArrayCodec, ArrayBytesCodec, BytesBytesCodec, Codec
1112
from zarr.abc.metadata import Metadata
@@ -139,14 +140,12 @@ def parse_storage_transformers(data: object) -> tuple[dict[str, JSON], ...]:
139140
)
140141

141142

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`.
148145
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`."""
150149

151150

152151
def check_allowed_extra_field(data: object) -> TypeGuard[AllowedExtraField]:
@@ -421,25 +420,12 @@ def parse_chunk_grid(
421420
raise ValueError(f"Unknown chunk grid name: {name!r}")
422421

423422

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`.
431425
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`."""
443429

444430

445431
"""
@@ -671,6 +657,12 @@ def from_dict(cls, data: dict[str, JSON]) -> Self:
671657
)
672658

673659
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+
"""
674666
out_dict = super().to_dict()
675667
extra_fields = out_dict.pop("extra_fields")
676668
out_dict = out_dict | extra_fields # type: ignore[operator]

0 commit comments

Comments
 (0)