Skip to content

Commit 2e6b275

Browse files
d-v-bclaude
andcommitted
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]>
1 parent f651b73 commit 2e6b275

31 files changed

Lines changed: 115 additions & 49 deletions

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

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ class ZarrV3NamedConfig:
5151
5252
Bare names and missing configurations normalize to an empty configuration.
5353
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).
5555
"""
5656

5757
name: str
@@ -107,8 +107,8 @@ def must_understand_subset(
107107
) -> dict[str, ZarrV3ExtensionField]:
108108
"""The subset of `extra_fields` the reader is obligated to understand.
109109
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
112112
open a group or array carrying fields it does not recognize that are not
113113
explicitly `must_understand: false`. A non-mapping field value cannot
114114
carry the explicit waiver, so it always requires understanding (the
@@ -310,7 +310,7 @@ def must_understand_fields(self) -> dict[str, ZarrV3ExtensionField]:
310310
"""Extra fields the reader is obligated to understand.
311311
312312
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
314314
reader MUST fail to open the array if this contains any field it does
315315
not recognize; the model layer only partitions by obligation, since
316316
recognition is reader-specific.
@@ -428,7 +428,8 @@ def to_json(self) -> ZarrV2ArrayMetadataJSON:
428428
`attributes` is included when set (even empty). This is not the
429429
on-disk `.zarray` content: a conforming `.zarray` must exclude
430430
`attributes` (they live in the sibling `.zattrs` file). Use
431-
`to_key_value` to produce the spec-conforming split for storage.
431+
`to_key_value` to produce the spec-conforming split for storage
432+
(https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v2/v2.0.rst#L323-L330).
432433
"""
433434
# to_json output shares no mutable state with the model: every value
434435
# that can hold a mutable container is deep-copied.

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -168,7 +168,7 @@ def must_understand_fields(self) -> dict[str, ZarrV3ExtensionField]:
168168
"""Extra fields the reader is obligated to understand.
169169
170170
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
172172
reader MUST fail to open the group if this contains any field it does
173173
not recognize; the model layer only partitions by obligation, since
174174
recognition is reader-specific.
@@ -299,7 +299,8 @@ def to_json(self) -> ZarrV2GroupMetadataJSON:
299299
`attributes` is included when set (even empty). This is not the
300300
on-disk `.zgroup` content: a conforming `.zgroup` must exclude
301301
`attributes` (they live in the sibling `.zattrs` file). Use
302-
`to_key_value` to produce the spec-conforming split for storage.
302+
`to_key_value` to produce the spec-conforming split for storage
303+
(https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v2/v2.0.rst#L313; https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v2/v2.0.rst#L323-L330).
303304
"""
304305
# to_json output shares no mutable state with the model.
305306
out: ZarrV2GroupMetadataJSON = {"zarr_format": self.zarr_format}

‎packages/zarr-metadata/src/zarr_metadata/v2/array.py‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -81,8 +81,8 @@ class ZarrV2ArrayMetadataJSON(TypedDict):
8181
"""
8282
Zarr v2 array metadata document, in-memory merged form.
8383
84-
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
8686
and are not part of `.zarray`; this type folds them in as the
8787
`attributes` field so a single TypedDict represents the complete
8888
in-memory state of a v2 array node. Consumers that read or write a
@@ -126,8 +126,10 @@ class ZarrV2ArrayMetadataJSONPartial(TypedDict, total=False):
126126
`tests/test_partial_equivalence.py` passes without special-casing those
127127
fields (PEP 655 explicitly permits `NotRequired` inside `total=False`).
128128
129-
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.
131133
132134
Drift between this type and `ZarrV2ArrayMetadataJSON` is prevented by
133135
`tests/test_partial_equivalence.py`.

‎packages/zarr-metadata/src/zarr_metadata/v2/attributes.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
Spec-defined keys for arrays / groups live in sibling `.zarray` / `.zgroup`
1616
files (modeled by `ZarrV2ZArrayJSON` / `ZarrV2ZGroupJSON`). This type does not
1717
constrain the keys or values of the attributes mapping.
18+
https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v2/v2.0.rst#L323-L330
1819
"""
1920

2021

‎packages/zarr-metadata/src/zarr_metadata/v2/group.py‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,10 @@ class ZarrV2ZGroupJSON(TypedDict):
1616
On-disk `.zgroup` file content.
1717
1818
Strict shape of the JSON document persisted at `<path>/.zgroup` for
19-
a v2 group. The spec defines exactly one field. User attributes live
20-
in a sibling `.zattrs` file and are NOT part of this type; see
21-
`ZarrV2ZAttrsJSON`.
19+
a v2 group. The spec defines exactly one field and forbids others. User
20+
attributes live in a sibling `.zattrs` file and are NOT part of this
21+
type; see `ZarrV2ZAttrsJSON`.
22+
https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v2/v2.0.rst#L306-L313
2223
2324
See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html
2425
"""
@@ -30,8 +31,8 @@ class ZarrV2GroupMetadataJSON(TypedDict):
3031
"""
3132
Zarr v2 group metadata document, in-memory merged form.
3233
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
3536
separate files; this type folds them so a single TypedDict represents
3637
the complete in-memory state of a v2 group node. Consumers that read
3738
or write the real on-disk files should use `ZarrV2ZGroupJSON` (strict
@@ -64,7 +65,8 @@ class ZarrV2GroupMetadataJSONPartial(TypedDict, total=False):
6465
`total=False`).
6566
6667
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.
6870
6971
Drift between this type and `ZarrV2GroupMetadataJSON` is prevented by
7072
`tests/test_partial_equivalence.py`.

‎packages/zarr-metadata/src/zarr_metadata/v3/chunk_grid/rectilinear.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
"""
22
Rectilinear chunk grid (zarr-extensions).
33
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
55
"""
66

77
from typing import Final, Literal
@@ -42,6 +42,8 @@ class RectilinearChunkGridObject(TypedDict):
4242
4343
`kind` and `chunk_shapes` are required, so only the object form is valid;
4444
the short-hand-name form is not permitted by the spec for this grid.
45+
https://github.com/zarr-developers/zarr-extensions/blob/4da7b37a84f76e660902f6d3de3eaef0e0febae6/chunk-grids/rectilinear/README.md#L59-L62
46+
https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1562-L1564
4547
"""
4648

4749
__all__ = [

‎packages/zarr-metadata/src/zarr_metadata/v3/chunk_grid/regular.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,8 @@ class RegularChunkGridObject(TypedDict):
3333
3434
`chunk_shape` is required and has no default, so only the object form is
3535
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")
37+
https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L1562-L1564
3638
"""
3739

3840
__all__ = [

‎packages/zarr-metadata/src/zarr_metadata/v3/chunk_key_encoding/__init__.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,9 @@
66
- `default` -- v3 default encoding (`/`-separated)
77
- `v2` -- v2-compatibility encoding (`.`-separated by default)
88
9-
Both are defined by the v3 core spec.
9+
Both are defined by the v3 core spec:
10+
https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/chunk-key-encodings/default/index.rst
11+
https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/chunk-key-encodings/v2/index.rst
1012
1113
The `<X>ChunkKeyEncodingMetadata` aliases re-exported here are the canonical
1214
type for each encoding's permitted JSON shapes. For the underlying

‎packages/zarr-metadata/src/zarr_metadata/v3/chunk_key_encoding/default.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ class DefaultChunkKeyEncodingConfiguration(TypedDict):
3131
"""Configuration for the default chunk key encoding.
3232
3333
`separator` is optional and defaults to `"/"` per spec.
34+
https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/chunk-key-encodings/default/index.rst#L27-L29
3435
"""
3536

3637
separator: NotRequired[DefaultChunkKeyEncodingSeparator]

‎packages/zarr-metadata/src/zarr_metadata/v3/chunk_key_encoding/v2.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ class V2ChunkKeyEncodingConfiguration(TypedDict):
3737
"""Configuration for the v2 chunk key encoding.
3838
3939
`separator` is optional and defaults to `"."` per spec.
40+
https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/chunk-key-encodings/v2/index.rst#L27-L29
4041
"""
4142

4243
separator: NotRequired[V2ChunkKeyEncodingSeparator]

0 commit comments

Comments
 (0)