feat(zarr-metadata): check, JSON against a TypedDict as the typing spec reads it

[d-v-b]

🤖 AI text below 🤖

zarr_metadata.typed_json.check(value, SomeTypedDict) type-checks a JSON value against any TypedDict (the package's own document and configuration types, or a caller's) and gives back a value of it, or None, with every problem located. It stands on its own: nothing it imports is zarr_metadata.model's.

from zarr_metadata import ZarrV3ArrayMetadataJSON
from zarr_metadata.typed_json import check

document, problems = check(json.loads(raw), ZarrV3ArrayMetadataJSON)

A TypedDict, read as the typing spec defines it, whatever the runtime's attributes say:

• A key is required by its own Required/NotRequired, or else by the total of the class that declared it, read off the evaluated annotations. __required_keys__ cannot see a qualifier written as a string, which under from __future__ import annotations is every one.
• closed, extra_items and openness come from the class, or from its bases when it says neither, which the runtime does not record. A key a closed TypedDict does not declare is reported as the new problem kind unknown_key and left out, and the value still comes back.
• Each annotation is evaluated in the module of the class that wrote it.
• typeddict_keys(T) says what a TypedDict declares.

Surveyed first. How pydantic, typing-inspection, typeguard, cattrs, msgspec, trycast, typedload and beartype check TypedDicts, and what their test suites and typing_extensions' and CPython's catch. What that decided here:

• get_type_hints reads what a subclass inherited in the subclass's module, so a base's x: Foo reads as the subclass's Foo, a silent wrong answer, and a string nested in a base's annotation fails to resolve (CPython #90531). The checker evaluates each class's own keys in its own module. pydantic and typeguard get the first case right; none of the libraries surveyed gets the second.
• A union of TypedDicts tagged by a Literal key is read by the branch the tag names, so a gzip with a bad level is reported as a gzip rather than as four blosc problems. An untagged union is reported by its closest branch, and of clean TypedDict branches the one declaring the most of the value's keys reads it.
• A key both Required and NotRequired, and runtime keys that are not the annotated keys, are a TypeError. A recursive alias is named in a message rather than expanded.
• Where this is ahead of every library surveyed, tests pin it: inherited openness, qualifiers under PEP 563 and under Annotated and ReadOnly, recursive aliases.
• Generic TypedDicts are refused: no library surveyed substitutes type arguments through bases correctly, and a refusal beats a silent pass.
• check(None, SomeTypedDict) refuses JSON's null as not an object, rather than answering no value and no problem.

JSON and its problems move below the model, from zarr_metadata.model._validation into zarr_metadata._json: the problem types, MetadataValidationError, refine_json and refine_user_data, validate_json, is_json, parse_json and arrays_to_tuples. The checker reports with them, and the model is one of the checker's users, so they sit below both. zarr_metadata.model exports every name it did.

Every TypedDict the package declares compiles, and a test says so. The v2 dtype alias names itself through a string, which is now resolved in the alias's module.

Tests. Unit tests per shape and per TypedDict rule, with every declaration read under both typing.TypedDict and typing_extensions.TypedDict, evaluated and postponed, and bases in other modules holding names their subclasses' modules lack or mean otherwise. test_typed_json_properties holds the checker to a reference predicate worked out from a drawn spec: each class is built in a module of its own, postponed and evaluated classes are mixed, names are quoted by hand, and read-only keys are redeclared. Values are JSON of capped depth that conform, nearly conform, or are drawn at large. Reach tests keep the strategy drawing each of those cases, and putting back any of the bugs found while writing the checker fails the suite. hypothesis joins the package's test dependencies for these.

Review question: does check read each shape, and each TypedDict, as the typing spec does, and is it useful to someone holding nothing but JSON and the package's types?

Where this goes. This is the first of a stack that reads a document's metadata fields (codecs, data types, chunk grids and the rest) against their definitions, with the checker compiling each definition's configuration TypedDict. The later layers are open on my fork for review first: must_understand: false refused at every extension point (d-v-b#353), metadata fields read against their definitions (d-v-b#350, with its core reviewable alone in d-v-b#349), and the field in a document (d-v-b#355). This PR stands without them.

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 zarr-metadata | 🛠️ Build #34779175 | 📁 Comparing d564657 against latest (cad2561)

  🔍 Preview build  

3 files changed

+ api/typed_json/index.html
± api/index.html
± api/model/index.html