feat(api): declare mode and data on create

[d-v-b]

This PR makes zarr.create and zarr.api.asynchronous.create have accurate signatures and docstrings. part of **kwargs removal.

🤖 AI text below 🤖

zarr.create and zarr.api.asynchronous.create now list mode and data in their signatures and docstrings. Both were accepted before without being declared. An unknown keyword now raises a TypeError from create before anything in the store is touched. Previously, with mode="w", the existing data was deleted before the error was raised. mode is documented as a legacy spelling; overwrite is preferred.

This is the first step of replacing **kwargs in the array-creation helpers (empty, zeros, ones, full, the *_like functions and open_array) with explicit parameters. Before this change, create passed **kwargs on to AsyncArray._create, and the only extra names that function accepted were mode (which create popped out of kwargs) and data. The docs still rely on mode (zarr.zeros(..., mode='w') in docs/user-guide/experimental.md), so it stays, documented as legacy. data is documented with a pointer to create_array(data=...), whose data sets the shape and data type, unlike create's.

• The docstring states each mode's outcome, including how it combines with overwrite: 'w' replaces even with overwrite=False, and 'w-' fails even with overwrite=True.
• Tests: one test covers the successful combinations of mode, overwrite, an existing array and data, for both the sync and async create. It compares the stored keys with a fresh store, so it fails if old chunks or unrelated keys survive a replacement. There is one test per error case: an existing array without overwrite (default mode, 'a', 'r+'), 'w-' over existing data, 'r', an invalid mode, and an unknown keyword (sync and async, store left untouched).
• Behavior is unchanged, except for where the TypeError for an unknown keyword comes from and that it is raised before mode="w" deletes anything.
• Type checkers now reject a mode annotated as plain str, as open and open_array already do.

Notes

• mode has no effect when store is a StorePath, because make_store_path returns it unchanged. The group helpers (Group.zeros etc.) pass a StorePath, so mode does nothing there. The docstring says so. Changing that is out of scope.
• fix(api): validate a new node before deleting the existing one #4410 (open) changes the meaning of mode in create, not only its text: it derives overwrite from mode, so 'w' would take effect for a StorePath too. Whichever PR merges second must update the docstring sentence about StorePath. The per-mode outcomes are written to hold on both sides.
• Found along the way, not changed here: zarr.create(..., data=<zarr Array>) raises SyncError (the docstring now says a Zarr array is not supported), and assigning a longer 1-D value into an array silently truncates (being investigated separately).
• Planned follow-ups: explicit signatures for empty/zeros/ones/full and the group helpers (after fix(group): create group helper arrays in the group's zarr format #4412), for the *_like functions, and for open_array/open_like (after fix(api): apply config when open_array opens an existing array #4408 and fix(api): validate a new node before deleting the existing one #4410).

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.46%. Comparing base (9677081) to head (4dc06f0).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4455   +/-   ##
=======================================
  Coverage   94.46%   94.46%           
=======================================
  Files          93       93           
  Lines       13234    13233    -1     
=======================================
  Hits        12501    12501           
+ Misses        733      732    -1     

Files with missing lines	Coverage Δ
src/zarr/api/asynchronous.py	96.30% <ø> (-0.02%)	⬇️
src/zarr/api/synchronous.py	92.95% <ø> (ø)

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

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