revert: keep the strict chunk-size changes in zarr-developers#4431, out of this patch PR

Reverts 47587bc, baddb31 and ad34ae8, and the error-message part of
e547401. Rejecting a chunk size of 0 in ArrayV2Metadata and
ShardingCodec, and no longer reading a falsy `chunks` as absent in the
legacy Zarr format 2 zarr.create, reject inputs zarr 3.4.0 accepted; this
PR targets the 3.4.1 patch release, which must not. zarr-developers#4431 makes the same
changes, more strictly, for the next minor release. The widened chunk and
shard annotations and the zarr.create docstring fix stay.

Assisted-by: ClaudeCode:claude-opus-5-5
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: d-v-b

changes/4376.bugfix.md

@@ -1 +1 @@
-Chunk specifications are judged only by the chunk normalizer: the separate duck-typed check for rectilinear input is gone, so the Zarr format 2 and sharding restrictions apply to what the normalized grid says was declared. A chunk size is an integer by Python's integer protocol: numpy integer scalars and 0-d integer arrays are accepted wherever a chunk or shard shape is. The legacy `zarr.create(..., zarr_format=2)` no longer tests the truth value of `chunks`: only `None` means not given, as for Zarr format 3. `chunks=False` is now one chunk instead of an automatic chunk shape, numpy arrays work, and `0`, `[]` and `np.array([0])` raise instead of chunking automatically. A non-integer scalar chunk specification raises a `TypeError` naming the problem. An explicit list of chunk edges declares a rectilinear dimension everywhere, including a stored rectilinear chunk grid passed as `chunks=` whose edges happen to be uniform, so the Zarr format 2 and sharding restrictions treat it the same whether it is given as lists or as metadata, and `zarr.create` stores it as a rectilinear chunk grid, as `create_array` does. A `RectilinearChunkGridMetadata` made only of bare integers declares no explicit edge list, so it is read as the regular grid it describes: it is accepted for Zarr format 2 and as the chunk shape of a sharded array. The `chunks` and `chunk_shape` parameters of `zarr.create` and the `ShardsLike` type now declare every chunk specification the normalizer accepts, including numpy integers and arrays, explicit edge lists and stored chunk grid metadata. The chunk shape of `ArrayV2Metadata` and the inner chunk shape of `ShardingCodec` are parsed with the chunk normalizer's integer test as a regular chunk shape: every size must be at least 1, so `ArrayV2Metadata(chunks=(0,))` raises a `ValueError` as the Zarr format 3 regular chunk grid does (a stored Zarr format 2 chunk size of 0 is still repaired on read), a stored inner chunk size of 0 raises a `ValueError` instead of a `ZeroDivisionError` on read, and an explicit list of chunk edges is rejected with a `TypeError`.
+Chunk specifications are judged only by the chunk normalizer: the separate duck-typed check for rectilinear input is gone, so the Zarr format 2 and sharding restrictions apply to what the normalized grid says was declared. A chunk size is an integer by Python's integer protocol: numpy integer scalars and 0-d integer arrays are accepted wherever a chunk or shard shape is. The legacy `zarr.create(..., zarr_format=2)` no longer tests the truth value of a numpy array given as `chunks`, so numpy arrays work there. A non-integer scalar chunk specification raises a `TypeError` naming the problem. An explicit list of chunk edges declares a rectilinear dimension everywhere, including a stored rectilinear chunk grid passed as `chunks=` whose edges happen to be uniform, so the Zarr format 2 and sharding restrictions treat it the same whether it is given as lists or as metadata, and `zarr.create` stores it as a rectilinear chunk grid, as `create_array` does. A `RectilinearChunkGridMetadata` made only of bare integers declares no explicit edge list, so it is read as the regular grid it describes: it is accepted for Zarr format 2 and as the chunk shape of a sharded array. The `chunks` and `chunk_shape` parameters of `zarr.create` and the `ShardsLike` type now declare every chunk specification the normalizer accepts, including numpy integers and arrays, explicit edge lists and stored chunk grid metadata.

src/zarr/codecs/sharding.py

@@ -36,7 +36,7 @@
     default_buffer_prototype,
     numpy_buffer_prototype,
 )
-from zarr.core.chunk_grids import ChunkGrid, parse_regular_chunk_shape
+from zarr.core.chunk_grids import ChunkGrid
 from zarr.core.chunk_utils import (
     ChunkTransform,
     decode_and_scatter_chunk,
@@ -47,6 +47,7 @@
 from zarr.core.common import (
     ShapeLike,
     parse_named_configuration,
+    parse_shapelike,
     product,
 )
 from zarr.core.config import config as zarr_config
@@ -467,7 +468,7 @@ def __init__(
         index_location: ShardingCodecIndexLocation | IndexLocation = "end",
         subchunk_write_order: SubchunkWriteOrder = "morton",
     ) -> None:
-        chunk_shape_parsed = parse_regular_chunk_shape(chunk_shape)
+        chunk_shape_parsed = parse_shapelike(chunk_shape)
         codecs_parsed = parse_codecs(codecs)
         index_codecs_parsed = parse_codecs(index_codecs)
         _check_index_codecs_fixed_size(index_codecs_parsed)
@@ -506,7 +507,7 @@ def __getstate__(self) -> dict[str, Any]:
 
     def __setstate__(self, state: dict[str, Any]) -> None:
         config = state["configuration"]
-        object.__setattr__(self, "chunk_shape", parse_regular_chunk_shape(config["chunk_shape"]))
+        object.__setattr__(self, "chunk_shape", parse_shapelike(config["chunk_shape"]))
         object.__setattr__(self, "codecs", parse_codecs(config["codecs"]))
         object.__setattr__(self, "index_codecs", parse_codecs(config["index_codecs"]))
         object.__setattr__(self, "index_location", _parse_index_location(config["index_location"]))

src/zarr/core/array.py

@@ -351,6 +351,18 @@ def _array_metadata_dict_v3(zarr_json_bytes: Buffer) -> dict[str, JSON]:
     return metadata_dict
 
 
+def _v2_chunks_given(chunks: object) -> bool:
+    """Whether the legacy Zarr format 2 `chunks` argument is given.
+
+    A falsy `chunks` (such as `None`, 0, `[]` or `False`) is read as not given. A numpy
+    array with more than one element has no truth value and is always given; a shorter
+    one is given when its element is nonzero (an empty array is not given).
+    """
+    if isinstance(chunks, np.ndarray):
+        return chunks.size > 1 or bool(chunks.any())
+    return bool(chunks)
+
+
 @dataclass(frozen=True)
 class AsyncArray[T_ArrayMetadata: (ArrayV2Metadata, ArrayV3Metadata)]:
     """
@@ -520,10 +532,11 @@ async def _create(
             item_size = 1
             if isinstance(dtype_parsed, HasItemSize):
                 item_size = dtype_parsed.item_size
-            if _raw_chunks is None:
+            _raw_v2 = chunks if _v2_chunks_given(chunks) else chunk_shape
+            if _raw_v2 is None:
                 outer_chunks = guess_chunks(shape, item_size)
             else:
-                outer_chunks = normalize_chunks_nd(_raw_chunks, shape)
+                outer_chunks = normalize_chunks_nd(_raw_v2, shape)
             if not outer_chunks.is_regular:
                 raise ValueError("Zarr format 2 does not support rectilinear chunk grids.")
             _chunks = outer_chunks.chunk_shape

src/zarr/core/chunk_grids.py

@@ -824,9 +824,7 @@ def normalize_chunks_nd(
 
     if chunks is None or chunks is True:
         raise ValueError(
-            f"{chunks!r} is not a valid chunk input. For automatic chunking pass "
-            f'chunks="auto" to `create_array` or chunks=None to `zarr.create`; otherwise '
-            f"pass an int or a sequence of ints."
+            f'{chunks!r} is not a valid chunk input. Use chunks=None or chunks="auto" from the top-level API for auto-chunking, or pass an int / tuple of ints.'
         )
 
     # handle no chunking: one chunk covering every axis.
@@ -853,35 +851,6 @@ def normalize_chunks_nd(
     )
 
 
-def parse_regular_chunk_shape(chunk_shape: ShapeLike) -> tuple[int, ...]:
-    """Parse the chunk shape of a regular chunk grid that has no array shape to be
-    normalized against, such as the inner chunk shape of a shard.
-
-    The chunk normalizer's integer test (`_chunk_int`) decides what a chunk size is, and
-    every chunk size is at least 1. A single integer is a one-dimensional chunk shape.
-    Without the lengths of the axes `-1` and `False` cannot be resolved, so they are
-    rejected as non-positive; an explicit list of chunk edges declares a rectilinear
-    dimension, which a regular chunk grid cannot have, and is rejected as a non-integer.
-    """
-    size = _chunk_int(chunk_shape)
-    elements = [size] if size is not None else _chunk_list(chunk_shape)
-    as_ints = [_chunk_int(e) for e in elements]
-    non_int = [
-        (idx, e) for idx, (e, i) in enumerate(zip(elements, as_ints, strict=True)) if i is None
-    ]
-    if non_int:
-        non_int_idxs, non_int_vals = [*zip(*non_int, strict=False)]
-        raise TypeError(
-            f"Each chunk size of a regular chunk shape must be an integer; got non-integer "
-            f"element(s) {non_int_vals!r} at indices {non_int_idxs!r}. A regular chunk shape "
-            f"is a flat sequence of positive integers, one per dimension (e.g. [10, 10])."
-        )
-    sizes = tuple(i for i in as_ints if i is not None)
-    if any(c < 1 for c in sizes):
-        raise ValueError(f"All chunk sizes must be positive, got {list(sizes)}")
-    return sizes
-
-
 def guess_chunks(
     shape: tuple[int, ...], typesize: int, *, max_bytes: int | None = None
 ) -> ChunkGrid:

src/zarr/core/metadata/v2.py

@@ -33,7 +33,6 @@
 
 from zarr.core._json import json_to_buffer
 from zarr.core.array_spec import ArrayConfig, ArraySpec
-from zarr.core.chunk_grids import parse_regular_chunk_shape
 from zarr.core.chunk_key_encodings import parse_separator
 from zarr.core.common import (
     JSON,
@@ -332,10 +331,9 @@ def parse_compressor(data: object) -> Numcodec | None:
 
 
 def parse_chunks(chunks: ShapeLike, shape: tuple[int, ...]) -> tuple[int, ...]:
-    """Check a chunk shape: one integer of at least 1 per array axis, as a regular chunk
-    shape (see `parse_regular_chunk_shape`). Stored chunk sizes of 0 are read by
-    `zarr.core.metadata.repair` before they get here."""
-    chunks_parsed = parse_regular_chunk_shape(chunks)
+    """Check a chunk shape: one non-negative integer per array axis (see
+    `parse_shapelike`). Stored chunk sizes of 0 are read by `zarr.core.metadata.repair`."""
+    chunks_parsed = parse_shapelike(chunks)
     if len(chunks_parsed) != len(shape):
         raise ValueError(
             f"The `shape` and `chunks` attributes must have the same length. "

tests/test_codecs/test_sharding.py

@@ -765,13 +765,15 @@ def test_structured_dtype_fill_value() -> None:
     [
         ShardingCodec(chunk_shape=(8, 8)),
         ShardingCodec(chunk_shape=(8, 8), subchunk_write_order="lexicographic"),
+        ShardingCodec(chunk_shape=(0,)),
     ],
-    ids=["default", "lexicographic"],
+    ids=["default", "lexicographic", "zero-chunk-size"],
 )
 def test_pickle(codec: ShardingCodec) -> None:
     """ShardingCodec round-trips through pickle, including the non-serialized
     ``subchunk_write_order`` (which ``to_dict`` omits and which must not silently
-    revert to the ``morton`` default)."""
+    revert to the ``morton`` default), and an inner chunk size of 0, which the
+    constructor accepts."""
     restored = pickle.loads(pickle.dumps(codec))
     assert restored == codec
     assert restored.chunk_shape == codec.chunk_shape

tests/test_metadata/test_repair.py

@@ -254,7 +254,7 @@ def _open_strictly(path: Path, mode: Literal["r", "a", "r+"] = "r") -> AnyArray:
 
 def test_stored_negative_chunk_size_rejected() -> None:
     """No known writer stored a negative chunk size: it is rejected, not repaired."""
-    with pytest.raises(ValueError, match=r"^All chunk sizes must be positive, got \[-1\]$"):
+    with pytest.raises(ValueError, match="^Expected all values to be non-negative"):
         _read_strictly(_v2_doc([4], [-1]))
 
 
@@ -331,9 +331,9 @@ def test_read_invalid_edges_in_rectilinear_grid(
         (_v3_doc([4], [4.5]), "Dimension 0: chunk edge length must be an int, got 4.5"),
         (
             _v3_doc([8], [4], inner=[2.0]),
-            "got non-integer element(s) (2.0,) at indices (0,)",
+            "Expected an iterable of integers. Got [2.0] instead.",
         ),
-        (_v2_doc([20], [10.0]), "got non-integer element(s) (10.0,) at indices (0,)"),
+        (_v2_doc([20], [10.0]), "Expected an iterable of integers. Got [10.0] instead."),
         (
             _rectilinear_doc([8], [[[4, 2.0]]]),
             "Dimension 0: RLE repeat count must be an int, got 2.0",
@@ -504,9 +504,8 @@ def _sharding_chunk_shape(chunks: Any) -> tuple[tuple[int, ...], object]:
     "v2": lambda chunks: ((md := _v2_metadata(chunks)).chunks, md.to_dict()["chunks"]),
     "sharding-inner": _sharding_chunk_shape,
 }
-"""`ArrayV2Metadata` and `ShardingCodec` read a regular chunk shape (see
-`parse_regular_chunk_shape`), returning the chunk shape and the value `to_dict` writes
-for it."""
+"""`ArrayV2Metadata` and `ShardingCodec` read a chunk shape as an array shape, returning
+the chunk shape and the value `to_dict` writes for it."""
 
 
 @pytest.mark.parametrize("site", CHUNK_SHAPE_SITES)
@@ -520,44 +519,37 @@ def _sharding_chunk_shape(chunks: Any) -> tuple[tuple[int, ...], object]:
         ((np.int64(4),), (4,)),
         (np.array([4]), (4,)),
         ((True,), (1,)),
+        ((0,), (0,)),
+        ((False,), (0,)),
         (range(4, 5), (4,)),
     ],
 )
-def test_regular_chunk_shape(site: str, chunks: object, expected: tuple[int, ...]) -> None:
-    """`ArrayV2Metadata` and `ShardingCodec` read their chunk shape with the chunk
-    normalizer's integer test: an integer or an iterable of integers of at least 1,
-    including NumPy integers and bools, written back as given. Reading a stored 0 is
-    `zarr.core.metadata.repair`' business, before the constructors see it."""
+def test_chunk_shape_read_as_array_shape(
+    site: str, chunks: object, expected: tuple[int, ...]
+) -> None:
+    """`ArrayV2Metadata` and `ShardingCodec` read their chunk shape as `parse_shapelike`
+    reads an array shape: an integer or an iterable of non-negative integers, including
+    NumPy integers and bools. A chunk size of 0 is written back as given; reading a
+    stored 0 is `zarr.core.metadata.repair`' business."""
     parsed, written = CHUNK_SHAPE_SITES[site](chunks)
     assert parsed == expected
     assert all(type(size) is int for size in parsed)
     assert written == expected
 
 
 @pytest.mark.parametrize("site", CHUNK_SHAPE_SITES)
-@pytest.mark.parametrize("chunks", [(0,), (False,), (-1,), 0])
-def test_regular_chunk_shape_rejects_non_positive(site: str, chunks: object) -> None:
-    """A chunk size below 1 is rejected, including `-1` and `False`, which have no axis
-    length to be resolved against here."""
-    with pytest.raises(ValueError, match="All chunk sizes must be positive"):
-        CHUNK_SHAPE_SITES[site](chunks)
+def test_chunk_shape_read_as_array_shape_rejects_negative(site: str) -> None:
+    with pytest.raises(ValueError, match="Expected all values to be non-negative"):
+        CHUNK_SHAPE_SITES[site]((-1,))
 
 
 @pytest.mark.parametrize("site", CHUNK_SHAPE_SITES)
-@pytest.mark.parametrize("chunks", [(4.0,), "4", [[2, 2]]])
-def test_regular_chunk_shape_rejects_non_integer(site: str, chunks: object) -> None:
-    """A non-integer chunk size is rejected, and so is an explicit list of chunk edges,
-    which declares a rectilinear dimension that a regular chunk shape cannot have."""
-    with pytest.raises(TypeError, match="Each chunk size of a regular chunk shape must be"):
+@pytest.mark.parametrize("chunks", [(4.0,), "4", None])
+def test_chunk_shape_read_as_array_shape_rejects_non_integer(site: str, chunks: object) -> None:
+    with pytest.raises(TypeError, match="Expected an"):
         CHUNK_SHAPE_SITES[site](chunks)
 
 
-@pytest.mark.parametrize("site", CHUNK_SHAPE_SITES)
-def test_regular_chunk_shape_rejects_non_iterable(site: str) -> None:
-    with pytest.raises(TypeError, match="must be an integer or an iterable of integers"):
-        CHUNK_SHAPE_SITES[site](None)
-
-
 def _rewrite_doc(path: Path, zarr_format: Literal[2, 3], edit: Any) -> None:
     doc_path = path / (".zarray" if zarr_format == 2 else "zarr.json")
     doc = json.loads(doc_path.read_text())
@@ -985,6 +977,30 @@ def test_from_dict_keeps_values_that_are_not_json(codec: Any) -> None:
     assert isinstance(metadata.codecs[0], ShardingCodec)
 
 
+@pytest.mark.parametrize(("shape", "expected"), [((0,), (1,)), ((3,), (1,))])
+def test_array_from_metadata_with_chunk_size_zero(shape: tuple[int], expected: tuple[int]) -> None:
+    """`ArrayV2Metadata` accepts a chunk size of 0, as a stored document may hold it. An
+    array built from such metadata reads it as the repairs read that document, silently
+    (no data was read or written under it): `create_hierarchy` stores the metadata as
+    given and yields such an array, which stores the repair before its first write."""
+    metadata = ArrayV2Metadata(shape=shape, chunks=(0,), dtype=Int16(), fill_value=0, order="C")
+    store = MemoryStore()
+    with warnings.catch_warnings():
+        warnings.simplefilter("error", ZarrUserWarning)
+        nodes = dict(zarr.create_hierarchy(store=store, nodes={"a": metadata}))
+    array = nodes["a"]
+    assert isinstance(array, zarr.Array)
+    assert array.chunks == expected
+    assert json.loads(store._store_dict["a/.zarray"].to_bytes())["chunks"] == [0]
+
+    array[...] = 1
+
+    # Writing an empty selection stores no chunks, so it stores no metadata either.
+    resaved = list(expected) if array.size else [0]
+    assert json.loads(store._store_dict["a/.zarray"].to_bytes())["chunks"] == resaved
+    np.testing.assert_array_equal(zarr.open_array(store, path="a")[...], np.ones(shape))
+
+
 def test_array_from_metadata_with_numpy_scalar_codec_configuration() -> None:
     """An array is built from metadata whose codec configuration holds NumPy scalars
     (which are not JSON values), as zarr always built one."""