fix: informative errors for None in chunk specifications

[d-v-b]

Summary

Passing None as a chunks parameter results in an uninformative TypeError, when it should raise an informative ValueError instead. This PR makes that change, along with some improvements to the signature of the chunk normalization routines. These routines are now shaped like regular normalization functions, with a wide input type (object) and a narrow output type.

These changes were written by claude.

See d-v-b#236 for the original claude-authored PR.

Author attestation

• I am a human, these are my changes, and I have reviewed and understood every change and can explain why each is correct.

TODO

• Add unit tests and/or doctests in docstrings
• Add docstrings and API docs for any new/modified user-facing classes and functions
• New/modified features documented in docs/user-guide/*.md
• Changes documented as a new file in changes/
• GitHub Actions have all passed
• Test coverage is 100% (Codecov passes)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.85%. Comparing base (80e00ae) to head (c730468).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4177   +/-   ##
=======================================
  Coverage   93.84%   93.85%           
=======================================
  Files          91       91           
  Lines       12549    12562   +13     
=======================================
+ Hits        11777    11790   +13     
  Misses        772      772           

Files with missing lines	Coverage Δ
src/zarr/core/array.py	97.86% <100.00%> (+<0.01%)	⬆️
src/zarr/core/chunk_grids.py	97.02% <100.00%> (+0.08%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[d-v-b]

i think this is a candidate for a self-merge. I plan to do so in ~8-16 hours

[mkitti]

What happens if chunks_input is False?

[mkitti]

Rather than checking for a few invalid values, should the check be if chunks is either "auto", an int, or a tuple of ints?

[d-v-b]

What happens if chunks_input is False?

chunks=false is valid for 2.x compatibility. it creates a single chunk for the whole array 🙃

Rather than checking for a few invalid values, should the check be if chunks is either "auto", an int, or a tuple of ints?

that leaves out iterables of ints, numpy arrays, etc. we have lower-level normalization for that.

[mkitti]

Suggested change

	if chunks_input is None or chunks_input is True:
	if not (
	chunks_input == "auto"
	or (isinstance(chunks_input, int) and not isinstance(chunks_input, bool))
	or (isinstance(chunks_input, tuple) and all(isinstance(v, int) and not isinstance(v, bool) for v in chunks_input))
	):

Perhaps we can actually verify if the value is valid or not

[mkitti]

Claude suggested something like this.

def _is_valid_chunks(value):
    if value == "auto":
        return True
    if isinstance(value, int) and not isinstance(value, bool):
        return True
    if isinstance(value, tuple) and all(
        isinstance(v, int) and not isinstance(v, bool) for v in value
    ):
        return True
    return False


if not _is_valid_chunks(chunks_input):
    raise ValueError(
        f'{chunks_input!r} is not a valid chunk input. Use chunks="auto" or omit the chunks '
        "argument for automatic chunking, or pass an int / tuple of ints."
    )

[d-v-b]

we already have type narrowing routines for this. we just need to handle "auto" and deprecated values before calling those functions

[Copilot]

Pull request overview

This PR hardens chunk specification normalization and improves user-facing error messages when invalid chunks values are provided (notably None and boolean-like inputs), aligning the normalizers with a “wide input / narrow output” pattern and ensuring API-level guidance is emitted from the top-level creation helpers.

Changes:

• Make normalize_chunks_1d / normalize_chunks_nd accept object inputs and raise more informative exceptions for invalid chunk specifications (e.g., None, bool, strings, non-iterables).
• Shift chunks=None / chunks=True guidance to init_array so API users are directed to chunks="auto" / omitting chunks.
• Expand and update tests and release notes to cover the new error semantics and generator acceptance.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/test_chunk_grids.py	Adds coverage for informative error messages and additional accepted/rejected chunk forms (incl. generators).
tests/test_api.py	Updates API-level expectation for chunk-size errors to match the new message.
src/zarr/core/chunk_grids.py	Refactors chunk normalization routines to accept object and improve type narrowing + error reporting.
src/zarr/core/array.py	Raises API-level ValueError for chunks=None/True with guidance toward auto-chunking.
docs/release-notes.md	Documents the more informative chunk-normalization behavior and generator support.

Comments suppressed due to low confidence (1)

src/zarr/core/chunk_grids.py:752

• if chunks == -1 runs before establishing that chunks is a scalar. If chunks is an array-like iterable (e.g., a NumPy array), chunks == -1 produces an array and the if triggers ValueError: truth value of an array is ambiguous instead of normalizing via the iterable path.

    if chunks == -1:
        return np.array([span], dtype=np.int64)
    if isinstance(chunks, int):
        if chunks <= 0:
            raise ValueError(f"Chunk size must be positive, got {chunks}")

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.