refactor(metadata): scope the stored chunk shape check to regular chunk grids

`parse_stored_chunk_shape` passed non-integer entries through "for the
caller's own parser", which made a regular-grid policy look like a
general chunk shape routine and let it decide what a 0-length chunk means
for grids it does not own. A rectilinear grid, or any other grid, is free
to define its own semantics for 0-length chunks.

It is now `parse_stored_regular_chunk_shape`, typed `Sequence[int]`, with
no pass-through, and its docstring says it applies to Zarr format 2
`chunks` and Zarr format 3 `regular` grids only. The Zarr format 3 caller
hands it a chunk shape only when the grid is named `regular` and every
entry is an integer (`_is_regular_chunk_shape`); anything else is not a
regular chunk shape and goes to the chunk grid parser untouched.

Assisted-by: ClaudeCode:claude-opus-5

Author: d-v-b

src/zarr/core/metadata/common.py

@@ -1,8 +1,7 @@
 from __future__ import annotations
 
-import numbers
 import warnings
-from typing import TYPE_CHECKING, Any, Final
+from typing import TYPE_CHECKING, Final
 
 from zarr.errors import ZarrUserWarning
 
@@ -29,33 +28,32 @@ def parse_attributes(data: dict[str, JSON] | None) -> dict[str, JSON]:
     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.
+def parse_stored_regular_chunk_shape(
+    chunk_shape: Sequence[int], shape: Sequence[int], *, legacy_writers: str
+) -> tuple[int, ...]:
+    """Validate a stored regular chunk grid's 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.
+    This is for regular chunk grids only: Zarr format 2 `chunks`, and the
+    `chunk_shape` of a Zarr format 3 `regular` grid. Another chunk grid, such
+    as the rectilinear grid, is free to define its own meaning for a chunk of
+    length 0, so its chunk sizes must not be passed here.
 
-    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
+    The chunk shape must have one entry per array axis, and every 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] = []
+    parsed: list[int] = []
     for dim_idx, (size, extent) in enumerate(zip(chunk_shape, shape, strict=True)):
-        if isinstance(size, numbers.Integral) and size < 1:
+        if size < 1:
             if size < 0 or extent != 0:
                 raise ValueError(
                     f"Dimension {dim_idx}: chunk edge length must be >= 1, got {size!r}"

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 parse_attributes, parse_stored_chunk_shape
+from zarr.core.metadata.common import parse_attributes, parse_stored_regular_chunk_shape
 
 
 class ArrayV2MetadataDict(TypedDict):
@@ -88,7 +88,7 @@ def __init__(
         Metadata for a Zarr format 2 array.
         """
         shape_parsed = parse_shapelike(shape)
-        chunks_parsed = parse_stored_chunk_shape(
+        chunks_parsed = parse_stored_regular_chunk_shape(
             parse_shapelike(chunks),
             shape_parsed,
             legacy_writers="zarr-python 2.x, and by 3.x before 3.4",

src/zarr/core/metadata/v3.py

@@ -5,6 +5,7 @@
 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
@@ -35,7 +36,7 @@
 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 parse_attributes, parse_stored_chunk_shape
+from zarr.core.metadata.common import parse_attributes, parse_stored_regular_chunk_shape
 from zarr.errors import MetadataValidationError, NodeTypeValidationError
 from zarr.registry import get_codec_class
 
@@ -476,26 +477,43 @@ class ArrayMetadataJSON_V3(TypedDict, extra_items=AllowedExtraField):  # type: i
 }
 
 
-def _read_legacy_zero_chunk_sizes(
+def _is_regular_chunk_shape(value: object) -> TypeGuard[Sequence[int]]:
+    """Whether a stored `chunk_shape` is a regular chunk shape: a sequence of integers.
+
+    JSON `false` counts, because `bool` is an integer type.
+    """
+    return (
+        isinstance(value, Sequence)
+        and not isinstance(value, str)
+        and all(isinstance(size, int | np.integer) for size in value)
+    )
+
+
+def _parse_stored_regular_chunk_grid(
     chunk_grid: dict[str, JSON] | ChunkGridMetadata | NamedConfig[str, Any],
     shape: tuple[int, ...],
 ) -> dict[str, JSON] | ChunkGridMetadata | NamedConfig[str, Any]:
-    """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.
+    """Check a stored regular chunk grid's chunk shape against the array shape.
+
+    Only a `regular` grid whose `chunk_shape` is all integers is a regular chunk
+    shape, and only that is handed to `parse_stored_regular_chunk_shape`.
+    Anything else is not a regular chunk shape and is left for the chunk grid
+    parser: other grids define their own chunk semantics. zarr-python 3.0 and
+    3.1 stored `chunk_shape: [0]` (and 3.0 `[false]`) for an array created with
+    a zero-length axis. This runs here rather than in the grid parser because
+    it needs the array shape, which chunk grid metadata does not carry.
     """
     if not isinstance(chunk_grid, Mapping) or chunk_grid.get("name") != "regular":
         return chunk_grid
     configuration = chunk_grid.get("configuration")
     if not isinstance(configuration, Mapping):
         return chunk_grid
     chunk_shape = configuration.get("chunk_shape")
-    if not isinstance(chunk_shape, Sequence) or isinstance(chunk_shape, str):
+    if not _is_regular_chunk_shape(chunk_shape):
         return chunk_grid
-    parsed = parse_stored_chunk_shape(chunk_shape, shape, legacy_writers="zarr-python 3.0 and 3.1")
+    parsed = parse_stored_regular_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
@@ -536,7 +554,7 @@ def __init__(
 
         shape_parsed = parse_shapelike(shape)
         chunk_grid_parsed = parse_chunk_grid(
-            _read_legacy_zero_chunk_sizes(chunk_grid, shape_parsed)
+            _parse_stored_regular_chunk_grid(chunk_grid, shape_parsed)
         )
         chunk_key_encoding_parsed = parse_chunk_key_encoding(chunk_key_encoding)
         dimension_names_parsed = parse_dimension_names(dimension_names)

tests/test_metadata/test_common.py

@@ -8,7 +8,7 @@
 import numpy as np
 import pytest
 
-from zarr.core.metadata.common import parse_stored_chunk_shape
+from zarr.core.metadata.common import parse_stored_regular_chunk_shape
 from zarr.errors import ZarrUserWarning
 
 
@@ -22,7 +22,6 @@
         ((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",
@@ -32,17 +31,18 @@
         "legacy-numpy-zero",
         "only-empty-axis-corrected",
         "every-empty-axis-corrected",
-        "edge-list-passed-through",
     ],
 )
-def test_parse_stored_chunk_shape(
+def test_parse_stored_regular_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")
+        parsed = parse_stored_regular_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
@@ -51,22 +51,22 @@ def test_parse_stored_chunk_shape(
         assert "update_attributes({})" in message
 
 
-def test_parse_stored_chunk_shape_rejects_dimension_mismatch() -> None:
+def test_parse_stored_regular_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")
+        parse_stored_regular_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(
+def test_parse_stored_regular_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")
+        parse_stored_regular_chunk_shape(chunk_shape, shape, legacy_writers="an old writer")
 
 
-def test_parse_stored_chunk_shape_rejects_negative() -> None:
+def test_parse_stored_regular_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")
+        parse_stored_regular_chunk_shape((-1,), (0,), legacy_writers="an old writer")