add warnings when write_empty_chunks is used as a kwarg

Author: d-v-b

src/zarr/api/asynchronous.py

@@ -16,6 +16,7 @@
     ChunkCoords,
     MemoryOrder,
     ZarrFormat,
+    _warn_write_empty_chunks_kwarg,
 )
 from zarr.core.config import config
 from zarr.core.group import AsyncGroup, ConsolidatedMetadata, GroupMetadata
@@ -724,7 +725,6 @@ async def create(
     read_only: bool | None = None,
     object_codec: Codec | None = None,  # TODO: type has changed
     dimension_separator: Literal[".", "/"] | None = None,
-    write_empty_chunks: bool = False,  # TODO: default has changed
     zarr_version: ZarrFormat | None = None,  # deprecated
     zarr_format: ZarrFormat | None = None,
     meta_array: Any | None = None,  # TODO: need type
@@ -794,17 +794,6 @@ async def create(
 
         .. versionadded:: 2.8
 
-    write_empty_chunks : bool, optional
-        If True (default), all chunks will be stored regardless of their
-        contents. If False, each chunk is compared to the array's fill value
-        prior to storing. If a chunk is uniformly equal to the fill value, then
-        that chunk is not be stored, and the store entry for that chunk's key
-        is deleted. This setting enables sparser storage, as only chunks with
-        non-fill-value data are stored, at the expense of overhead associated
-        with checking the data of each chunk.
-
-        .. versionadded:: 2.11
-
     zarr_format : {2, 3, None}, optional
         The zarr format to use when saving.
     meta_array : array-like, optional
@@ -856,8 +845,12 @@ async def create(
                 RuntimeWarning,
                 stacklevel=2,
             )
-    if write_empty_chunks:
-        warnings.warn("write_empty_chunks is not yet implemented", RuntimeWarning, stacklevel=2)
+
+    if "write_empty_chunks" in kwargs:
+        # warn users if the write_empty_chunks kwarg was used
+        write_empty_chunks = kwargs.pop("write_empty_chunks")
+        _warn_write_empty_chunks_kwarg(write_empty_chunks)
+
     if meta_array is not None:
         warnings.warn("meta_array is not yet implemented", RuntimeWarning, stacklevel=2)
 
@@ -1058,6 +1051,11 @@ async def open_array(
 
     zarr_format = _handle_zarr_version_or_format(zarr_version=zarr_version, zarr_format=zarr_format)
 
+    if "write_empty_chunks" in kwargs:
+        # warn users if the write_empty_chunks kwarg was used
+        write_empty_chunks = kwargs.pop("write_empty_chunks")
+        _warn_write_empty_chunks_kwarg(write_empty_chunks)
+
     try:
         return await AsyncArray.open(store_path, zarr_format=zarr_format)
     except FileNotFoundError:

src/zarr/core/common.py

@@ -3,6 +3,7 @@
 import asyncio
 import functools
 import operator
+import warnings
 from collections.abc import Iterable, Mapping
 from enum import Enum
 from itertools import starmap
@@ -166,3 +167,12 @@ def parse_dtype(dtype: Any, zarr_format: ZarrFormat) -> np.dtype[Any]:
         else:
             return _STRING_DTYPE
     return np.dtype(dtype)
+
+
+def _warn_write_empty_chunks_kwarg(write_empty_chunks: bool) -> None:
+    msg = (
+        f"The `write_empty_chunks` keyword argument was provided to this function with a value of {write_empty_chunks}."
+        "This keyword argument has no effect. To control whether empty chunks are written to"
+        " storage, change the 'array.write_empty_chunks' configuration variable."
+    )
+    warnings.warn(msg, RuntimeWarning, stacklevel=2)

tests/test_api.py

@@ -48,6 +48,21 @@ def test_create_array(memory_store: Store) -> None:
     assert z.chunks == (40,)
 
 
+@pytest.mark.parametrize("write_empty_chunks", [True, False])
+def test_write_empty_chunks_warns(write_empty_chunks: bool) -> None:
+    """
+    Test that using the `write_empty_chunks` kwarg on array access will raise a warning.
+    """
+    match = f"The `write_empty_chunks` keyword argument was provided to this function with a value of {write_empty_chunks}."
+    with pytest.warns(RuntimeWarning, match=match):
+        _ = zarr.array(
+            data=np.arange(10), shape=(10,), dtype="uint8", write_empty_chunks=write_empty_chunks
+        )
+
+    with pytest.warns(RuntimeWarning, match=match):
+        _ = zarr.create(shape=(10,), dtype="uint8", write_empty_chunks=write_empty_chunks)
+
+
 @pytest.mark.parametrize("path", ["foo", "/", "/foo", "///foo/bar"])
 @pytest.mark.parametrize("node_type", ["array", "group"])
 def test_open_normalized_path(