Skip to content

Commit d81f8ed

Browse files
committed
feat(zarr-metadata)!: problems and errors check their values at run time
`ValidationProblem` checks that its `loc` is a tuple of strings and integers, its `message` a string and its `kind` one of the kinds, and `MetadataValidationError` that it holds problems; each raises `TypeError` otherwise. A caller that is not type-checked fails where it builds the value, not where a location is read. The v2 consolidated reader reported a non-string document key as a member at a location made of the key, which the check refuses; it now reports it at the document, as every other reader does. BREAKING CHANGE: a `loc` that is a list, or holds a `bool`, is refused. Assisted-by: ClaudeCode:claude-opus-5-5
1 parent e85bf65 commit d81f8ed

5 files changed

Lines changed: 105 additions & 3 deletions

File tree

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
**Breaking:** `ValidationProblem` and `MetadataValidationError` check at run
2+
time what their annotations declare, and raise `TypeError` otherwise. A
3+
problem's `loc` is a tuple of strings and integers, so a list, which was
4+
accepted before, is now refused, as is a `bool`; its `message` is a string
5+
and its `kind` one of the kinds; an error holds problems. A caller that is
6+
not type-checked fails where it builds the value, not later, where a
7+
location is read.

‎packages/zarr-metadata/src/zarr_metadata/model/_group.py‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -386,15 +386,18 @@ def from_json(cls, data: object) -> ZarrV2ConsolidatedMetadata:
386386
raise MetadataValidationError(
387387
[ValidationProblem((), "expected a mapping", "invalid_type")]
388388
)
389-
doc = cast("Mapping[str, object]", normalized)
389+
doc = cast("Mapping[object, object]", normalized)
390390
problems: list[ValidationProblem] = [
391391
ValidationProblem((key,), "missing required key", "missing_key")
392392
for key in ("zarr_consolidated_format", "metadata")
393393
if key not in doc
394394
]
395395
problems.extend(
396396
ValidationProblem((key,), "unexpected document member", "invalid_value")
397-
for key in doc.keys() - {"zarr_consolidated_format", "metadata"}
397+
if isinstance(key, str)
398+
else ValidationProblem((), f"non-string document key {key!r}", "invalid_type")
399+
for key in doc
400+
if key not in {"zarr_consolidated_format", "metadata"}
398401
)
399402
if "zarr_consolidated_format" in doc and (
400403
not isinstance(doc["zarr_consolidated_format"], int)

‎packages/zarr-metadata/src/zarr_metadata/model/_validation.py‎

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
import math
1818
from collections.abc import Mapping, Sequence
1919
from dataclasses import dataclass
20-
from typing import Final, Literal, cast
20+
from typing import Final, Literal, cast, get_args
2121

2222
from typing_extensions import TypeIs
2323

@@ -55,6 +55,26 @@ class ValidationProblem:
5555
message: str
5656
kind: ProblemKind
5757

58+
def __post_init__(self) -> None:
59+
# The runtime half of the annotations: a rule written without a type
60+
# checker, as an extension's may be, fails where it builds a problem
61+
# rather than reporting one at a location that is not one.
62+
loc = cast("object", self.loc)
63+
if not isinstance(loc, tuple) or not all(
64+
isinstance(part, str) or (isinstance(part, int) and not isinstance(part, bool))
65+
for part in cast("tuple[object, ...]", loc)
66+
):
67+
msg = f"a ValidationProblem's loc is a tuple of keys and indices, got {loc!r}"
68+
raise TypeError(msg)
69+
message = cast("object", self.message)
70+
if not isinstance(message, str):
71+
msg = f"a ValidationProblem's message is a string, got {message!r}"
72+
raise TypeError(msg)
73+
kind = cast("object", self.kind)
74+
if not isinstance(kind, str) or kind not in get_args(ProblemKind):
75+
msg = f"a ValidationProblem's kind is one of {get_args(ProblemKind)!r}, got {kind!r}"
76+
raise TypeError(msg)
77+
5878
def __str__(self) -> str:
5979
location = ".".join(str(part) for part in self.loc) if self.loc else "<root>"
6080
return f"{location}: {self.message}"
@@ -72,6 +92,16 @@ class MetadataValidationError(ValueError):
7292

7393
def __init__(self, problems: Sequence[ValidationProblem]) -> None:
7494
self.problems = tuple(problems)
95+
for entry in cast("tuple[object, ...]", self.problems):
96+
# The runtime half of the annotation: a caller that is not
97+
# type-checked, and hands over anything else, fails here
98+
# rather than far away, where a `loc` is read off it.
99+
if not isinstance(entry, ValidationProblem):
100+
msg = (
101+
"MetadataValidationError takes ValidationProblem values, "
102+
f"got {type(entry).__name__}"
103+
)
104+
raise TypeError(msg)
75105
super().__init__("\n".join(str(problem) for problem in self.problems))
76106

77107
def __reduce__(

‎packages/zarr-metadata/tests/model/test_array.py‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1274,6 +1274,55 @@ def test_the_error_pickles_and_copies_as_its_problems() -> None:
12741274
assert again.__notes__ == ["while reading a"]
12751275

12761276

1277+
def test_error_a_problem_refuses_a_loc_that_is_not_a_tuple() -> None:
1278+
# The missing comma: `("level")` is a string, and read as a location
1279+
# it would be the path through each of its characters.
1280+
with pytest.raises(TypeError, match="loc is a tuple of keys and indices"):
1281+
ValidationProblem(("level"), "bad level", "invalid_value") # pyright: ignore[reportArgumentType]
1282+
1283+
1284+
@pytest.mark.parametrize("part", [True, 1.5], ids=["bool", "float"])
1285+
def test_error_a_problem_refuses_a_loc_part_that_is_not_a_key_or_an_index(part: object) -> None:
1286+
# `True` passes as an `int`, and would index a sequence as 1.
1287+
with pytest.raises(TypeError, match="loc is a tuple of keys and indices"):
1288+
ValidationProblem(("a", part), "bad a", "invalid_value") # pyright: ignore[reportArgumentType]
1289+
1290+
1291+
def test_error_a_problem_refuses_a_message_that_is_not_a_string() -> None:
1292+
with pytest.raises(TypeError, match="message is a string"):
1293+
ValidationProblem(("level",), 7, "invalid_value") # pyright: ignore[reportArgumentType]
1294+
1295+
1296+
def test_error_a_problem_refuses_a_kind_that_is_not_one() -> None:
1297+
# A kind outside the set is one a consumer that dispatches on kinds
1298+
# never sees.
1299+
with pytest.raises(TypeError, match="kind is one of"):
1300+
ValidationProblem(("level",), "bad level", "invalid") # pyright: ignore[reportArgumentType]
1301+
1302+
1303+
class _EqualToEveryKind:
1304+
"""Not a kind, though it compares equal to each."""
1305+
1306+
def __eq__(self, other: object) -> bool:
1307+
return True
1308+
1309+
def __hash__(self) -> int:
1310+
return 0
1311+
1312+
1313+
def test_error_a_problem_refuses_a_kind_that_only_compares_equal_to_one() -> None:
1314+
# `in` tests equality, which any object can claim.
1315+
with pytest.raises(TypeError, match="kind is one of"):
1316+
ValidationProblem(("level",), "bad level", _EqualToEveryKind()) # pyright: ignore[reportArgumentType]
1317+
1318+
1319+
def test_error_the_error_refuses_what_is_not_a_problem() -> None:
1320+
# A list of one-element tuples of problems is the likely slip: it
1321+
# would otherwise fail far away, where a `loc` is read off an entry.
1322+
with pytest.raises(TypeError, match="takes ValidationProblem values, got tuple"):
1323+
MetadataValidationError([(ValidationProblem(("a",), "bad a", "invalid_value"),)]) # pyright: ignore[reportArgumentType]
1324+
1325+
12771326
def test_prefix_prepends_loc_head() -> None:
12781327
"""_prefix prepends a loc head to each problem's loc."""
12791328
problems = [ValidationProblem(loc=("name",), message="expected str", kind="invalid_type")]

‎packages/zarr-metadata/tests/model/test_group.py‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -498,6 +498,19 @@ def test_v2_consolidated_rejects_unknown_document_member() -> None:
498498
ZarrV2ConsolidatedMetadata.from_json(doc)
499499

500500

501+
@pytest.mark.parametrize("key", [1, None], ids=["int", "none"])
502+
def test_v2_consolidated_rejects_non_string_document_key(key: object) -> None:
503+
"""A non-string key is a problem at the document: not a member at a
504+
location that reads as an index, nor a `TypeError`."""
505+
doc = {"zarr_consolidated_format": 1, "metadata": {}, key: "x"}
506+
507+
with pytest.raises(MetadataValidationError) as exc_info:
508+
ZarrV2ConsolidatedMetadata.from_json(doc)
509+
assert [(problem.loc, problem.kind) for problem in exc_info.value.problems] == [
510+
((), "invalid_type")
511+
]
512+
513+
501514
# --- must_understand partition ------------------------------------------------
502515

503516

0 commit comments

Comments
 (0)