|
| 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