feat(api): declare mode and data on create

`create` accepted `mode` and `data` only through `**kwargs`: `mode` was
popped for opening the store and `data` reached `AsyncArray._create`.
Both are now named, documented parameters of the sync and async
`create`, and `**kwargs` is gone, so an unknown keyword raises a
TypeError from `create` itself.

Assisted-by: ClaudeCode:claude-opus-5-5

Author: d-v-b

changes/create-mode-data.feature.md

@@ -0,0 +1 @@
+`zarr.create` and `zarr.api.asynchronous.create` now declare and document their `mode` and `data` parameters. Both parameters were accepted before but were not part of the signature. `create` no longer takes arbitrary keyword arguments, so an unknown keyword raises a `TypeError` naming `create` instead of the private `AsyncArray._create`.

src/zarr/api/asynchronous.py

@@ -922,7 +922,8 @@ async def create(
     dimension_names: DimensionNamesLike = None,
     storage_options: dict[str, Any] | None = None,
     config: ArrayConfigLike | None = None,
-    **kwargs: Any,
+    mode: AccessModeLiteral | None = None,
+    data: npt.ArrayLike | None = None,
 ) -> AnyAsyncArray:
     """Create an array.
 
@@ -1042,6 +1043,15 @@ async def create(
     config : ArrayConfigLike, optional
         Runtime configuration of the array. If provided, will override the
         default values from `zarr.config.array`.
+    mode : {'r', 'r+', 'a', 'w', 'w-'}, optional
+        The access mode used to open `store`. The default, `None`, is `'a'`.
+        With `'w'`, everything stored under `path` is deleted before the array is
+        created. With `'w-'`, creation fails if anything is stored under `path`.
+        With `'r'`, the store is opened read-only and creation fails.
+        Ignored if `store` is a `StorePath`, which is already open.
+    data : array-like, optional
+        Values written into the new array after it is created, as `array[...] = data`.
+        `data` does not determine the shape or data type of the array.
 
     Returns
     -------
@@ -1066,7 +1076,6 @@ async def create(
     if write_empty_chunks is not None:
         _warn_write_empty_chunks_kwarg()
 
-    mode = kwargs.pop("mode", None)
     if mode is None:
         mode = "a"
     store_path = await make_store_path(store, path=path, mode=mode, storage_options=storage_options)
@@ -1102,7 +1111,7 @@ async def create(
         dimension_names=dimension_names,
         attributes=attributes,
         config=config_parsed,
-        **kwargs,
+        data=data,
     )
 
 

src/zarr/api/synchronous.py

@@ -630,7 +630,6 @@ def create_group(
     )
 
 
-# TODO: add type annotations for kwargs
 def create(
     shape: tuple[int, ...] | int,
     *,  # Note: this is a change from v2
@@ -666,7 +665,8 @@ def create(
     dimension_names: DimensionNamesLike = None,
     storage_options: dict[str, Any] | None = None,
     config: ArrayConfigLike | None = None,
-    **kwargs: Any,
+    mode: AccessModeLiteral | None = None,
+    data: npt.ArrayLike | None = None,
 ) -> AnyArray:
     """Create an array.
 
@@ -786,6 +786,15 @@ def create(
     config : ArrayConfigLike, optional
         Runtime configuration of the array. If provided, will override the
         default values from `zarr.config.array`.
+    mode : {'r', 'r+', 'a', 'w', 'w-'}, optional
+        The access mode used to open `store`. The default, `None`, is `'a'`.
+        With `'w'`, everything stored under `path` is deleted before the array is
+        created. With `'w-'`, creation fails if anything is stored under `path`.
+        With `'r'`, the store is opened read-only and creation fails.
+        Ignored if `store` is a `StorePath`, which is already open.
+    data : array-like, optional
+        Values written into the new array after it is created, as `array[...] = data`.
+        `data` does not determine the shape or data type of the array.
 
     Returns
     -------
@@ -822,7 +831,8 @@ def create(
                 dimension_names=dimension_names,
                 storage_options=storage_options,
                 config=config,
-                **kwargs,
+                mode=mode,
+                data=data,
             )
         )
     )

tests/test_api.py

@@ -15,7 +15,7 @@
     from pathlib import Path
 
     from zarr.abc.store import Store
-    from zarr.core.common import JSON, MemoryOrder, ZarrFormat
+    from zarr.core.common import JSON, AccessModeLiteral, MemoryOrder, ZarrFormat
     from zarr.types import AnyArray
 
 import contextlib
@@ -46,6 +46,7 @@
 from zarr.core.buffer import NDArrayLike
 from zarr.errors import (
     ArrayNotFoundError,
+    ContainsArrayError,
     MetadataValidationError,
     ZarrDeprecationWarning,
     ZarrUserWarning,
@@ -84,6 +85,61 @@ def test_create(memory_store: Store) -> None:
         z = create(shape=(400, 100), chunks=(16, 16.5), store=store, overwrite=True)  # type: ignore[arg-type]
 
 
+@pytest.mark.parametrize(
+    ("mode", "existing"),
+    [(None, False), ("a", False), ("r+", False), ("w", False), ("w", True), ("w-", False)],
+)
+@pytest.mark.parametrize("data", [None, np.arange(3, dtype="float64")])
+def test_create_mode_data(mode: AccessModeLiteral | None, existing: bool, data: Any) -> None:
+    """
+    `create` opens the store with `mode` and writes `data` into the new array.
+    """
+    store = MemoryStore()
+    if existing:
+        create_array(store, shape=(2,), dtype="int8")
+    z = create(shape=(3,), store=store, mode=mode, data=data)
+    assert z.shape == (3,)
+    assert z.dtype == np.dtype("float64")
+    expected = np.zeros(3) if data is None else data
+    assert_array_equal(z[:], expected)
+
+
+def test_create_mode_a_existing_array() -> None:
+    """
+    `create` with mode `'a'` refuses to replace an existing array.
+    """
+    store = MemoryStore()
+    create_array(store, shape=(2,), dtype="int8")
+    with pytest.raises(ContainsArrayError):
+        create(shape=(3,), store=store, mode="a")
+
+
+def test_create_mode_w_minus_existing_data() -> None:
+    """
+    `create` with mode `'w-'` refuses to write where data is stored.
+    """
+    store = MemoryStore()
+    create_array(store, shape=(2,), dtype="int8")
+    with pytest.raises(FileExistsError, match="mode 'w-'"):
+        create(shape=(3,), store=store, mode="w-")
+
+
+def test_create_mode_r() -> None:
+    """
+    `create` with mode `'r'` opens the store read-only, so creation fails.
+    """
+    with pytest.raises(ValueError, match="read-only"):
+        create(shape=(3,), store=MemoryStore(), mode="r")
+
+
+def test_create_unknown_keyword() -> None:
+    """
+    `create` rejects keyword arguments it does not declare, naming itself in the error.
+    """
+    with pytest.raises(TypeError, match=r"^create\(\) got an unexpected keyword argument 'typo'"):
+        create(shape=(3,), typo=1)  # type: ignore[call-arg]
+
+
 @pytest.mark.parametrize(
     "func",
     [