Skip to content

Commit 2b57be8

Browse files
vup903claude
andcommitted
Add unified parse_json runtime type checker (zarr-developers#3285)
Introduce zarr.core.json_parse.parse_json, a single type-annotation-driven validator that consolidates the scattered per-field parse_* helpers. Handles primitives, Literal, unions/Optional, fixed and variadic tuples, Sequence/list (coerced to tuple), Mapping/dict, and TypedDict, with a bool-vs-int safe primitive check. Adds tests/test_json_parse.py (94 tests) and a changelog fragment. No existing call sites migrated yet; this is the proof-of-direction module. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
1 parent 971d30d commit 2b57be8

3 files changed

Lines changed: 748 additions & 0 deletions

File tree

‎changes/3285.feature.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Add `zarr.core.json_parse.parse_json`, a unified runtime type checker that validates JSON-decoded metadata values against a type annotation and returns data assignable to it (coercing sequences to tuples), or raises a clear error. It handles the JSON-relevant type categories used by array metadata: primitives (`None`, `str`, `int`, `float`, `bool`), `Literal`, unions/`Optional`, fixed and variadic `tuple`, `Sequence`/`list`, `Mapping`/`dict`, and `TypedDict`. This begins de-duplicating the scattered per-field `parse_*` helpers into a single shared validation path (see #3285).

‎src/zarr/core/json_parse.py‎

Lines changed: 271 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,271 @@
1+
"""Unified runtime type checking for JSON-decoded metadata.
2+
3+
This module provides a single entry point, :func:`parse_json`, that validates a
4+
JSON-decoded ``value`` against a Python ``type_annotation`` and returns data
5+
assignable to that annotation (coercing where sensible, e.g. a list is coerced
6+
to a ``tuple`` for ``Sequence[T]`` annotations), or raises a useful exception.
7+
8+
It is intended to consolidate the many hand-written ``parse_*`` helpers spread
9+
across the codebase (see issue #3285). The scope is deliberately limited to the
10+
JSON-shaped types that appear in Zarr metadata:
11+
12+
* primitives: ``None``, ``str``, ``int``, ``float``, ``bool``
13+
* ``Literal[...]``
14+
* unions, including ``Optional[T]`` and ``X | Y``
15+
* ``tuple[...]`` (fixed-length and variadic)
16+
* ``Sequence[T]`` / ``list[T]`` (coerced to ``tuple``)
17+
* ``Mapping[str, T]`` / ``dict[str, T]``
18+
* :class:`~typing.TypedDict`
19+
20+
Anything outside this scope raises a :class:`TypeError`.
21+
"""
22+
23+
from __future__ import annotations
24+
25+
import types
26+
from collections.abc import Mapping, Sequence
27+
from typing import Any, Literal, Union, get_args, get_origin
28+
29+
from typing_extensions import get_type_hints, is_typeddict
30+
31+
__all__ = ["parse_json"]
32+
33+
# Primitive types handled by a plain ``isinstance`` check. ``bool`` deliberately
34+
# comes before ``int`` because ``bool`` is a subclass of ``int`` and the two
35+
# must not be confused (see ``_parse_primitive``).
36+
_PRIMITIVES: tuple[type, ...] = (bool, int, float, str)
37+
38+
39+
def parse_json(value: object, type_annotation: object) -> Any:
40+
"""Validate ``value`` against ``type_annotation`` and return assignable data.
41+
42+
Parameters
43+
----------
44+
value : object
45+
A JSON-decoded value (``str``, ``int``, ``float``, ``bool``, ``None``,
46+
``list``/``Sequence`` or ``dict``/``Mapping``).
47+
type_annotation : object
48+
The expected type. One of the categories listed in the module
49+
docstring.
50+
51+
Returns
52+
-------
53+
object
54+
``value``, possibly coerced (e.g. a list coerced to a ``tuple`` for a
55+
``Sequence[T]`` annotation, or a TypedDict-shaped ``dict``).
56+
57+
Raises
58+
------
59+
ValueError
60+
If ``value`` does not satisfy a primitive, literal, or union
61+
annotation.
62+
TypeError
63+
If ``value`` has the wrong container shape, or if
64+
``type_annotation`` is not within the supported scope.
65+
"""
66+
# 1. None / type(None)
67+
if type_annotation is None or type_annotation is type(None):
68+
if value is None:
69+
return None
70+
raise ValueError(f"Expected None, got {value!r} instead.")
71+
72+
origin = get_origin(type_annotation)
73+
74+
# 3. Literal[...]
75+
if origin is Literal:
76+
return _parse_literal(value, type_annotation)
77+
78+
# 4. Union / Optional / types.UnionType (X | Y)
79+
if origin is Union or origin is types.UnionType:
80+
return _parse_union(value, type_annotation)
81+
82+
# 8. TypedDict
83+
if is_typeddict(type_annotation):
84+
return _parse_typeddict(value, type_annotation)
85+
86+
# 5. tuple[...]
87+
if origin is tuple:
88+
return _parse_tuple(value, type_annotation)
89+
90+
# 7. Mapping[str, T] / dict[str, T]
91+
if origin is not None and isinstance(origin, type) and issubclass(origin, Mapping):
92+
return _parse_mapping(value, type_annotation)
93+
94+
# 6. Sequence[T] / list[T] (after tuple/Mapping so those take precedence)
95+
if origin is not None and isinstance(origin, type) and issubclass(origin, Sequence):
96+
return _parse_sequence(value, type_annotation)
97+
98+
# 2. Primitives (str, int, float, bool)
99+
if isinstance(type_annotation, type) and issubclass(type_annotation, _PRIMITIVES):
100+
return _parse_primitive(value, type_annotation)
101+
102+
# 9. Fallback
103+
raise TypeError(
104+
f"Cannot parse value {value!r} against unsupported type annotation "
105+
f"{type_annotation!r}."
106+
)
107+
108+
109+
def _parse_primitive(value: object, type_annotation: type) -> Any:
110+
"""Validate ``value`` against a primitive type via ``isinstance``.
111+
112+
The critical edge case is that ``bool`` is a subclass of ``int``. When an
113+
``int`` is expected a ``bool`` must be rejected, and when a ``bool`` is
114+
expected an ``int`` must be rejected.
115+
"""
116+
if type_annotation is bool:
117+
if isinstance(value, bool):
118+
return value
119+
raise ValueError(f"Expected bool, got {value!r} instead.")
120+
121+
if type_annotation is int:
122+
# Reject bool, which is an ``int`` subclass.
123+
if isinstance(value, int) and not isinstance(value, bool):
124+
return value
125+
raise ValueError(f"Expected int, got {value!r} instead.")
126+
127+
if type_annotation is float:
128+
# Reject bool, which is an ``int`` (and thus a ``float``-compatible) value.
129+
if isinstance(value, float) and not isinstance(value, bool):
130+
return value
131+
raise ValueError(f"Expected float, got {value!r} instead.")
132+
133+
# str
134+
if isinstance(value, type_annotation):
135+
return value
136+
raise ValueError(f"Expected {type_annotation.__name__}, got {value!r} instead.")
137+
138+
139+
def _parse_literal(value: object, type_annotation: object) -> Any:
140+
"""Validate that ``value`` is one of the literal members."""
141+
choices = get_args(type_annotation)
142+
# ``True == 1`` in Python, so guard against a bool being accepted for an int
143+
# literal (and vice versa) by also comparing types for the matched member.
144+
for choice in choices:
145+
if value == choice and type(value) is type(choice):
146+
return value
147+
raise ValueError(f"Expected one of {choices!r}, got {value!r} instead.")
148+
149+
150+
def _parse_union(value: object, type_annotation: object) -> Any:
151+
"""Try each union member; return the first that parses, else aggregate."""
152+
members = get_args(type_annotation)
153+
errors: list[str] = []
154+
for member in members:
155+
try:
156+
return parse_json(value, member)
157+
except (ValueError, TypeError) as exc: # noqa: PERF203
158+
errors.append(f" - against {member!r}: {exc}")
159+
joined = "\n".join(errors)
160+
raise ValueError(
161+
f"Expected a value matching one of {members!r}, got {value!r} instead. "
162+
f"Tried each union member:\n{joined}"
163+
)
164+
165+
166+
def _parse_tuple(value: object, type_annotation: object) -> tuple[Any, ...]:
167+
"""Validate a fixed-length or variadic ``tuple[...]`` annotation.
168+
169+
``tuple[int, str]`` is fixed-length; ``tuple[int, ...]`` is variadic. Each
170+
element is recursively parsed against its corresponding element type.
171+
"""
172+
if not isinstance(value, Sequence) or isinstance(value, str | bytes):
173+
raise TypeError(f"Expected a sequence, got {value!r} instead.")
174+
175+
args = get_args(type_annotation)
176+
177+
# Bare ``tuple`` with no parameters: accept any sequence of elements.
178+
if not args:
179+
return tuple(value)
180+
181+
# Variadic ``tuple[T, ...]``.
182+
if len(args) == 2 and args[1] is Ellipsis:
183+
element_type = args[0]
184+
return tuple(parse_json(item, element_type) for item in value)
185+
186+
# Special-case the empty tuple ``tuple[()]``.
187+
if args == ((),):
188+
args = ()
189+
190+
# Fixed-length ``tuple[T1, T2, ...]``.
191+
if len(value) != len(args):
192+
raise TypeError(
193+
f"Expected a sequence of length {len(args)}, got {value!r} of "
194+
f"length {len(value)} instead."
195+
)
196+
return tuple(parse_json(item, element_type) for item, element_type in zip(value, args, strict=True))
197+
198+
199+
def _parse_sequence(value: object, type_annotation: object) -> tuple[Any, ...]:
200+
"""Validate ``Sequence[T]`` / ``list[T]``, returning a ``tuple``.
201+
202+
Each element is recursively parsed against ``T``. A ``str`` is *not* a valid
203+
sequence here, even though it is technically a ``Sequence[str]``, because in
204+
JSON terms a string is a primitive, not an array.
205+
"""
206+
if not isinstance(value, Sequence) or isinstance(value, str | bytes):
207+
raise TypeError(f"Expected a sequence, got {value!r} instead.")
208+
209+
args = get_args(type_annotation)
210+
if not args:
211+
# Bare ``list`` / ``Sequence`` with no element type: accept any element.
212+
return tuple(value)
213+
element_type = args[0]
214+
return tuple(parse_json(item, element_type) for item in value)
215+
216+
217+
def _parse_mapping(value: object, type_annotation: object) -> dict[str, Any]:
218+
"""Validate ``Mapping[str, T]`` / ``dict[str, T]``, returning a ``dict``.
219+
220+
Keys must be ``str`` and each value is recursively parsed against ``T``.
221+
"""
222+
if not isinstance(value, Mapping):
223+
raise TypeError(f"Expected a mapping, got {value!r} instead.")
224+
225+
args = get_args(type_annotation)
226+
if args:
227+
key_type, value_type = args[0], args[1]
228+
else:
229+
key_type, value_type = str, object
230+
231+
result: dict[str, Any] = {}
232+
for key, val in value.items():
233+
if key_type is str and not isinstance(key, str):
234+
raise TypeError(f"Expected mapping key to be str, got {key!r} instead.")
235+
result[key] = parse_json(val, value_type) if value_type is not object else val
236+
return result
237+
238+
239+
def _parse_typeddict(value: object, type_annotation: Any) -> dict[str, Any]:
240+
"""Validate a :class:`~typing.TypedDict` annotation.
241+
242+
Each required key must be present and is parsed against its annotation.
243+
Optional keys are parsed when present. Totality is respected via the
244+
TypedDict's ``__required_keys__`` / ``__optional_keys__`` attributes.
245+
"""
246+
if not isinstance(value, Mapping):
247+
raise TypeError(f"Expected a mapping, got {value!r} instead.")
248+
249+
# ``include_extras=True`` keeps ``Required`` / ``NotRequired`` / ``ReadOnly``
250+
# wrappers visible if needed; the required/optional split is taken from the
251+
# TypedDict's own bookkeeping which already accounts for totality.
252+
hints = get_type_hints(type_annotation, include_extras=False)
253+
required_keys: frozenset[str] = getattr(type_annotation, "__required_keys__", frozenset())
254+
optional_keys: frozenset[str] = getattr(type_annotation, "__optional_keys__", frozenset())
255+
256+
missing = [key for key in required_keys if key not in value]
257+
if missing:
258+
raise ValueError(
259+
f"Expected required key(s) {sorted(missing)!r} for "
260+
f"{type_annotation.__name__}, got {value!r} instead."
261+
)
262+
263+
result: dict[str, Any] = {}
264+
for key in required_keys | optional_keys:
265+
if key in value:
266+
result[key] = parse_json(value[key], hints[key])
267+
# Preserve any extra keys not declared on the TypedDict.
268+
for key, val in value.items():
269+
if key not in result:
270+
result[key] = val
271+
return result

0 commit comments

Comments
 (0)