You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 2e6b275
Browse filesBrowse the repository at this point in the historyBrowse files
docs(zarr-metadata): link the spec text behind every spec statement
Every docstring or comment that cites the Zarr spec or a zarr-extensions
README now carries a commit-pinned permalink with a line range
(zarr-specs fc7dd9c; zarr-extensions 4da7b37, the registry commit the
TypeScript port vendors). Unpinned zarr-extensions `tree/main` page links
are pinned the same way.
Three statements were wrong or stale and are corrected:
- zstd: `checksum` was typed required "per the proposed specification"
(zarr-specs PR #256, never merged). The published zarr-extensions entry
makes it optional ("Should be omitted if false"; schema requires only
`level`), so it is now `NotRequired[bool]`.
- v3 consolidated metadata was described as "not a spec artifact"; since
zarr-specs #373 the core spec names the field and fixes its envelope
(core/index.rst L802-L816); the entry format remains a convention.
- The v2 array `*Partial` docstring spoke of a "closed shape"; the array
document is open (other keys SHOULD be ignored), unlike `.zgroup`.
Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <[email protected]>
Copy file name to clipboardExpand all lines: packages/zarr-metadata/src/zarr_metadata/model/_array.py
+6-5Lines changed: 6 additions & 5 deletions
Original file line number
Diff line number
Diff line change
@@ -51,7 +51,7 @@ class ZarrV3NamedConfig:
51
51
52
52
Bare names and missing configurations normalize to an empty configuration.
53
53
Bare names and missing `must_understand` members normalize to the spec's
54
-
implicit `True` value.
54
+
implicit `True` value (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1573).
55
55
"""
56
56
57
57
name: str
@@ -107,8 +107,8 @@ def must_understand_subset(
107
107
) ->dict[str, ZarrV3ExtensionField]:
108
108
"""The subset of `extra_fields` the reader is obligated to understand.
109
109
110
-
Per the v3 spec, an extension field is implicitly `must_understand: True`
111
-
unless it explicitly says otherwise, and an implementation MUST fail to
110
+
Per the v3 spec (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1578), an extension field is implicitly `must_understand:
111
+
True` unless it explicitly says otherwise, and an implementation MUST fail to
112
112
open a group or array carrying fields it does not recognize that are not
113
113
explicitly `must_understand: false`. A non-mapping field value cannot
114
114
carry the explicit waiver, so it always requires understanding (the
"""Extra fields the reader is obligated to understand.
311
311
312
312
Everything in `extra_fields` not explicitly waived with
313
-
`must_understand: false` (the spec's implicit-true rule). A compliant
313
+
`must_understand: false` (the spec's implicit-true rule, https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1578). A compliant
314
314
reader MUST fail to open the array if this contains any field it does
315
315
not recognize; the model layer only partitions by obligation, since
"""Extra fields the reader is obligated to understand.
169
169
170
170
Everything in `extra_fields` not explicitly waived with
171
-
`must_understand: false` (the spec's implicit-true rule). A compliant
171
+
`must_understand: false` (the spec's implicit-true rule, https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1571-L1578). A compliant
172
172
reader MUST fail to open the group if this contains any field it does
173
173
not recognize; the model layer only partitions by obligation, since
Models the union of `.zarray` (the spec-defined fields) and `.zattrs`
85
-
(user attributes). On disk, attributes live in a sibling `.zattrs` file
84
+
Models the union of `.zarray` (the spec-defined fields, https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v2/v2.0.rst#L51-L92)
85
+
and `.zattrs` (user attributes, https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v2/v2.0.rst#L323-L330). On disk, attributes live in a sibling `.zattrs` file
86
86
and are not part of `.zarray`; this type folds them in as the
87
87
`attributes` field so a single TypedDict represents the complete
88
88
in-memory state of a v2 array node. Consumers that read or write a
@@ -126,8 +126,10 @@ class ZarrV2ArrayMetadataJSONPartial(TypedDict, total=False):
126
126
`tests/test_partial_equivalence.py` passes without special-casing those
Note: v2 array metadata has no `extra_items` setting (the v2 spec has no
130
-
extension-field concept), so this partial inherits the same closed shape.
129
+
Note: v2 array metadata has no `extra_items` setting: the v2 spec has no
130
+
extension-field concept, and other `.zarray` keys "SHOULD be ignored by
131
+
implementations" (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v2/v2.0.rst#L91-L92), so nothing beyond the spec-defined
132
+
fields is modeled.
131
133
132
134
Drift between this type and `ZarrV2ArrayMetadataJSON` is prevented by
See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html
24
25
"""
@@ -30,8 +31,8 @@ class ZarrV2GroupMetadataJSON(TypedDict):
30
31
"""
31
32
Zarr v2 group metadata document, in-memory merged form.
32
33
33
-
Models the union of `.zgroup` (the spec-defined `zarr_format` field)
34
-
and `.zattrs` (user attributes). On disk these are persisted as two
34
+
Models the union of `.zgroup` (the spec-defined `zarr_format` field,
35
+
https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v2/v2.0.rst#L306-L313) and `.zattrs` (user attributes, https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v2/v2.0.rst#L323-L330). On disk these are persisted as two
35
36
separate files; this type folds them so a single TypedDict represents
36
37
the complete in-memory state of a v2 group node. Consumers that read
37
38
or write the real on-disk files should use `ZarrV2ZGroupJSON` (strict
@@ -64,7 +65,8 @@ class ZarrV2GroupMetadataJSONPartial(TypedDict, total=False):
64
65
`total=False`).
65
66
66
67
Note: v2 group metadata has no `extra_items` setting (the v2 spec has no
67
-
extension-field concept), so this partial inherits the same closed shape.
68
+
extension-field concept, and `.zgroup` forbids other keys outright:
69
+
https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v2/v2.0.rst#L313), so this partial inherits the same closed shape.
68
70
69
71
Drift between this type and `ZarrV2GroupMetadataJSON` is prevented by
Copy file name to clipboardExpand all lines: packages/zarr-metadata/src/zarr_metadata/v3/chunk_grid/rectilinear.py
+3-1Lines changed: 3 additions & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
"""
2
2
Rectilinear chunk grid (zarr-extensions).
3
3
4
-
See https://github.com/zarr-developers/zarr-extensions/tree/main/chunk-grids/rectilinear
4
+
See https://github.com/zarr-developers/zarr-extensions/blob/4da7b37a84f76e660902f6d3de3eaef0e0febae6/chunk-grids/rectilinear/README.md
5
5
"""
6
6
7
7
fromtypingimportFinal, Literal
@@ -42,6 +42,8 @@ class RectilinearChunkGridObject(TypedDict):
42
42
43
43
`kind` and `chunk_shapes` are required, so only the object form is valid;
44
44
the short-hand-name form is not permitted by the spec for this grid.
Copy file name to clipboardExpand all lines: packages/zarr-metadata/src/zarr_metadata/v3/chunk_grid/regular.py
+2Lines changed: 2 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -33,6 +33,8 @@ class RegularChunkGridObject(TypedDict):
33
33
34
34
`chunk_shape` is required and has no default, so only the object form is
35
35
valid; the short-hand-name form is not permitted by the spec for this grid.
36
+
https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L528-L537 ("must be an object with the names name and configuration")
0 commit comments