refactor(metadata): check stored chunk shapes against the array shape in one routine

The legacy zero-chunk policy was written out twice: inline in
`ArrayV2Metadata.__init__`, and again in a Zarr format 3 helper. The V2
copy also zipped with `strict=False` and re-appended any trailing chunk
entries only so that a separate length check, `parse_metadata`, could
report a dimensionality mismatch after construction.

`parse_stored_chunk_shape` in `zarr.core.metadata.common` is now the one
place a stored chunk shape is checked against its array's shape, for both
formats: one entry per axis, every integer chunk size at least 1, and a
size of 0 (or JSON `false`) on a zero-length axis read as 1 with a
warning that names the writer and how to re-save. Non-integer entries,
such as edge lists, pass through for the caller's own parser.

`ArrayV2Metadata.__init__` calls it directly and `parse_metadata` is
gone. The Zarr format 3 adapter only locates a regular grid's
`chunk_shape` in the stored document and hands it over; it still runs in
`ArrayV3Metadata.__init__` because chunk grid metadata has no array shape.
The Zarr format 3 import changes that existed only for the old helper are
reverted.

Tests for the policy now target the routine: one table of valid and
legacy inputs, and one test per rejection (dimension mismatch, zero on a
non-empty axis, negative). They replace metadata-level tests in
test_v2.py and test_v3.py that only re-tested the same rules; the
end-to-end tests still cover both formats' wiring against stored arrays.

Assisted-by: ClaudeCode:claude-opus-5

Author: d-v-b

src/zarr/core/metadata/common.py

@@ -1,8 +1,14 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Final
+import numbers
+import warnings
+from typing import TYPE_CHECKING, Any, Final
+
+from zarr.errors import ZarrUserWarning
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
+
     from zarr.core.common import JSON
 
 RESAVE_METADATA_HINT: Final = (
@@ -21,3 +27,45 @@ def parse_attributes(data: dict[str, JSON] | None) -> dict[str, JSON]:
         return {}
 
     return dict(data)
+
+
+def parse_stored_chunk_shape(
+    chunk_shape: Sequence[Any], shape: Sequence[int], *, legacy_writers: str
+) -> tuple[Any, ...]:
+    """Validate a stored chunk shape against the array shape.
+
+    This is the one place a stored per-axis chunk shape is checked against the
+    array it belongs to, for both Zarr formats. The chunk shape must have one
+    entry per array axis, and every integer chunk size must be at least 1.
+
+    The exception is a chunk size of 0 on a zero-length axis, which
+    `legacy_writers` stored for arrays created empty. An empty axis has no
+    chunk for the size to describe, so it is read as 1 with a
+    `ZarrUserWarning` that says how to re-save valid metadata. A chunk size of
+    0 on a positive-length axis is rejected, because the metadata cannot say
+    how the stored chunks were laid out. JSON `false` counts as 0.
+
+    Entries that are not integers, such as explicit chunk edge lists, are
+    returned unchanged for the caller's own parser.
+    """
+    if len(chunk_shape) != len(shape):
+        raise ValueError(
+            f"The chunk shape {tuple(chunk_shape)} and the array shape {tuple(shape)} "
+            "must have the same number of dimensions."
+        )
+    parsed: list[Any] = []
+    for dim_idx, (size, extent) in enumerate(zip(chunk_shape, shape, strict=True)):
+        if isinstance(size, numbers.Integral) and size < 1:
+            if size < 0 or extent != 0:
+                raise ValueError(
+                    f"Dimension {dim_idx}: chunk edge length must be >= 1, got {size!r}"
+                )
+            warnings.warn(
+                f"Dimension {dim_idx}: chunk edge length {size!r} on a zero-length axis "
+                f"(as written by {legacy_writers}) is treated as 1. {RESAVE_METADATA_HINT}",
+                ZarrUserWarning,
+                stacklevel=3,
+            )
+            size = 1
+        parsed.append(size)
+    return tuple(parsed)

src/zarr/core/metadata/v2.py

@@ -42,7 +42,7 @@
 )
 from zarr.core.config import config, parse_indexing_order
 from zarr.core.json_parse import parse_field
-from zarr.core.metadata.common import RESAVE_METADATA_HINT, parse_attributes
+from zarr.core.metadata.common import parse_attributes, parse_stored_chunk_shape
 
 
 class ArrayV2MetadataDict(TypedDict):
@@ -88,32 +88,11 @@ def __init__(
         Metadata for a Zarr format 2 array.
         """
         shape_parsed = parse_shapelike(shape)
-        chunks_parsed = parse_shapelike(chunks)
-        # Same invariant as the Zarr format 3 chunk grid metadata: every chunk edge
-        # length is at least 1. zarr-python 2.18.7, and 3.x before 3.4, can write
-        # `chunks: [0]` for a zero-length axis (e.g. `chunks=False`, `-1` or `(0,)`).
-        # Normalize that empty axis to chunk size 1 so it can use the positive-size
-        # grid model. This is a compatibility policy for legacy metadata, not a
-        # statement about every historical reader. A zero chunk size on a
-        # positive-length axis is rejected; metadata alone cannot establish
-        # whether the store contains chunk payloads.
-        normalized_chunks: list[int] = []
-        for dim_idx, (extent, chunk) in enumerate(zip(shape_parsed, chunks_parsed, strict=False)):
-            if chunk < 1:
-                if chunk < 0 or extent != 0:
-                    raise ValueError(
-                        f"Dimension {dim_idx}: chunk edge length must be >= 1, got {chunk}"
-                    )
-                warnings.warn(
-                    f"Dimension {dim_idx}: chunk edge length 0 on a zero-length axis "
-                    "(as written by zarr-python 2.x, and by 3.x before 3.4) is treated "
-                    f"as 1. {RESAVE_METADATA_HINT}",
-                    ZarrUserWarning,
-                    stacklevel=2,
-                )
-                chunk = 1
-            normalized_chunks.append(chunk)
-        chunks_parsed = tuple(normalized_chunks) + chunks_parsed[len(shape_parsed) :]
+        chunks_parsed = parse_stored_chunk_shape(
+            parse_shapelike(chunks),
+            shape_parsed,
+            legacy_writers="zarr-python 2.x, and by 3.x before 3.4",
+        )
         compressor_parsed = parse_compressor(compressor)
         order_parsed = parse_indexing_order(order)
         dimension_separator_parsed = parse_separator(dimension_separator)
@@ -136,7 +115,6 @@ def __init__(
         object.__setattr__(self, "attributes", attributes_parsed)
 
         # ensure that the metadata document is consistent
-        _ = parse_metadata(self)
 
     @property
     def ndim(self) -> int:
@@ -348,16 +326,6 @@ def parse_compressor(data: object) -> Numcodec | None:
     raise ValueError(msg)
 
 
-def parse_metadata(data: ArrayV2Metadata) -> ArrayV2Metadata:
-    if (l_chunks := len(data.chunks)) != (l_shape := len(data.shape)):
-        msg = (
-            f"The `shape` and `chunks` attributes must have the same length. "
-            f"`chunks` has length {l_chunks}, but `shape` has length {l_shape}."
-        )
-        raise ValueError(msg)
-    return data
-
-
 def get_object_codec_id(maybe_object_codecs: Sequence[JSON]) -> str | None:
     """
     Inspect a sequence of codecs / filters for an "object codec", i.e. a codec

src/zarr/core/metadata/v3.py

@@ -1,12 +1,10 @@
 from __future__ import annotations
 
 import json
-import warnings
 from collections.abc import Iterable, Mapping, Sequence
 from dataclasses import dataclass, field, replace
 from typing import TYPE_CHECKING, Any, Final, Literal, NotRequired, TypeGuard, cast
 
-import numpy as np
 from typing_extensions import TypedDict
 
 from zarr.abc.codec import ArrayArrayCodec, ArrayBytesCodec, BytesBytesCodec, Codec
@@ -37,8 +35,8 @@
 from zarr.core.dtype import VariableLengthUTF8, ZDType, get_data_type_from_json
 from zarr.core.dtype.common import check_dtype_spec_v3
 from zarr.core.json_parse import parse_field
-from zarr.core.metadata.common import RESAVE_METADATA_HINT, parse_attributes
-from zarr.errors import MetadataValidationError, NodeTypeValidationError, ZarrUserWarning
+from zarr.core.metadata.common import parse_attributes, parse_stored_chunk_shape
+from zarr.errors import MetadataValidationError, NodeTypeValidationError
 from zarr.registry import get_codec_class
 
 if TYPE_CHECKING:
@@ -482,17 +480,12 @@ def _read_legacy_zero_chunk_sizes(
     chunk_grid: dict[str, JSON] | ChunkGridMetadata | NamedConfig[str, Any],
     shape: tuple[int, ...],
 ) -> dict[str, JSON] | ChunkGridMetadata | NamedConfig[str, Any]:
-    """Read a stored regular chunk size of 0 on a zero-length axis as 1.
-
-    zarr-python 3.0 and 3.1 stored `chunk_shape: [0]` for an array created with
-    a zero-length axis and `chunks=(0,)` or `chunks=False` (3.0 stored `false`
-    for the latter). Chunk sizes must be at least 1, and a zero-length axis has
-    no chunks for the size to describe until the array grows, so the size is
-    read as 1 with a warning. This is the policy `ArrayV2Metadata` applies to
-    Zarr format 2 metadata. It needs the array shape, which the chunk grid
-    metadata does not carry, so it runs here rather than in the grid parser.
-    A zero chunk size on a positive-length axis is left for that parser to
-    reject.
+    """Check a stored regular grid's chunk shape against the array shape.
+
+    zarr-python 3.0 and 3.1 stored `chunk_shape: [0]` (and 3.0 `[false]`) for
+    an array created with a zero-length axis; `parse_stored_chunk_shape`
+    decides what that means. It needs the array shape, which chunk grid
+    metadata does not carry, so this runs here rather than in the grid parser.
     """
     if not isinstance(chunk_grid, Mapping) or chunk_grid.get("name") != "regular":
         return chunk_grid
@@ -502,25 +495,10 @@ def _read_legacy_zero_chunk_sizes(
     chunk_shape = configuration.get("chunk_shape")
     if not isinstance(chunk_shape, Sequence) or isinstance(chunk_shape, str):
         return chunk_grid
-    if len(chunk_shape) != len(shape):
-        return chunk_grid  # the dimensionality check reports this
-    normalized = list(chunk_shape)
-    changed = False
-    for dim_idx, (size, extent) in enumerate(zip(chunk_shape, shape, strict=True)):
-        if isinstance(size, int | np.integer) and size == 0 and extent == 0:
-            warnings.warn(
-                f"Dimension {dim_idx}: chunk edge length {size!r} on a zero-length axis "
-                "(as written by zarr-python 3.0 and 3.1) is treated as 1. "
-                f"{RESAVE_METADATA_HINT}",
-                ZarrUserWarning,
-                stacklevel=2,
-            )
-            normalized[dim_idx] = 1
-            changed = True
-    if not changed:
-        return chunk_grid
-    corrected: dict[str, JSON] = {**configuration, "chunk_shape": normalized}
-    return {"name": "regular", "configuration": corrected}
+    parsed = parse_stored_chunk_shape(chunk_shape, shape, legacy_writers="zarr-python 3.0 and 3.1")
+    corrected: dict[str, Any] = dict(chunk_grid)
+    corrected["configuration"] = {**configuration, "chunk_shape": list(parsed)}
+    return corrected
 
 
 @dataclass(frozen=True, kw_only=True)

tests/test_metadata/test_common.py

@@ -0,0 +1,72 @@
+"""Tests for metadata helpers shared by both Zarr formats."""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+import numpy as np
+import pytest
+
+from zarr.core.metadata.common import parse_stored_chunk_shape
+from zarr.errors import ZarrUserWarning
+
+
+@pytest.mark.parametrize(
+    ("chunk_shape", "shape", "expected", "warns"),
+    [
+        ((4, 5), (10, 10), (4, 5), False),
+        ((1, 1), (0, 0), (1, 1), False),
+        ((0,), (0,), (1,), True),
+        ((False,), (0,), (1,), True),
+        ((np.int64(0),), (0,), (1,), True),
+        ((4, 0), (4, 0), (4, 1), True),
+        ((0, 0), (0, 0), (1, 1), True),
+        ((2, [5, 10, 5]), (6, 20), (2, [5, 10, 5]), False),
+    ],
+    ids=[
+        "valid",
+        "valid-on-empty-axes",
+        "legacy-zero",
+        "legacy-json-false",
+        "legacy-numpy-zero",
+        "only-empty-axis-corrected",
+        "every-empty-axis-corrected",
+        "edge-list-passed-through",
+    ],
+)
+def test_parse_stored_chunk_shape(
+    chunk_shape: tuple[Any, ...], shape: tuple[int, ...], expected: tuple[Any, ...], warns: bool
+) -> None:
+    """A valid chunk shape is returned as is; a chunk size of 0 on a zero-length
+    axis is read as 1, with a warning naming the writer and how to re-save."""
+    with warnings.catch_warnings(record=True) as record:
+        warnings.simplefilter("always")
+        parsed = parse_stored_chunk_shape(chunk_shape, shape, legacy_writers="an old writer")
+    assert parsed == expected
+    messages = [str(w.message) for w in record if issubclass(w.category, ZarrUserWarning)]
+    assert bool(messages) is warns
+    for message in messages:
+        assert "an old writer" in message
+        assert "update_attributes({})" in message
+
+
+def test_parse_stored_chunk_shape_rejects_dimension_mismatch() -> None:
+    """The chunk shape needs one entry per array axis."""
+    with pytest.raises(ValueError, match="same number of dimensions"):
+        parse_stored_chunk_shape((4,), (10, 10), legacy_writers="an old writer")
+
+
+@pytest.mark.parametrize(("chunk_shape", "shape"), [((0,), (5,)), ((4, 0), (4, 3))])
+def test_parse_stored_chunk_shape_rejects_zero_on_nonempty_axis(
+    chunk_shape: tuple[int, ...], shape: tuple[int, ...]
+) -> None:
+    """A chunk size of 0 is only tolerated on a zero-length axis."""
+    with pytest.raises(ValueError, match="chunk edge length must be >= 1, got 0"):
+        parse_stored_chunk_shape(chunk_shape, shape, legacy_writers="an old writer")
+
+
+def test_parse_stored_chunk_shape_rejects_negative() -> None:
+    """A negative chunk size is rejected even on a zero-length axis."""
+    with pytest.raises(ValueError, match="chunk edge length must be >= 1, got -1"):
+        parse_stored_chunk_shape((-1,), (0,), legacy_writers="an old writer")

tests/test_metadata/test_v2.py

@@ -309,35 +309,6 @@ def test_from_dict_extra_fields() -> None:
     assert result == expected
 
 
-@pytest.mark.parametrize(
-    ("shape", "chunks", "expected"),
-    [((0,), (0,), (1,)), ((4, 0), (4, 0), (4, 1)), ((0, 0), (0, 0), (1, 1))],
-)
-def test_zero_chunk_edge_on_empty_axis_normalized(
-    shape: tuple[int, ...], chunks: tuple[int, ...], expected: tuple[int, ...]
-) -> None:
-    """A stored chunk edge of 0 on a zero-length axis is read as 1, with a warning.
-
-    This checks the compatibility policy for legacy metadata: the in-memory
-    chunk size becomes positive while the extent remains zero. It does not
-    test historical reader behavior or perform array I/O.
-    """
-    with pytest.warns(ZarrUserWarning, match="chunk edge length 0 on a zero-length axis"):
-        meta = ArrayV2Metadata(
-            shape=shape, dtype=Float64(), chunks=chunks, fill_value=0.0, order="C"
-        )
-    assert meta.chunks == expected
-
-
-@pytest.mark.parametrize(("shape", "chunks"), [((5,), (0,)), ((4, 3), (4, 0))])
-def test_zero_chunk_edge_with_positive_extent_rejected(
-    shape: tuple[int, ...], chunks: tuple[int, ...]
-) -> None:
-    """A chunk edge of 0 on a positive-length axis is rejected."""
-    with pytest.raises(ValueError, match="chunk edge length must be >= 1"):
-        ArrayV2Metadata(shape=shape, dtype=Float64(), chunks=chunks, fill_value=0.0, order="C")
-
-
 def test_eq_nan_fill_value() -> None:
     """Two metadata objects with an identical NaN fill_value compare equal.
 

tests/test_metadata/test_v3.py

@@ -463,35 +463,3 @@ def test_group_metadata_to_dict_consolidated(attributes: dict[str, Any] | None)
             },
         },
     }
-
-
-@pytest.mark.parametrize(
-    ("shape", "chunk_shape", "expected"),
-    [
-        ((0,), [0], (1,)),
-        ((4, 0), [4, 0], (4, 1)),
-        ((0, 0), [0, 0], (1, 1)),
-        ((0,), [False], (1,)),
-    ],
-    ids=["1d", "one-empty-axis", "all-empty-axes", "json-false"],
-)
-def test_zero_chunk_size_on_empty_axis_normalized(
-    shape: tuple[int, ...], chunk_shape: list[Any], expected: tuple[int, ...]
-) -> None:
-    """A stored regular chunk size of 0 on a zero-length axis is read as 1, with a warning.
-
-    zarr-python 3.0 and 3.1 wrote this for an array created with a zero-length
-    axis; 3.0 wrote JSON `false` for `chunks=False`. This is the Zarr format 3
-    counterpart of the policy `ArrayV2Metadata` applies.
-    """
-    from zarr.core.metadata.v3 import RegularChunkGridMetadata
-    from zarr.errors import ZarrUserWarning
-
-    d = minimal_metadata_dict_v3(
-        shape=shape,
-        chunk_grid={"name": "regular", "configuration": {"chunk_shape": chunk_shape}},
-    )
-    with pytest.warns(ZarrUserWarning, match="zero-length axis"):
-        meta = ArrayV3Metadata.from_dict(d)  # type: ignore[arg-type]
-    assert isinstance(meta.chunk_grid, RegularChunkGridMetadata)
-    assert meta.chunk_grid.chunk_shape == expected