fix(chunk-grids): judge every chunk specification by the chunk normalizer alone

[d-v-b]

This AI-written PR consolidates the logic for parsing a chunk request into one function, where previously we had 2 paths that separately handled chunk- and shard-like requests, and that led to bugs as the two paths disagreed. one function should at least keep the bugs in one place :)

🤖 AI text below 🤖

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.

Follow-up to #4374.

Problem

The chunk normalizer (normalize_chunks_nd → normalize_chunks_1d) was not the only judge of a chunks=/shards= specification. A separate duck-typed classifier, _is_rectilinear_chunks, ran on the raw input at three sites (AsyncArray._create, init_array, resolve_outer_and_inner_chunks) to decide whether the specification was rectilinear, so that the Zarr format 2 and sharding restrictions could fire. Two opinions on the same input is the shape of the bug in #4374, and they could disagree: a 0-d NumPy array counted as rectilinear because it has __iter__, and ChunkGrid.from_sizes collapsed a uniform edge list to a regular dimension while normalize_chunks_1d kept it rectilinear.

Changes

• One judge. _is_rectilinear_chunks is deleted. Each site normalizes first and asks the resulting ChunkGrid (is_regular). Regular and rectilinear shard specifications go through the same normalizer.
• One integer rule in the normalizer (_chunk_int): a chunk size is anything Python's integer protocol (operator.index) accepts: int, NumPy integer scalars and 0-d integer arrays. Floats, arrays with dimensions and NumPy booleans are not integers. A Python bool is still an int (0 or 1), as in 3.4.0.
• An explicit edge list declares a rectilinear dimension everywhere. ChunkGrid.from_sizes no longer collapses uniform edges, matching normalize_chunks_1d. So a stored RectilinearChunkGridMetadata passed as chunks= is treated the same whether its edges are uniform or not: zarr.create stores it as a rectilinear grid, as create_array does (3.4.0 stored RectilinearChunkGridMetadata(((5, 5),)) as a regular [5], A rectilinear chunk spec with a short trailing chunk is silently normalized to a regular grid, changing resize semantics #4272). A RectilinearChunkGridMetadata made only of bare integers declares no edge list, so it is the regular grid it describes (accepted for Zarr format 2 and as the chunk shape of a sharded array).
• Legacy zarr.create(..., zarr_format=2) used chunks or chunk_shape, so a NumPy array such as chunks=np.array([5, 3]) failed with "truth value of an array is ambiguous". A small predicate (_v2_chunks_given) now decides whether chunks was given: falsy values (None, 0, [], (), False, np.int64(0), np.array(0), np.array([0])) still mean automatic chunking, exactly as in 3.4.0; a NumPy array with more than one element is always given.
• Errors: a non-integer scalar specification (2.0, np.float64(2.0), a 0-d float array) raises the normalizer's own TypeError naming it (was "object has no len()" or "len() of unsized object").
• Typing: normalize_chunks_nd(chunks: ChunksLike | None, ...); shard_spec uses the existing aliases instead of Any.

Not changed in this patch release: chunks=True still raises ValueError, and a bool inside a specification is still read as 1 or 0. Rejecting booleans with one TypeError is part of the 3.5.0 follow-up.

Compatibility with 3.4.0

In the 244-row behaviour table run against a real 3.4.0 install, this branch changes no result that 3.4.0 handled correctly. The rows it changes: zarr.create(chunks=np.array([5, 5]), zarr_format=2) and np.array([]) now work (3.4.0 raised a truth-value error with current NumPy); a uniform RectilinearChunkGridMetadata passed to zarr.create is stored as rectilinear (gh-4272). check_patch.py: OK, 0 undocumented changes, 0 warnings-only changes.

Tests

• tests/test_unified_chunk_grid.py: one table for the legacy Zarr format 2 chunks argument (every falsy spelling auto-chunks, np.array(7) → (7, 7), np.array([5, 3]) → (5, 3)) and one error test for np.array([0, 0]); the classifier's tests are replaced by one test that the Zarr format 2 and sharding restrictions recognize every rectilinear specification (whichever dimension carries the list, uniform edges included) through create_array and zarr.create; the uniform-edge resize test covers edges given as lists and as metadata.
• tests/test_chunk_grids.py: NumPy booleans are rejected by the normalizer; NumPy inputs join the existing normalizer tables.

Stack and release notes

• Target: 3.4.1 (patch). Independent of fix(chunk-grids): require chunk sizes of at least 1 and read the 0, false and true sizes older releases stored #4334, fix(chunk-grids): read mixed regular/rectilinear chunk grids written by zarr 3.2.x #4375 and test(chunk-grids): sample the full rectilinear chunk grid declaration space #4377.
• Conflicts with fix(chunk-grids): require chunk sizes of at least 1 and read the 0, false and true sizes older releases stored #4334: the two PRs conflict in two small hunks; the resolution keeps both changes:
  • src/zarr/core/chunk_grids.py, resolve_outer_and_inner_chunks: keep this PR's single normalizer call and add fix(chunk-grids): require chunk sizes of at least 1 and read the 0, false and true sizes older releases stored #4334's unit, outer = normalize_chunks_nd(shard_spec, array_shape, unit=chunks.chunk_shape).
  • tests/test_unified_chunk_grid.py: keep both imports (import re from fix(chunk-grids): require chunk sizes of at least 1 and read the 0, false and true sizes older releases stored #4334, from functools import partial from this PR).
• On 2026-09-29 the agent merged main (cd1e5b3) into this branch. The one conflict was in ChunkGrid.from_sizes, where main had switched the uniform-edge collapse to ceildiv_int; the resolution keeps this PR's removal of that collapse.
• After a review of the set on 2026-09-29, the agent pushed 007f60c. _chunk_list no longer checks isinstance(chunks, Iterable) before list(chunks). That check rejected sequences that define only __getitem__ and __len__, which 3.4.0 accepted as chunks=. Two cases in test_normalize_chunks cover this. The full test suite passes (11765).

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 zarr-metadata | 🛠️ Build #34778781 | 📁 Comparing 9016f32 against latest (1187a43)

  🔍 Preview build  

9 files changed · ± 9 modified

± Modified

• api/index.html
• api/model/index.html
• api/pydantic/index.html
• api/v2/index.html
• api/v3/index.html
• api/v3/chunk_grid/index.html
• api/v3/chunk_key_encoding/index.html
• api/v3/codec/index.html
• api/v3/data_type/index.html

[read-the-docs-community]

Documentation build overview

📚 zarr-indexing | 🛠️ Build #34831131 | 📁 Comparing 37fc614 against latest (1187a43)

  🔍 Preview build  

No files changed.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.68%. Comparing base (f078bd3) to head (81d97e0).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4376      +/-   ##
==========================================
- Coverage   94.69%   94.68%   -0.01%     
==========================================
  Files          94       94              
  Lines       13604    13596       -8     
==========================================
- Hits        12882    12874       -8     
  Misses        722      722              

Files with missing lines	Coverage Δ
src/zarr/api/asynchronous.py	96.46% <ø> (ø)
src/zarr/api/synchronous.py	95.77% <ø> (ø)
src/zarr/core/array.py	98.39% <100.00%> (+0.09%)	⬆️
src/zarr/core/chunk_grids.py	96.35% <100.00%> (-0.39%)	⬇️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.