Skip to content

feat(zarr-metadata): export the v3 node types, spec default separators and narrowing helpers - #4638

Merged
d-v-b merged 3 commits into
zarr-developers:mainfrom
d-v-b:feat/zarr-metadata-spec-constants
Nov 16, 2026
Merged

d-v-b merged 3 commits into
zarr-developers:mainfrom
d-v-b:feat/zarr-metadata-spec-constants

Conversation

@d-v-b

@d-v-b d-v-b commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Export more constants, and define useful public type narrowing routines

🤖 AI text below 🤖

Adds ZarrV3NodeType and ZARR_V3_NODE_TYPE, and constants for the separators the spec assumes when one is absent (ZARR_V2_ARRAY_DEFAULT_DIMENSION_SEPARATOR, DEFAULT_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR, V2_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR). Adds TypeIs helpers that narrow an object to a spec value set: is_zarr_v2_array_order, is_zarr_v2_array_dimension_separator and is_zarr_v3_node_type.

Why

pydantic-zarr hardcodes these spec values or re-derives them (get_args(MemoryOrder) followed by cast, node_type == "array" or node_type == "group", a hardcoded "." default). It should import them from zarr-metadata instead.

The agent checked whether a tuple constant alone is enough, using x in ZARR_V2_ARRAY_ORDER with x: object:

  • pyright and pyrefly narrow x to the Literal; mypy and ty do not.
  • A generic is_one_of(value, allowed: tuple[T, ...]) -> TypeIs[T] widens T to str under pyright and mypy.

So each value set gets its own helper.

What changed
  • zarr_metadata.v2.array: ZARR_V2_ARRAY_DEFAULT_DIMENSION_SEPARATOR, is_zarr_v2_array_order, is_zarr_v2_array_dimension_separator.
  • zarr_metadata.v3 (home: the private module v3/_common.py): ZarrV3NodeType (an alias of the format-neutral _hierarchy.NodeType), ZARR_V3_NODE_TYPE, is_zarr_v3_node_type.
  • zarr_metadata.v3.chunk_key_encoding.{default,v2}: DEFAULT_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR ("/") and V2_CHUNK_KEY_ENCODING_DEFAULT_SEPARATOR ("."), each citing the spec line.
  • The top-level zarr_metadata exports the constants and types. The helpers stay in their home modules, like is_node_name_v3.
  • The package now uses these names itself:
    • The v2 array reader drops ("C", "F"), (".", "/"), its "." default and two cast calls.
    • The v3 node reader replaces the private _NODE_TYPES and now returns ZarrV3NodeType | None instead of str | None.
    • Each chunk key encoding's _canonical compares against its default constant.
Considered and left out
  • A shared FloatSpecialFillValue / FLOAT_SPECIAL_FILL_VALUES export. It would need a single public home, and putting it in the float modules makes it value-tied with Float{16,32,64}SpecialFillValue. Those per-width aliases are already public.
  • Public document key sets. ZarrV3GroupMetadataJSON.__required_keys__ | __optional_keys__ already gives them at runtime.
  • A v2 node-name validator, and a codec-definition property for "passes on the data type it receives". These change behaviour, so they are better as separate PRs.
  • The default sharding index codecs. zarr-python picks them; the spec does not define them.
Tests
  • tests/test_spec_values.py: one parametrized test of the three helpers over members and non-members; one test that the v2 array model reads an absent dimension_separator as the default; one test that each chunk key encoding's simplest spelling drops its default separator.
  • test_public_api.py: the new front-door names, and the ZARR_V3_NODE_TYPE/ZarrV3NodeType drift pair.
  • Local runs: 3940 passed and 3 skipped on Python 3.13; pyright (Python 3.11) reports 0 errors over sources and tests; ruff passes; the pre-commit hooks pass; mkdocs build --strict printed no warnings.

🤖 Generated with Claude Code

…s 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
@github-actions github-actions Bot added needs release notes Automatically applied to PRs which haven't added release notes zarr-metadata Specific to the zarr-metadata sub-package labels Nov 16, 2026
@read-the-docs-community

Copy link
Copy Markdown

Documentation build overview

📚 zarr-metadata | 🛠️ Build #35926115 | 📁 Comparing 63fa405 against latest (d8b8543)

  🔍 Preview build  

3 files changed
± api/v2/index.html
± api/v3/index.html
± api/v3/chunk_key_encoding/index.html

@d-v-b
d-v-b merged commit 18d6eb6 into zarr-developers:main Nov 16, 2026
45 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs release notes Automatically applied to PRs which haven't added release notes zarr-metadata Specific to the zarr-metadata sub-package

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant