feat(array): add ArrayIO and AsyncArrayIO, the explicit-IO layer under Array and AsyncArray

changes/419.feature.md

@@ -0,0 +1,3 @@
+Added `zarr.ArrayIO` and `zarr.AsyncArrayIO`, an explicit-IO layer over Zarr arrays. Constructing one performs no IO against storage: storing metadata (`store_metadata`), storing or reading chunks (`setitem` / `getitem`), and their erasing inverses (`erase_metadata`, `erase_chunk`, `erase_chunks`) are explicit method calls that run in whatever order the caller chooses, so chunks can be written before metadata. `open` auto-detects the Zarr format by default, as `zarrs` does, and `verify` reads the stored metadata and raises, naming each differing field, when it does not match the metadata the instance is bound to.
+`Array` and `AsyncArray` are built on this layer: every `AsyncArray` wraps an `AsyncArrayIO` and delegates its metadata and selection IO to it, the wrapped layer is reachable as `Array.io` / `AsyncArray.io`, and `to_array()` returns an array over the same binding.
+The binding holds the metadata document as a `zarr-metadata` model — `zarr-python` now depends on `zarr-metadata` — reachable as `ArrayIO.document`: document operations (`store_metadata`, `erase_metadata`, `erase_chunk`, `erase_chunks`, `verify`) never resolve codec or data type names, so an array whose codecs this environment lacks can still be opened, verified and erased, and names resolve into classes only when chunks are read or written.

docs/api/zarr/array.md

@@ -1,2 +1,4 @@
 ::: zarr.Array
 ::: zarr.AsyncArray
+::: zarr.ArrayIO
+::: zarr.AsyncArrayIO

pyproject.toml

@@ -53,6 +53,7 @@ dependencies = [
     'typing_extensions>=4.14',
     'donfig>=0.8',
     'msgspec>=0.19',
+    'zarr-metadata>=0.6.0',
 ]
 
 dynamic = [

src/zarr/__init__.py

@@ -34,7 +34,7 @@
     zeros,
     zeros_like,
 )
-from zarr.core.array import Array, AsyncArray
+from zarr.core.array import Array, ArrayIO, AsyncArray, AsyncArrayIO
 from zarr.core.config import config
 from zarr.core.group import AsyncGroup, Group
 
@@ -147,7 +147,9 @@ def set_format(log_format: str) -> None:
 
 __all__ = [
     "Array",
+    "ArrayIO",
     "AsyncArray",
+    "AsyncArrayIO",
     "AsyncGroup",
     "Group",
     "__version__",