Skip to content

Commit 5bd5f47

Browse files
d-v-bclaude
d-v-b
and
claude
committed
feat(zarr-metadata): promote curated front door to top-level public API
Promote a curated set of names to the top-level `zarr_metadata` namespace so consumers can import spec types directly (e.g. `from zarr_metadata import ArrayMetadataV3, ShardingIndexLocation, BLOSC_CNAME`). Deep submodule paths continue to work unchanged. Several promoted names get clearer spellings now that they appear bare at the top level: `Endian`->`Endianness`, `IndexLocation`->`ShardingIndexLocation`, `RoundingMode`->`CastRoundingMode`, `OutOfRangeMode`->`CastOutOfRangeMode`, `DateTimeUnit`->`NumpyTimeUnit`, `NamedConfig`->`NamedConfigV3`, and `MetadataFieldV3`->`MetadataV3` (matching the name `zarrs` uses for this `name`-or-`{name, configuration}` shape). Also adds the `NUMPY_TIME_UNIT` runtime constant paired with the `NumpyTimeUnit` Literal. Scoped to packages/zarr-metadata only; no zarr-python changes, so no deprecation shims are needed (zarr-python does not yet depend on zarr-metadata). A follow-up zarr-python PR will consume these names. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 260f89b commit 5bd5f47

15 files changed

Lines changed: 606 additions & 56 deletions

File tree

‎packages/zarr-metadata/changes/4083.feature.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Promoted a curated "front door" of names to the top-level `zarr_metadata`
2+
namespace, so consumers can write e.g. `from zarr_metadata import
3+
ArrayMetadataV3, ShardingIndexLocation, BLOSC_CNAME` instead of importing from
4+
deep submodule paths. The front door covers every metadata-document TypedDict,
5+
each codec/chunk-grid/chunk-key-encoding canonical type, the full data-type
6+
trio for every dtype, and every constant + `Literal` pair. Deep submodule paths
7+
continue to work unchanged.
8+
9+
Several promoted names were given clearer, less ambiguous spellings than their
10+
deep-module names, since they now appear bare at the top level:
11+
`Endian`/`ENDIAN` → `Endianness`/`ENDIANNESS`,
12+
`IndexLocation`/`INDEX_LOCATION` → `ShardingIndexLocation`/`SHARDING_INDEX_LOCATION`,
13+
`RoundingMode`/`ROUNDING_MODE` → `CastRoundingMode`/`CAST_ROUNDING_MODE`,
14+
`OutOfRangeMode`/`OUT_OF_RANGE_MODE` → `CastOutOfRangeMode`/`CAST_OUT_OF_RANGE_MODE`,
15+
`DateTimeUnit` → `NumpyTimeUnit`,
16+
`NamedConfig` → `NamedConfigV3`, and
17+
`MetadataFieldV3` → `MetadataV3` (matching the name `zarrs` uses for this
18+
`name`-or-`{name, configuration}` shape).
19+
20+
Also added the `NUMPY_TIME_UNIT` runtime constant (a `Final` tuple paired with
21+
the `NumpyTimeUnit` Literal) in `zarr_metadata.v3.data_type.numpy_timedelta64`.

‎packages/zarr-metadata/src/zarr_metadata/__init__.py‎

Lines changed: 291 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
from importlib.metadata import version
22

3-
from zarr_metadata._common import JSONValue, NamedConfig
3+
from zarr_metadata._common import JSONValue, NamedConfigV3
44
from zarr_metadata.v2.array import (
5+
ARRAY_DIMENSION_SEPARATOR_V2,
6+
ARRAY_ORDER_V2,
57
ArrayDimensionSeparatorV2,
68
ArrayMetadataV2,
79
ArrayMetadataV2Partial,
@@ -13,35 +15,320 @@
1315
from zarr_metadata.v2.codec import CodecMetadataV2
1416
from zarr_metadata.v2.consolidated import ConsolidatedMetadataV2
1517
from zarr_metadata.v2.group import GroupMetadataV2, GroupMetadataV2Partial, ZGroupMetadata
16-
from zarr_metadata.v3._common import MetadataFieldV3
18+
from zarr_metadata.v3._common import MetadataV3
1719
from zarr_metadata.v3.array import ArrayMetadataV3, ArrayMetadataV3Partial, ExtensionFieldV3
20+
from zarr_metadata.v3.chunk_grid.rectilinear import (
21+
RECTILINEAR_CHUNK_GRID_NAME,
22+
RectilinearChunkGridMetadata,
23+
RectilinearChunkGridName,
24+
)
25+
from zarr_metadata.v3.chunk_grid.regular import (
26+
REGULAR_CHUNK_GRID_NAME,
27+
RegularChunkGridMetadata,
28+
RegularChunkGridName,
29+
)
30+
from zarr_metadata.v3.chunk_key_encoding.default import (
31+
DEFAULT_CHUNK_KEY_ENCODING_NAME,
32+
DEFAULT_CHUNK_KEY_ENCODING_SEPARATOR,
33+
DefaultChunkKeyEncodingMetadata,
34+
DefaultChunkKeyEncodingName,
35+
DefaultChunkKeyEncodingSeparator,
36+
)
37+
from zarr_metadata.v3.chunk_key_encoding.v2 import (
38+
V2_CHUNK_KEY_ENCODING_NAME,
39+
V2_CHUNK_KEY_ENCODING_SEPARATOR,
40+
V2ChunkKeyEncodingMetadata,
41+
V2ChunkKeyEncodingName,
42+
V2ChunkKeyEncodingSeparator,
43+
)
44+
from zarr_metadata.v3.codec.blosc import (
45+
BLOSC_CNAME,
46+
BLOSC_CODEC_NAME,
47+
BLOSC_SHUFFLE,
48+
BloscCName,
49+
BloscCodecMetadata,
50+
BloscCodecName,
51+
BloscShuffle,
52+
)
53+
from zarr_metadata.v3.codec.bytes import (
54+
BYTES_CODEC_NAME,
55+
ENDIANNESS,
56+
BytesCodecMetadata,
57+
BytesCodecName,
58+
Endianness,
59+
)
60+
from zarr_metadata.v3.codec.cast_value import (
61+
CAST_OUT_OF_RANGE_MODE,
62+
CAST_ROUNDING_MODE,
63+
CAST_VALUE_CODEC_NAME,
64+
CastOutOfRangeMode,
65+
CastRoundingMode,
66+
CastValueCodecMetadata,
67+
CastValueCodecName,
68+
)
69+
from zarr_metadata.v3.codec.crc32c import CRC32C_CODEC_NAME, Crc32cCodecMetadata, Crc32cCodecName
70+
from zarr_metadata.v3.codec.gzip import GZIP_CODEC_NAME, GzipCodecMetadata, GzipCodecName
71+
from zarr_metadata.v3.codec.scale_offset import (
72+
SCALE_OFFSET_CODEC_NAME,
73+
ScaleOffsetCodecMetadata,
74+
ScaleOffsetCodecName,
75+
)
76+
from zarr_metadata.v3.codec.sharding_indexed import (
77+
SHARDING_INDEX_LOCATION,
78+
SHARDING_INDEXED_CODEC_NAME,
79+
ShardingIndexedCodecMetadata,
80+
ShardingIndexedCodecName,
81+
ShardingIndexLocation,
82+
)
83+
from zarr_metadata.v3.codec.transpose import (
84+
TRANSPOSE_CODEC_NAME,
85+
TransposeCodecMetadata,
86+
TransposeCodecName,
87+
)
88+
from zarr_metadata.v3.codec.zstd import ZSTD_CODEC_NAME, ZstdCodecMetadata, ZstdCodecName
1889
from zarr_metadata.v3.consolidated import ConsolidatedMetadataV3
90+
from zarr_metadata.v3.data_type.bool import (
91+
BOOL_DATA_TYPE_NAME,
92+
BoolDataTypeName,
93+
BoolFillValue,
94+
)
95+
from zarr_metadata.v3.data_type.bytes import (
96+
BYTES_DATA_TYPE_NAME,
97+
BytesDataTypeName,
98+
BytesFillValue,
99+
)
100+
from zarr_metadata.v3.data_type.complex64 import (
101+
COMPLEX64_DATA_TYPE_NAME,
102+
Complex64DataTypeName,
103+
Complex64FillValue,
104+
)
105+
from zarr_metadata.v3.data_type.complex128 import (
106+
COMPLEX128_DATA_TYPE_NAME,
107+
Complex128DataTypeName,
108+
Complex128FillValue,
109+
)
110+
from zarr_metadata.v3.data_type.float16 import (
111+
FLOAT16_DATA_TYPE_NAME,
112+
Float16DataTypeName,
113+
Float16FillValue,
114+
)
115+
from zarr_metadata.v3.data_type.float32 import (
116+
FLOAT32_DATA_TYPE_NAME,
117+
Float32DataTypeName,
118+
Float32FillValue,
119+
)
120+
from zarr_metadata.v3.data_type.float64 import (
121+
FLOAT64_DATA_TYPE_NAME,
122+
Float64DataTypeName,
123+
Float64FillValue,
124+
)
125+
from zarr_metadata.v3.data_type.int8 import (
126+
INT8_DATA_TYPE_NAME,
127+
Int8DataTypeName,
128+
Int8FillValue,
129+
)
130+
from zarr_metadata.v3.data_type.int16 import (
131+
INT16_DATA_TYPE_NAME,
132+
Int16DataTypeName,
133+
Int16FillValue,
134+
)
135+
from zarr_metadata.v3.data_type.int32 import (
136+
INT32_DATA_TYPE_NAME,
137+
Int32DataTypeName,
138+
Int32FillValue,
139+
)
140+
from zarr_metadata.v3.data_type.int64 import (
141+
INT64_DATA_TYPE_NAME,
142+
Int64DataTypeName,
143+
Int64FillValue,
144+
)
145+
from zarr_metadata.v3.data_type.numpy_datetime64 import (
146+
NUMPY_DATETIME64_DATA_TYPE_NAME,
147+
NumpyDatetime64DataTypeName,
148+
NumpyDatetime64FillValue,
149+
)
150+
from zarr_metadata.v3.data_type.numpy_timedelta64 import (
151+
NUMPY_TIME_UNIT,
152+
NUMPY_TIMEDELTA64_DATA_TYPE_NAME,
153+
NumpyTimedelta64DataTypeName,
154+
NumpyTimedelta64FillValue,
155+
NumpyTimeUnit,
156+
)
157+
from zarr_metadata.v3.data_type.raw import RawBytesDataTypeName, RawBytesFillValue
158+
from zarr_metadata.v3.data_type.string import (
159+
STRING_DATA_TYPE_NAME,
160+
StringDataTypeName,
161+
StringFillValue,
162+
)
163+
from zarr_metadata.v3.data_type.struct import (
164+
STRUCT_DATA_TYPE_NAME,
165+
StructDataTypeName,
166+
StructFillValue,
167+
)
168+
from zarr_metadata.v3.data_type.uint8 import (
169+
UINT8_DATA_TYPE_NAME,
170+
Uint8DataTypeName,
171+
Uint8FillValue,
172+
)
173+
from zarr_metadata.v3.data_type.uint16 import (
174+
UINT16_DATA_TYPE_NAME,
175+
Uint16DataTypeName,
176+
Uint16FillValue,
177+
)
178+
from zarr_metadata.v3.data_type.uint32 import (
179+
UINT32_DATA_TYPE_NAME,
180+
Uint32DataTypeName,
181+
Uint32FillValue,
182+
)
183+
from zarr_metadata.v3.data_type.uint64 import (
184+
UINT64_DATA_TYPE_NAME,
185+
Uint64DataTypeName,
186+
Uint64FillValue,
187+
)
19188
from zarr_metadata.v3.group import GroupMetadataV3, GroupMetadataV3Partial
20189

21190
__version__ = version("zarr-metadata")
22191

23192

24193
__all__ = [
194+
"ARRAY_DIMENSION_SEPARATOR_V2",
195+
"ARRAY_ORDER_V2",
196+
"BLOSC_CNAME",
197+
"BLOSC_CODEC_NAME",
198+
"BLOSC_SHUFFLE",
199+
"BOOL_DATA_TYPE_NAME",
200+
"BYTES_CODEC_NAME",
201+
"BYTES_DATA_TYPE_NAME",
202+
"CAST_OUT_OF_RANGE_MODE",
203+
"CAST_ROUNDING_MODE",
204+
"CAST_VALUE_CODEC_NAME",
205+
"COMPLEX64_DATA_TYPE_NAME",
206+
"COMPLEX128_DATA_TYPE_NAME",
207+
"CRC32C_CODEC_NAME",
208+
"DEFAULT_CHUNK_KEY_ENCODING_NAME",
209+
"DEFAULT_CHUNK_KEY_ENCODING_SEPARATOR",
210+
"ENDIANNESS",
211+
"FLOAT16_DATA_TYPE_NAME",
212+
"FLOAT32_DATA_TYPE_NAME",
213+
"FLOAT64_DATA_TYPE_NAME",
214+
"GZIP_CODEC_NAME",
215+
"INT8_DATA_TYPE_NAME",
216+
"INT16_DATA_TYPE_NAME",
217+
"INT32_DATA_TYPE_NAME",
218+
"INT64_DATA_TYPE_NAME",
219+
"NUMPY_DATETIME64_DATA_TYPE_NAME",
220+
"NUMPY_TIMEDELTA64_DATA_TYPE_NAME",
221+
"NUMPY_TIME_UNIT",
222+
"RECTILINEAR_CHUNK_GRID_NAME",
223+
"REGULAR_CHUNK_GRID_NAME",
224+
"SCALE_OFFSET_CODEC_NAME",
225+
"SHARDING_INDEXED_CODEC_NAME",
226+
"SHARDING_INDEX_LOCATION",
227+
"STRING_DATA_TYPE_NAME",
228+
"STRUCT_DATA_TYPE_NAME",
229+
"TRANSPOSE_CODEC_NAME",
230+
"UINT8_DATA_TYPE_NAME",
231+
"UINT16_DATA_TYPE_NAME",
232+
"UINT32_DATA_TYPE_NAME",
233+
"UINT64_DATA_TYPE_NAME",
234+
"V2_CHUNK_KEY_ENCODING_NAME",
235+
"V2_CHUNK_KEY_ENCODING_SEPARATOR",
236+
"ZSTD_CODEC_NAME",
25237
"ArrayDimensionSeparatorV2",
26238
"ArrayMetadataV2",
27239
"ArrayMetadataV2Partial",
28240
"ArrayMetadataV3",
29241
"ArrayMetadataV3Partial",
30242
"ArrayOrderV2",
243+
"BloscCName",
244+
"BloscCodecMetadata",
245+
"BloscCodecName",
246+
"BloscShuffle",
247+
"BoolDataTypeName",
248+
"BoolFillValue",
249+
"BytesCodecMetadata",
250+
"BytesCodecName",
251+
"BytesDataTypeName",
252+
"BytesFillValue",
253+
"CastOutOfRangeMode",
254+
"CastRoundingMode",
255+
"CastValueCodecMetadata",
256+
"CastValueCodecName",
31257
"CodecMetadataV2",
258+
"Complex64DataTypeName",
259+
"Complex64FillValue",
260+
"Complex128DataTypeName",
261+
"Complex128FillValue",
32262
"ConsolidatedMetadataV2",
33263
"ConsolidatedMetadataV3",
264+
"Crc32cCodecMetadata",
265+
"Crc32cCodecName",
34266
"DataTypeMetadataV2",
267+
"DefaultChunkKeyEncodingMetadata",
268+
"DefaultChunkKeyEncodingName",
269+
"DefaultChunkKeyEncodingSeparator",
270+
"Endianness",
35271
"ExtensionFieldV3",
272+
"Float16DataTypeName",
273+
"Float16FillValue",
274+
"Float32DataTypeName",
275+
"Float32FillValue",
276+
"Float64DataTypeName",
277+
"Float64FillValue",
36278
"GroupMetadataV2",
37279
"GroupMetadataV2Partial",
38280
"GroupMetadataV3",
39281
"GroupMetadataV3Partial",
282+
"GzipCodecMetadata",
283+
"GzipCodecName",
284+
"Int8DataTypeName",
285+
"Int8FillValue",
286+
"Int16DataTypeName",
287+
"Int16FillValue",
288+
"Int32DataTypeName",
289+
"Int32FillValue",
290+
"Int64DataTypeName",
291+
"Int64FillValue",
40292
"JSONValue",
41-
"MetadataFieldV3",
42-
"NamedConfig",
293+
"MetadataV3",
294+
"NamedConfigV3",
295+
"NumpyDatetime64DataTypeName",
296+
"NumpyDatetime64FillValue",
297+
"NumpyTimeUnit",
298+
"NumpyTimedelta64DataTypeName",
299+
"NumpyTimedelta64FillValue",
300+
"RawBytesDataTypeName",
301+
"RawBytesFillValue",
302+
"RectilinearChunkGridMetadata",
303+
"RectilinearChunkGridName",
304+
"RegularChunkGridMetadata",
305+
"RegularChunkGridName",
306+
"ScaleOffsetCodecMetadata",
307+
"ScaleOffsetCodecName",
308+
"ShardingIndexLocation",
309+
"ShardingIndexedCodecMetadata",
310+
"ShardingIndexedCodecName",
311+
"StringDataTypeName",
312+
"StringFillValue",
313+
"StructDataTypeName",
314+
"StructFillValue",
315+
"TransposeCodecMetadata",
316+
"TransposeCodecName",
317+
"Uint8DataTypeName",
318+
"Uint8FillValue",
319+
"Uint16DataTypeName",
320+
"Uint16FillValue",
321+
"Uint32DataTypeName",
322+
"Uint32FillValue",
323+
"Uint64DataTypeName",
324+
"Uint64FillValue",
325+
"V2ChunkKeyEncodingMetadata",
326+
"V2ChunkKeyEncodingName",
327+
"V2ChunkKeyEncodingSeparator",
43328
"ZArrayMetadata",
44329
"ZAttrsMetadata",
45330
"ZGroupMetadata",
331+
"ZstdCodecMetadata",
332+
"ZstdCodecName",
46333
"__version__",
47334
]

‎packages/zarr-metadata/src/zarr_metadata/_common.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424
"""
2525

2626

27-
class NamedConfig(TypedDict):
27+
class NamedConfigV3(TypedDict):
2828
"""
2929
Externally-tagged union member for a metadata field.
3030

‎packages/zarr-metadata/src/zarr_metadata/v3/__init__.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
"""Zarr v3 metadata types."""
22

3-
from zarr_metadata.v3._common import MetadataFieldV3
3+
from zarr_metadata.v3._common import MetadataV3
44
from zarr_metadata.v3.array import ArrayMetadataV3, ExtensionFieldV3
55
from zarr_metadata.v3.consolidated import ConsolidatedMetadataV3
66
from zarr_metadata.v3.group import GroupMetadataV3
@@ -10,5 +10,5 @@
1010
"ConsolidatedMetadataV3",
1111
"ExtensionFieldV3",
1212
"GroupMetadataV3",
13-
"MetadataFieldV3",
13+
"MetadataV3",
1414
]

0 commit comments

Comments
 (0)