From 0127f0492b4ae98b0495527dd5faadf4efd64462 Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Mon, 16 Nov 2026 13:13:38 +0100 Subject: [PATCH 1/3] feat(zarr-metadata): export the v3 node types, spec default separators and narrowing helpers Add `ZarrV3NodeType` and `ZARR_V3_NODE_TYPE`; the default separators `ZARR_V2_ARRAY_DEFAULT_DIMENSION_SEPARATOR`, `DEFAULT_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR` and `V2_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR`; and the `TypeIs` helpers `is_zarr_v2_array_order`, `is_zarr_v2_array_dimension_separator` and `is_zarr_v3_node_type`. The v2 array reader, the v3 node reader and the chunk key encodings' canonicalization now use them in place of their own literals, which removes two casts from the v2 array reader. Assisted-by: ClaudeCode:claude-opus-5-5 --- .../src/zarr_metadata/__init__.py | 16 +++- .../src/zarr_metadata/model/_array_v2.py | 41 ++++++---- .../src/zarr_metadata/model/_group_v3.py | 19 ++--- .../src/zarr_metadata/v2/array.py | 23 +++++- .../src/zarr_metadata/v3/__init__.py | 15 +++- .../src/zarr_metadata/v3/_common.py | 29 ++++++- .../v3/_types/chunk_key_encoding.py | 16 ++++ .../v3/chunk_key_encoding/__init__.py | 4 + .../v3/chunk_key_encoding/default.py | 4 +- .../zarr_metadata/v3/chunk_key_encoding/v2.py | 4 +- .../zarr-metadata/tests/test_public_api.py | 7 ++ .../zarr-metadata/tests/test_spec_values.py | 79 +++++++++++++++++++ 12 files changed, 224 insertions(+), 33 deletions(-) create mode 100644 packages/zarr-metadata/tests/test_spec_values.py diff --git a/packages/zarr-metadata/src/zarr_metadata/__init__.py b/packages/zarr-metadata/src/zarr_metadata/__init__.py index 3cde0f7230..1838352c1b 100644 --- a/packages/zarr-metadata/src/zarr_metadata/__init__.py +++ b/packages/zarr-metadata/src/zarr_metadata/__init__.py @@ -38,6 +38,7 @@ from zarr_metadata.problems import MetadataValidationError, ProblemKind, ValidationProblem from zarr_metadata.typed_json import JSONValue from zarr_metadata.v2.array import ( + ZARR_V2_ARRAY_DEFAULT_DIMENSION_SEPARATOR, ZARR_V2_ARRAY_DIMENSION_SEPARATOR, ZARR_V2_ARRAY_METADATA_STORE_KEY, ZARR_V2_ARRAY_ORDER, @@ -65,7 +66,13 @@ ZarrV2GroupMetadataStoreKey, ZarrV2ZGroupJSON, ) -from zarr_metadata.v3 import ZarrV3DeclarationJSON, ZarrV3ExtensionField, ZarrV3NamedConfigJSON +from zarr_metadata.v3 import ( + ZARR_V3_NODE_TYPE, + ZarrV3DeclarationJSON, + ZarrV3ExtensionField, + ZarrV3NamedConfigJSON, + ZarrV3NodeType, +) from zarr_metadata.v3.array import ( ZARR_V3_ARRAY_METADATA_STORE_KEY, ZarrV3ArrayMetadataJSON, @@ -82,6 +89,7 @@ RegularChunkGridName, ) from zarr_metadata.v3.chunk_key_encoding.default import ( + DEFAULT_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR, DEFAULT_CHUNK_KEY_ENCODING_NAME, DEFAULT_CHUNK_KEY_ENCODING_SEPARATOR, DefaultChunkKeyEncodingMetadata, @@ -89,6 +97,7 @@ DefaultChunkKeyEncodingSeparator, ) from zarr_metadata.v3.chunk_key_encoding.v2 import ( + V2_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR, V2_CHUNK_KEY_ENCODING_NAME, V2_CHUNK_KEY_ENCODING_SEPARATOR, V2ChunkKeyEncodingMetadata, @@ -281,6 +290,7 @@ "COMPLEX64_DATA_TYPE_NAME", "COMPLEX128_DATA_TYPE_NAME", "CRC32C_CODEC_NAME", + "DEFAULT_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR", "DEFAULT_CHUNK_KEY_ENCODING_NAME", "DEFAULT_CHUNK_KEY_ENCODING_SEPARATOR", "ENDIANNESS", @@ -309,10 +319,12 @@ "UINT32_DATA_TYPE_NAME", "UINT64_DATA_TYPE_NAME", "UNSET", + "V2_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR", "V2_CHUNK_KEY_ENCODING_NAME", "V2_CHUNK_KEY_ENCODING_SEPARATOR", "VLEN_BYTES_CODEC_NAME", "VLEN_UTF8_CODEC_NAME", + "ZARR_V2_ARRAY_DEFAULT_DIMENSION_SEPARATOR", "ZARR_V2_ARRAY_DIMENSION_SEPARATOR", "ZARR_V2_ARRAY_METADATA_STORE_KEY", "ZARR_V2_ARRAY_ORDER", @@ -322,6 +334,7 @@ "ZARR_V3_ARRAY_METADATA_STORE_KEY", "ZARR_V3_CONSOLIDATED_METADATA_KEY", "ZARR_V3_GROUP_METADATA_STORE_KEY", + "ZARR_V3_NODE_TYPE", "ZSTD_CODEC_NAME", "BloscCName", "BloscCodecMetadata", @@ -444,6 +457,7 @@ "ZarrV3GroupMetadataUpdate", "ZarrV3NamedConfigJSON", "ZarrV3NodeMetadataInput", + "ZarrV3NodeType", "ZstdCodecMetadata", "ZstdCodecName", "__version__", diff --git a/packages/zarr-metadata/src/zarr_metadata/model/_array_v2.py b/packages/zarr-metadata/src/zarr_metadata/model/_array_v2.py index 58795e93a6..2e5ba2930e 100644 --- a/packages/zarr-metadata/src/zarr_metadata/model/_array_v2.py +++ b/packages/zarr-metadata/src/zarr_metadata/model/_array_v2.py @@ -66,10 +66,15 @@ from zarr_metadata.v2._context import ZarrV2Context # noqa: TC001 from zarr_metadata.v2._declaration_json import ZarrV2DataTypeMetadata from zarr_metadata.v2.array import ( + ZARR_V2_ARRAY_DEFAULT_DIMENSION_SEPARATOR, + ZARR_V2_ARRAY_DIMENSION_SEPARATOR, ZARR_V2_ARRAY_METADATA_STORE_KEY, + ZARR_V2_ARRAY_ORDER, ZarrV2ArrayDimensionSeparator, ZarrV2ArrayMetadataJSON, ZarrV2ArrayOrder, + is_zarr_v2_array_dimension_separator, + is_zarr_v2_array_order, ) from zarr_metadata.v2.attributes import ZARR_V2_ATTRIBUTES_STORE_KEY from zarr_metadata.v2.codec import ZarrV2CodecMetadata @@ -239,13 +244,15 @@ def read_array_v2( doc["dtype"], refined["dtype"], found, ZarrV2DataTypeDefinition, context, ("dtype",) ) problems.extend(found) + order: ZarrV2ArrayOrder | None = None if "order" in doc: # Checked after refinement, so a value that only compares equal to # "C" is refused, like every other value outside the set. - order, found = refine_json(doc["order"], ("order",)) - refined["order"] = order - if len(found) != 0 or order not in ("C", "F"): - problems.append(outside_of(("order",), doc["order"], ("C", "F"))) + refined["order"], found = refine_json(doc["order"], ("order",)) + if len(found) == 0 and is_zarr_v2_array_order(refined["order"]): + order = refined["order"] + else: + problems.append(outside_of(("order",), doc["order"], ZARR_V2_ARRAY_ORDER)) compressor: ResolvedDeclaration[ZarrV2CodecDefinition[Any]] | UNSET | None = UNSET if "compressor" in doc: compressor = None @@ -297,12 +304,20 @@ def read_array_v2( problems.extend(found) filters = tuple(read) refined["filters"] = tuple(items) + dimension_separator: ZarrV2ArrayDimensionSeparator = ZARR_V2_ARRAY_DEFAULT_DIMENSION_SEPARATOR if "dimension_separator" in doc: - separator, found = refine_json(doc["dimension_separator"], ("dimension_separator",)) - refined["dimension_separator"] = separator - if len(found) != 0 or separator not in (".", "/"): + refined["dimension_separator"], found = refine_json( + doc["dimension_separator"], ("dimension_separator",) + ) + if len(found) == 0 and is_zarr_v2_array_dimension_separator(refined["dimension_separator"]): + dimension_separator = refined["dimension_separator"] + else: problems.append( - outside_of(("dimension_separator",), doc["dimension_separator"], (".", "/")) + outside_of( + ("dimension_separator",), + doc["dimension_separator"], + ZARR_V2_ARRAY_DIMENSION_SEPARATOR, + ) ) fill_value: JSONValue = None if "fill_value" in doc: @@ -325,16 +340,14 @@ def read_array_v2( filters=filters, problems=within(with_input(problems, doc), at), ) - if len(problems) != 0 or shape is None or chunks is None or attributes is None: + if len(problems) != 0 or shape is None or chunks is None or order is None or attributes is None: return reading, None members = ArrayMembersV2( shape=shape, chunks=chunks, fill_value=fill_value, - order=cast("ZarrV2ArrayOrder", refined["order"]), - dimension_separator=cast( - "ZarrV2ArrayDimensionSeparator", refined.get("dimension_separator", ".") - ), + order=order, + dimension_separator=dimension_separator, attributes=attributes, extra_fields=extra_fields, document={key: refined[key] for key in cast("Mapping[str, object]", doc)}, @@ -897,7 +910,7 @@ def from_key_value( "order": "C", "compressor": None, "filters": None, - "dimension_separator": ".", + "dimension_separator": ZARR_V2_ARRAY_DEFAULT_DIMENSION_SEPARATOR, } ) """The document of `ZarrV2ArrayMetadata.create_default` given nothing: a scalar `|u1` array, without its `zarr_format`.""" diff --git a/packages/zarr-metadata/src/zarr_metadata/model/_group_v3.py b/packages/zarr-metadata/src/zarr_metadata/model/_group_v3.py index 0d0127ad01..9c5d9dc006 100644 --- a/packages/zarr-metadata/src/zarr_metadata/model/_group_v3.py +++ b/packages/zarr-metadata/src/zarr_metadata/model/_group_v3.py @@ -76,7 +76,12 @@ unclaimed_declarations_of, unexpected_keys, ) -from zarr_metadata.v3._common import ZarrV3ExtensionField +from zarr_metadata.v3._common import ( + ZARR_V3_NODE_TYPE, + ZarrV3ExtensionField, + ZarrV3NodeType, + is_zarr_v3_node_type, +) # A runtime import: `get_type_hints` resolves the public signatures. from zarr_metadata.v3._context import ZarrV3Context # noqa: TC001 @@ -872,12 +877,8 @@ def _read_node_v3( return ZarrV3UnknownNodeMetadataReading(problems), None -_NODE_TYPES: Final = ("array", "group") -"""The node types the spec defines.""" - - -def _node_type(value: object) -> tuple[str | None, tuple[ValidationProblem, ...]]: - """The node type `value` declares, one of `_NODE_TYPES`. None, with the problems, when it declares none of them or is not an object. +def _node_type(value: object) -> tuple[ZarrV3NodeType | None, tuple[ValidationProblem, ...]]: + """The node type `value` declares, one of `ZARR_V3_NODE_TYPE`. None, with the problems, when it declares none of them or is not an object. When a document declares no valid node type, its `zarr_format` is checked too, so a document in another format is reported as not v3. @@ -886,7 +887,7 @@ def _node_type(value: object) -> tuple[str | None, tuple[ValidationProblem, ...] return None, not_an_object(value) document = value node_type = document.get("node_type") - if isinstance(node_type, str) and node_type in _NODE_TYPES: + if is_zarr_v3_node_type(node_type): return node_type, () problems = [ *missing_keys(frozenset({"zarr_format"}), document), @@ -895,7 +896,7 @@ def _node_type(value: object) -> tuple[str | None, tuple[ValidationProblem, ...] if "node_type" not in document: problems.append(ValidationProblem(("node_type",), "missing required key", "missing_key")) else: - problems.append(outside_of(("node_type",), node_type, _NODE_TYPES)) + problems.append(outside_of(("node_type",), node_type, ZARR_V3_NODE_TYPE)) return None, with_input(problems, document) diff --git a/packages/zarr-metadata/src/zarr_metadata/v2/array.py b/packages/zarr-metadata/src/zarr_metadata/v2/array.py index d0eacd29eb..4c0665b6b9 100644 --- a/packages/zarr-metadata/src/zarr_metadata/v2/array.py +++ b/packages/zarr-metadata/src/zarr_metadata/v2/array.py @@ -4,7 +4,7 @@ from typing import Annotated, Final, Literal, NotRequired from annotated_types import Ge -from typing_extensions import TypedDict +from typing_extensions import TypedDict, TypeIs from zarr_metadata._common import JSONValue from zarr_metadata.v2._declaration_json import ZarrV2CodecMetadata, ZarrV2DataTypeMetadata @@ -20,6 +20,12 @@ ZARR_V2_ARRAY_ORDER: Final = ("C", "F") """Tuple of permitted values for the `order` field of v2 array metadata.""" + +def is_zarr_v2_array_order(value: object) -> TypeIs[ZarrV2ArrayOrder]: + """Whether `value` is one of `ZARR_V2_ARRAY_ORDER`, narrowing it to `ZarrV2ArrayOrder`.""" + return value in ZARR_V2_ARRAY_ORDER + + ZarrV2ArrayDimensionSeparator = Literal[".", "/"] """Literal type of permitted values for the `dimension_separator` field of v2 array metadata. @@ -32,6 +38,18 @@ ZARR_V2_ARRAY_DIMENSION_SEPARATOR: Final = (".", "/") """Tuple of permitted values for the `dimension_separator` field of v2 array metadata.""" +ZARR_V2_ARRAY_DEFAULT_DIMENSION_SEPARATOR: Final[ZarrV2ArrayDimensionSeparator] = "." +"""The `dimension_separator` a v2 array's metadata means when it has none. + +"If the value is not set, then the default MUST be assumed to be `"."`" +(https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v2/v2.0.rst#L83-L86). +""" + + +def is_zarr_v2_array_dimension_separator(value: object) -> TypeIs[ZarrV2ArrayDimensionSeparator]: + """Whether `value` is one of `ZARR_V2_ARRAY_DIMENSION_SEPARATOR`, narrowing it to `ZarrV2ArrayDimensionSeparator`.""" + return value in ZARR_V2_ARRAY_DIMENSION_SEPARATOR + class ZarrV2ZArrayJSON(TypedDict): """ @@ -148,6 +166,7 @@ class ZarrV2ArrayMetadataJSON(TypedDict, extra_items=JSONValue): __all__ = [ + "ZARR_V2_ARRAY_DEFAULT_DIMENSION_SEPARATOR", "ZARR_V2_ARRAY_DIMENSION_SEPARATOR", "ZARR_V2_ARRAY_METADATA_STORE_KEY", "ZARR_V2_ARRAY_ORDER", @@ -156,4 +175,6 @@ class ZarrV2ArrayMetadataJSON(TypedDict, extra_items=JSONValue): "ZarrV2ArrayMetadataStoreKey", "ZarrV2ArrayOrder", "ZarrV2ZArrayJSON", + "is_zarr_v2_array_dimension_separator", + "is_zarr_v2_array_order", ] diff --git a/packages/zarr-metadata/src/zarr_metadata/v3/__init__.py b/packages/zarr-metadata/src/zarr_metadata/v3/__init__.py index c831630f34..07b943a844 100644 --- a/packages/zarr-metadata/src/zarr_metadata/v3/__init__.py +++ b/packages/zarr-metadata/src/zarr_metadata/v3/__init__.py @@ -1,8 +1,8 @@ """Zarr v3 metadata types, and the front door to the v3 definitions. This module holds the JSON of any declaration (a bare name or a -`ZarrV3NamedConfigJSON` envelope) and the node name and path -types. Each document type is in the submodule for its node: `array`, +`ZarrV3NamedConfigJSON` envelope), the node type, and the node name and +path types. Each document type is in the submodule for its node: `array`, `group` and `consolidated`. The extensions are in `codec`, `data_type`, `chunk_grid` and `chunk_key_encoding`, and the v3 kinds and scopes are in `definition`. @@ -18,7 +18,13 @@ from zarr_metadata._common import ZarrV3NamedConfigJSON from zarr_metadata._renamed import renamed_scope -from zarr_metadata.v3._common import ZarrV3DeclarationJSON, ZarrV3ExtensionField +from zarr_metadata.v3._common import ( + ZARR_V3_NODE_TYPE, + ZarrV3DeclarationJSON, + ZarrV3ExtensionField, + ZarrV3NodeType, + is_zarr_v3_node_type, +) from zarr_metadata.v3._core import RENAMED_SCOPES from zarr_metadata.v3._hierarchy import NodeName, NodePath from zarr_metadata.v3.chunk_grid.rectilinear import RECTILINEAR_CHUNK_GRID @@ -111,6 +117,7 @@ "VLEN_UTF8_CODEC", "ZARR_PYTHON_CONTEXT", "ZARR_PYTHON_RAW_BYTES_DATA_TYPE", + "ZARR_V3_NODE_TYPE", "ZSTD_CODEC", "NodeName", "NodePath", @@ -118,6 +125,8 @@ "ZarrV3DeclarationJSON", "ZarrV3ExtensionField", "ZarrV3NamedConfigJSON", + "ZarrV3NodeType", + "is_zarr_v3_node_type", ] diff --git a/packages/zarr-metadata/src/zarr_metadata/v3/_common.py b/packages/zarr-metadata/src/zarr_metadata/v3/_common.py index 29be28b612..da8f4f511a 100644 --- a/packages/zarr-metadata/src/zarr_metadata/v3/_common.py +++ b/packages/zarr-metadata/src/zarr_metadata/v3/_common.py @@ -1,18 +1,38 @@ -"""The v3 declaration: its JSON type, and the type aliases for members that hold a declaration. +"""The v3 node types, the v3 declaration's JSON type, and the type aliases for members that hold a declaration. This module is private. It sits below both code paths that read a declaration: the model, which checks the members of a document, and the definitions, which read a declaration's configuration. Public consumers import +`ZarrV3NodeType`, `ZARR_V3_NODE_TYPE`, `is_zarr_v3_node_type` and `ZarrV3DeclarationJSON` from `zarr_metadata.v3`, and the aliases from `zarr_metadata.v3.definition`. One declaration is read with `zarr_metadata.definition.resolve`. """ -from typing import TypeAlias +from typing import Final, TypeAlias -from typing_extensions import TypeAliasType +from typing_extensions import TypeAliasType, TypeIs from zarr_metadata._common import JSONValue, ZarrV3NamedConfigJSON +from zarr_metadata._hierarchy import NodeType + +ZarrV3NodeType = NodeType +"""Literal type of permitted values for the `node_type` field of v3 metadata. + +An array's document declares `"array"` +(https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L483-L487) +and a group's `"group"` +(https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L760-L764). +""" + +ZARR_V3_NODE_TYPE: Final = ("array", "group") +"""Tuple of permitted values for the `node_type` field of v3 metadata.""" + + +def is_zarr_v3_node_type(value: object) -> TypeIs[ZarrV3NodeType]: + """Whether `value` is one of `ZARR_V3_NODE_TYPE`, narrowing it to `ZarrV3NodeType`.""" + return value in ZARR_V3_NODE_TYPE + ZarrV3ExtensionField: TypeAlias = JSONValue """The JSON value of an unknown top-level v3 metadata field. @@ -59,12 +79,15 @@ __all__ = [ + "ZARR_V3_NODE_TYPE", "ZarrV3ChunkGridDeclaration", "ZarrV3ChunkKeyEncodingDeclaration", "ZarrV3CodecDeclaration", "ZarrV3DataTypeDeclaration", "ZarrV3DeclarationJSON", "ZarrV3ExtensionField", + "ZarrV3NodeType", "ZarrV3StaticCodecDeclaration", "ZarrV3StorageTransformerDeclaration", + "is_zarr_v3_node_type", ] diff --git a/packages/zarr-metadata/src/zarr_metadata/v3/_types/chunk_key_encoding.py b/packages/zarr-metadata/src/zarr_metadata/v3/_types/chunk_key_encoding.py index f73b73f0cc..4113c6ee07 100644 --- a/packages/zarr-metadata/src/zarr_metadata/v3/_types/chunk_key_encoding.py +++ b/packages/zarr-metadata/src/zarr_metadata/v3/_types/chunk_key_encoding.py @@ -30,6 +30,13 @@ DEFAULT_CHUNK_KEY_ENCODING_SEPARATOR: Final = ("/", ".") """Tuple of permitted values for the `separator` field of the default chunk key encoding.""" +DEFAULT_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR: Final[DefaultChunkKeyEncodingSeparator] = "/" +"""The `separator` the default chunk key encoding means when its configuration has none. + +"If not specified, `separator` defaults to `/`" +(https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/chunk-key-encodings/default/index.rst#L27-L29). +""" + class DefaultChunkKeyEncodingConfiguration(TypedDict, closed=True): """Configuration for the default chunk key encoding. @@ -88,6 +95,13 @@ class DefaultChunkKeyEncodingObject(TypedDict, closed=True): V2_CHUNK_KEY_ENCODING_SEPARATOR: Final = ("/", ".") """Tuple of permitted values for the `separator` field of the v2 chunk key encoding.""" +V2_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR: Final[V2ChunkKeyEncodingSeparator] = "." +"""The `separator` the v2 chunk key encoding means when its configuration has none. + +"If not specified, `separator` defaults to `.`" +(https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/chunk-key-encodings/v2/index.rst#L27-L29). +""" + class V2ChunkKeyEncodingConfiguration(TypedDict, closed=True): """Configuration for the v2 chunk key encoding. @@ -130,8 +144,10 @@ class V2ChunkKeyEncodingObject(TypedDict, closed=True): __all__ = [ + "DEFAULT_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR", "DEFAULT_CHUNK_KEY_ENCODING_NAME", "DEFAULT_CHUNK_KEY_ENCODING_SEPARATOR", + "V2_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR", "V2_CHUNK_KEY_ENCODING_NAME", "V2_CHUNK_KEY_ENCODING_SEPARATOR", "DefaultChunkKeyEncodingConfiguration", diff --git a/packages/zarr-metadata/src/zarr_metadata/v3/chunk_key_encoding/__init__.py b/packages/zarr-metadata/src/zarr_metadata/v3/chunk_key_encoding/__init__.py index 7162840872..e8563fa624 100644 --- a/packages/zarr-metadata/src/zarr_metadata/v3/chunk_key_encoding/__init__.py +++ b/packages/zarr-metadata/src/zarr_metadata/v3/chunk_key_encoding/__init__.py @@ -20,6 +20,7 @@ from zarr_metadata.v3.chunk_key_encoding.default import ( DEFAULT_CHUNK_KEY_ENCODING, + DEFAULT_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR, DEFAULT_CHUNK_KEY_ENCODING_NAME, DEFAULT_CHUNK_KEY_ENCODING_SEPARATOR, DefaultChunkKeyEncodingConfiguration, @@ -30,6 +31,7 @@ ) from zarr_metadata.v3.chunk_key_encoding.v2 import ( V2_CHUNK_KEY_ENCODING, + V2_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR, V2_CHUNK_KEY_ENCODING_NAME, V2_CHUNK_KEY_ENCODING_SEPARATOR, V2ChunkKeyEncodingConfiguration, @@ -41,9 +43,11 @@ __all__ = [ "DEFAULT_CHUNK_KEY_ENCODING", + "DEFAULT_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR", "DEFAULT_CHUNK_KEY_ENCODING_NAME", "DEFAULT_CHUNK_KEY_ENCODING_SEPARATOR", "V2_CHUNK_KEY_ENCODING", + "V2_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR", "V2_CHUNK_KEY_ENCODING_NAME", "V2_CHUNK_KEY_ENCODING_SEPARATOR", "DefaultChunkKeyEncodingConfiguration", diff --git a/packages/zarr-metadata/src/zarr_metadata/v3/chunk_key_encoding/default.py b/packages/zarr-metadata/src/zarr_metadata/v3/chunk_key_encoding/default.py index 693c4c4720..a92aad7fa4 100644 --- a/packages/zarr-metadata/src/zarr_metadata/v3/chunk_key_encoding/default.py +++ b/packages/zarr-metadata/src/zarr_metadata/v3/chunk_key_encoding/default.py @@ -11,6 +11,7 @@ from zarr_metadata.v3._definition import ChunkKeyEncodingDefinition from zarr_metadata.v3._types.chunk_key_encoding import ( + DEFAULT_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR, DEFAULT_CHUNK_KEY_ENCODING_NAME, DEFAULT_CHUNK_KEY_ENCODING_SEPARATOR, DefaultChunkKeyEncodingConfiguration, @@ -30,7 +31,7 @@ def _canonical( (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/chunk-key-encodings/default/index.rst#L27-L29), so the two spellings describe the same encoding. """ - if configuration.get("separator") != "/": + if configuration.get("separator") != DEFAULT_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR: return configuration return {} @@ -45,6 +46,7 @@ def _canonical( __all__ = [ "DEFAULT_CHUNK_KEY_ENCODING", + "DEFAULT_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR", "DEFAULT_CHUNK_KEY_ENCODING_NAME", "DEFAULT_CHUNK_KEY_ENCODING_SEPARATOR", "DefaultChunkKeyEncodingConfiguration", diff --git a/packages/zarr-metadata/src/zarr_metadata/v3/chunk_key_encoding/v2.py b/packages/zarr-metadata/src/zarr_metadata/v3/chunk_key_encoding/v2.py index 24c458d102..752e553053 100644 --- a/packages/zarr-metadata/src/zarr_metadata/v3/chunk_key_encoding/v2.py +++ b/packages/zarr-metadata/src/zarr_metadata/v3/chunk_key_encoding/v2.py @@ -17,6 +17,7 @@ from zarr_metadata.v3._definition import ChunkKeyEncodingDefinition from zarr_metadata.v3._types.chunk_key_encoding import ( + V2_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR, V2_CHUNK_KEY_ENCODING_NAME, V2_CHUNK_KEY_ENCODING_SEPARATOR, V2ChunkKeyEncodingConfiguration, @@ -34,7 +35,7 @@ def _canonical(configuration: V2ChunkKeyEncodingConfiguration) -> V2ChunkKeyEnco (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/chunk-key-encodings/v2/index.rst#L27-L29), so the two spellings describe the same encoding. """ - if configuration.get("separator") != ".": + if configuration.get("separator") != V2_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR: return configuration return {} @@ -49,6 +50,7 @@ def _canonical(configuration: V2ChunkKeyEncodingConfiguration) -> V2ChunkKeyEnco __all__ = [ "V2_CHUNK_KEY_ENCODING", + "V2_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR", "V2_CHUNK_KEY_ENCODING_NAME", "V2_CHUNK_KEY_ENCODING_SEPARATOR", "V2ChunkKeyEncodingConfiguration", diff --git a/packages/zarr-metadata/tests/test_public_api.py b/packages/zarr-metadata/tests/test_public_api.py index e09dc0a0a8..71f7b8064e 100644 --- a/packages/zarr-metadata/tests/test_public_api.py +++ b/packages/zarr-metadata/tests/test_public_api.py @@ -180,6 +180,8 @@ def _group_rank(s: str) -> int: "ZarrV2ArrayOrder", "ZARR_V2_ARRAY_DIMENSION_SEPARATOR", "ZarrV2ArrayDimensionSeparator", + "ZARR_V3_NODE_TYPE", + "ZarrV3NodeType", "ENDIANNESS", "Endianness", "BYTES_CODEC_NAME", @@ -227,6 +229,10 @@ def _group_rank(s: str) -> int: "V2_CHUNK_KEY_ENCODING_SEPARATOR", "V2ChunkKeyEncodingSeparator", "NUMPY_TIME_UNIT", + # Spec defaults: the value an absent member means. + "ZARR_V2_ARRAY_DEFAULT_DIMENSION_SEPARATOR", + "DEFAULT_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR", + "V2_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR", "NumpyTimeUnit", ] @@ -448,6 +454,7 @@ def test_promoted_pairs_drift() -> None: (zm.ZARR_V2_ARRAY_DIMENSION_SEPARATOR, zm.ZarrV2ArrayDimensionSeparator), (zm.DEFAULT_CHUNK_KEY_ENCODING_SEPARATOR, zm.DefaultChunkKeyEncodingSeparator), (zm.V2_CHUNK_KEY_ENCODING_SEPARATOR, zm.V2ChunkKeyEncodingSeparator), + (zm.ZARR_V3_NODE_TYPE, zm.ZarrV3NodeType), ] for const, lit in pairs: assert set(const) == set(get_args(lit)) diff --git a/packages/zarr-metadata/tests/test_spec_values.py b/packages/zarr-metadata/tests/test_spec_values.py new file mode 100644 index 0000000000..d064d4bfc7 --- /dev/null +++ b/packages/zarr-metadata/tests/test_spec_values.py @@ -0,0 +1,79 @@ +"""Test the spec's closed value sets and defaults, as the narrowing helpers and default constants spell them.""" + +from collections.abc import Callable + +import pytest + +from zarr_metadata import ( + DEFAULT_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR, + DEFAULT_CHUNK_KEY_ENCODING_NAME, + DEFAULT_CHUNK_KEY_ENCODING_SEPARATOR, + UNSET, + V2_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR, + V2_CHUNK_KEY_ENCODING_NAME, + V2_CHUNK_KEY_ENCODING_SEPARATOR, + ZARR_V2_ARRAY_DEFAULT_DIMENSION_SEPARATOR, + ZARR_V2_ARRAY_DIMENSION_SEPARATOR, + ZarrV2ArrayMetadata, +) +from zarr_metadata.definition import canonical_of, resolve +from zarr_metadata.v2.array import is_zarr_v2_array_dimension_separator, is_zarr_v2_array_order +from zarr_metadata.v3 import is_zarr_v3_node_type +from zarr_metadata.v3.definition import CORE_CONTEXT, ChunkKeyEncodingDefinition + + +@pytest.mark.parametrize( + ("helper", "value", "expected"), + [ + (is_zarr_v2_array_order, "C", True), + (is_zarr_v2_array_order, "F", True), + (is_zarr_v2_array_order, "c", False), + (is_zarr_v2_array_order, "A", False), + (is_zarr_v2_array_order, None, False), + (is_zarr_v2_array_dimension_separator, ".", True), + (is_zarr_v2_array_dimension_separator, "/", True), + (is_zarr_v2_array_dimension_separator, "\\", False), + (is_zarr_v2_array_dimension_separator, None, False), + (is_zarr_v3_node_type, "array", True), + (is_zarr_v3_node_type, "group", True), + (is_zarr_v3_node_type, "Array", False), + (is_zarr_v3_node_type, ("array",), False), + (is_zarr_v3_node_type, 3, False), + ], +) +def test_narrowing_helpers(helper: Callable[[object], bool], value: object, expected: bool) -> None: + """Each helper accepts exactly the members of its value set.""" + assert helper(value) is expected + + +def test_v2_array_default_dimension_separator() -> None: + """An array document without a `dimension_separator` means the default one, which is a permitted separator.""" + assert ZARR_V2_ARRAY_DEFAULT_DIMENSION_SEPARATOR in ZARR_V2_ARRAY_DIMENSION_SEPARATOR + metadata = ZarrV2ArrayMetadata.create_default(dimension_separator=UNSET) + assert "dimension_separator" not in metadata.to_json() + assert metadata.dimension_separator == ZARR_V2_ARRAY_DEFAULT_DIMENSION_SEPARATOR + + +@pytest.mark.parametrize( + ("name", "default", "permitted"), + [ + ( + DEFAULT_CHUNK_KEY_ENCODING_NAME, + DEFAULT_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR, + DEFAULT_CHUNK_KEY_ENCODING_SEPARATOR, + ), + ( + V2_CHUNK_KEY_ENCODING_NAME, + V2_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR, + V2_CHUNK_KEY_ENCODING_SEPARATOR, + ), + ], +) +def test_chunk_key_encoding_default_separator( + name: str, default: str, permitted: tuple[str, ...] +) -> None: + """A chunk key encoding's default separator is permitted, and its simplest spelling omits it.""" + assert default in permitted + declaration = {"name": name, "configuration": {"separator": default}} + resolved, problems = resolve(declaration, ChunkKeyEncodingDefinition, CORE_CONTEXT) + assert canonical_of(resolved, problems) == {"name": name} From bd7651ed44e27e5735961f0b39ca8df0f4bde392 Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Mon, 16 Nov 2026 13:14:37 +0100 Subject: [PATCH 2/3] docs(zarr-metadata): add the changelog fragment for the spec constants Assisted-by: ClaudeCode:claude-opus-5-5 --- packages/zarr-metadata/changes/448.feature.md | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 packages/zarr-metadata/changes/448.feature.md diff --git a/packages/zarr-metadata/changes/448.feature.md b/packages/zarr-metadata/changes/448.feature.md new file mode 100644 index 0000000000..759b4bac5f --- /dev/null +++ b/packages/zarr-metadata/changes/448.feature.md @@ -0,0 +1,8 @@ +Add `ZarrV3NodeType` and `ZARR_V3_NODE_TYPE` for the `node_type` member of a +v3 document, and constants for the separator the spec assumes when one is +absent: `ZARR_V2_ARRAY_DEFAULT_DIMENSION_SEPARATOR` (`"."`), +`DEFAULT_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR` (`"/"`) and +`V2_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR` (`"."`). The `TypeIs` functions +`is_zarr_v2_array_order`, `is_zarr_v2_array_dimension_separator` (in +`zarr_metadata.v2.array`) and `is_zarr_v3_node_type` (in `zarr_metadata.v3`) +narrow any value to the matching `Literal` type, under every type checker. From 63fa4054c1cb55bf0e0f7f29c980733a06fea9f5 Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Mon, 16 Nov 2026 13:22:58 +0100 Subject: [PATCH 3/3] docs(zarr-metadata): name the changelog fragment after the upstream PR Assisted-by: ClaudeCode:claude-opus-5-5 --- .../zarr-metadata/changes/{448.feature.md => 4638.feature.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename packages/zarr-metadata/changes/{448.feature.md => 4638.feature.md} (100%) diff --git a/packages/zarr-metadata/changes/448.feature.md b/packages/zarr-metadata/changes/4638.feature.md similarity index 100% rename from packages/zarr-metadata/changes/448.feature.md rename to packages/zarr-metadata/changes/4638.feature.md