feat: add SupportsSetRange protocol and store implementations

Add SupportsSetRange protocol for stores that support writing to a byte
range within an existing value (set_range/set_range_sync). Implement
in MemoryStore and LocalStore, both explicitly subclassing the protocol.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: d-v-b

src/zarr/abc/store.py

@@ -22,6 +22,7 @@
     "Store",
     "SupportsDeleteSync",
     "SupportsGetSync",
+    "SupportsSetRange",
     "SupportsSetSync",
     "SupportsSyncStore",
     "set_or_delete",
@@ -709,6 +710,15 @@ async def delete(self) -> None: ...
     async def set_if_not_exists(self, default: Buffer) -> None: ...
 
 
+@runtime_checkable
+class SupportsSetRange(Protocol):
+    """Protocol for stores that support writing to a byte range within an existing value."""
+
+    async def set_range(self, key: str, value: Buffer, start: int) -> None: ...
+
+    def set_range_sync(self, key: str, value: Buffer, start: int) -> None: ...
+
+
 @runtime_checkable
 class SupportsGetSync(Protocol):
     def get_sync(

src/zarr/storage/_local.py

@@ -16,6 +16,7 @@
     RangeByteRequest,
     Store,
     SuffixByteRequest,
+    SupportsSetRange,
 )
 from zarr.core.buffer import Buffer
 from zarr.core.buffer.core import default_buffer_prototype
@@ -77,6 +78,13 @@ def _atomic_write(
         raise
 
 
+def _put_range(path: Path, value: Buffer, start: int) -> None:
+    """Write bytes at a specific offset within an existing file."""
+    with path.open("r+b") as f:
+        f.seek(start)
+        f.write(value.as_numpy_array().tobytes())
+
+
 def _put(path: Path, value: Buffer, exclusive: bool = False) -> int:
     path.parent.mkdir(parents=True, exist_ok=True)
     # write takes any object supporting the buffer protocol
@@ -85,7 +93,7 @@ def _put(path: Path, value: Buffer, exclusive: bool = False) -> int:
         return f.write(view)
 
 
-class LocalStore(Store):
+class LocalStore(Store, SupportsSetRange):
     """
     Store for the local file system.
 
@@ -292,6 +300,19 @@ async def _set(self, key: str, value: Buffer, exclusive: bool = False) -> None:
         path = self.root / key
         await asyncio.to_thread(_put, path, value, exclusive=exclusive)
 
+    async def set_range(self, key: str, value: Buffer, start: int) -> None:
+        if not self._is_open:
+            await self._open()
+        self._check_writable()
+        path = self.root / key
+        await asyncio.to_thread(_put_range, path, value, start)
+
+    def set_range_sync(self, key: str, value: Buffer, start: int) -> None:
+        self._ensure_open_sync()
+        self._check_writable()
+        path = self.root / key
+        _put_range(path, value, start)
+
     async def delete(self, key: str) -> None:
         """
         Remove a key from the store.

src/zarr/storage/_memory.py

@@ -3,7 +3,7 @@
 from logging import getLogger
 from typing import TYPE_CHECKING, Any, Self
 
-from zarr.abc.store import ByteRequest, Store
+from zarr.abc.store import ByteRequest, Store, SupportsSetRange
 from zarr.core.buffer import Buffer, gpu
 from zarr.core.buffer.core import default_buffer_prototype
 from zarr.core.common import concurrent_map
@@ -18,7 +18,7 @@
 logger = getLogger(__name__)
 
 
-class MemoryStore(Store):
+class MemoryStore(Store, SupportsSetRange):
     """
     Store for local memory.
 
@@ -186,6 +186,26 @@ async def delete(self, key: str) -> None:
         except KeyError:
             logger.debug("Key %s does not exist.", key)
 
+    def _set_range_impl(self, key: str, value: Buffer, start: int) -> None:
+        buf = self._store_dict[key]
+        target = buf.as_numpy_array()
+        if not target.flags.writeable:
+            target = target.copy()
+            self._store_dict[key] = buf.__class__(target)
+        source = value.as_numpy_array()
+        target[start : start + len(source)] = source
+
+    async def set_range(self, key: str, value: Buffer, start: int) -> None:
+        self._check_writable()
+        await self._ensure_open()
+        self._set_range_impl(key, value, start)
+
+    def set_range_sync(self, key: str, value: Buffer, start: int) -> None:
+        self._check_writable()
+        if not self._is_open:
+            self._is_open = True
+        self._set_range_impl(key, value, start)
+
     async def list(self) -> AsyncIterator[str]:
         # docstring inherited
         for key in self._store_dict: