Feature/store list methods async generators

docs/release.rst

@@ -18,6 +18,12 @@ Release notes
 Unreleased (v3)
 ---------------
 
+Enhancements
+~~~~~~~~~~~~
+
+* Implement listing of the sub-arrays and sub-groups for a V3 ``Group``.
+  By :user:`Davis Bennett <d-v-b>` :issue:`1726`.
+
 Maintenance
 ~~~~~~~~~~~
 

src/zarr/v3/abc/store.py

@@ -1,4 +1,5 @@
 from abc import abstractmethod, ABC
+from collections.abc import AsyncGenerator
 
 from typing import List, Tuple, Optional
 
@@ -106,17 +107,17 @@ def supports_listing(self) -> bool:
         ...
 
     @abstractmethod
-    async def list(self) -> List[str]:
+    async def list(self) -> AsyncGenerator[str, None]:
         """Retrieve all keys in the store.
 
         Returns
         -------
-        list[str]
+        AsyncGenerator[str, None]
         """
         ...
 
     @abstractmethod
-    async def list_prefix(self, prefix: str) -> List[str]:
+    async def list_prefix(self, prefix: str) -> AsyncGenerator[str, None]:
         """Retrieve all keys in the store with a given prefix.
 
         Parameters
@@ -125,12 +126,12 @@ async def list_prefix(self, prefix: str) -> List[str]:
 
         Returns
         -------
-        list[str]
+        AsyncGenerator[str, None]
         """
         ...
 
     @abstractmethod
-    async def list_dir(self, prefix: str) -> List[str]:
+    async def list_dir(self, prefix: str) -> AsyncGenerator[str, None]:
         """
         Retrieve all keys and prefixes with a given prefix and which do not contain the character
         “/” after the given prefix.
@@ -141,6 +142,6 @@ async def list_dir(self, prefix: str) -> List[str]:
 
         Returns
         -------
-        list[str]
+        AsyncGenerator[str, None]
         """
         ...

src/zarr/v3/array.py

@@ -27,6 +27,7 @@
     ChunkCoords,
     Selection,
     SliceSelection,
+    ZarrFormat,
     concurrent_map,
 )
 from zarr.v3.config import RuntimeConfiguration
@@ -88,6 +89,7 @@ async def create(
         attributes: Optional[Dict[str, Any]] = None,
         runtime_configuration: RuntimeConfiguration = RuntimeConfiguration(),
         exists_ok: bool = False,
+        zarr_format: ZarrFormat = 3,
     ) -> AsyncArray:
         store_path = make_store_path(store)
         if not exists_ok:
@@ -100,31 +102,33 @@ async def create(
                 fill_value = False
             else:
                 fill_value = 0
+        if zarr_format == 3:
+            metadata = ArrayMetadata(
+                shape=shape,
+                data_type=dtype,
+                chunk_grid=RegularChunkGrid(chunk_shape=chunk_shape),
+                chunk_key_encoding=(
+                    V2ChunkKeyEncoding(separator=chunk_key_encoding[1])
+                    if chunk_key_encoding[0] == "v2"
+                    else DefaultChunkKeyEncoding(separator=chunk_key_encoding[1])
+                ),
+                fill_value=fill_value,
+                codecs=codecs,
+                dimension_names=tuple(dimension_names) if dimension_names else None,
+                attributes=attributes or {},
+            )
+            runtime_configuration = runtime_configuration or RuntimeConfiguration()
 
-        metadata = ArrayMetadata(
-            shape=shape,
-            data_type=dtype,
-            chunk_grid=RegularChunkGrid(chunk_shape=chunk_shape),
-            chunk_key_encoding=(
-                V2ChunkKeyEncoding(separator=chunk_key_encoding[1])
-                if chunk_key_encoding[0] == "v2"
-                else DefaultChunkKeyEncoding(separator=chunk_key_encoding[1])
-            ),
-            fill_value=fill_value,
-            codecs=codecs,
-            dimension_names=tuple(dimension_names) if dimension_names else None,
-            attributes=attributes or {},
-        )
-        runtime_configuration = runtime_configuration or RuntimeConfiguration()
-
-        array = cls(
-            metadata=metadata,
-            store_path=store_path,
-            runtime_configuration=runtime_configuration,
-        )
+            array = cls(
+                metadata=metadata,
+                store_path=store_path,
+                runtime_configuration=runtime_configuration,
+            )
 
-        await array._save_metadata()
-        return array
+            await array._save_metadata()
+            return array
+        else:
+            raise NotImplementedError("Zarr version 2 arrays cannot be created yet.")
 
     @classmethod
     def from_dict(

src/zarr/v3/common.py

@@ -1,5 +1,5 @@
 from __future__ import annotations
-from typing import TYPE_CHECKING, Union, Tuple, Iterable, Dict, List, TypeVar, overload
+from typing import TYPE_CHECKING, Literal, Union, Tuple, Iterable, Dict, List, TypeVar, overload
 import asyncio
 import contextvars
 from dataclasses import dataclass
@@ -21,6 +21,7 @@
 ChunkCoordsLike = Iterable[int]
 SliceSelection = Tuple[slice, ...]
 Selection = Union[slice, SliceSelection]
+ZarrFormat = Literal[2, 3]
 JSON = Union[str, None, int, float, Enum, Dict[str, "JSON"], List["JSON"], Tuple["JSON", ...]]