Mark V3 API experimental

Following discussion at this week's community call, a few additional
precautions are being implemented here:

- [x] rename the var ZARR_V3_API_AVAILABLE to ZARR_V3_EXPERIMENTAL_API
- [x] add an assertion to prevent use of zarr_version=3 w/o the var

Author: joshmoore

.github/workflows/python-package.yml

@@ -71,7 +71,7 @@ jobs:
         ZARR_TEST_ABS: 1
         ZARR_TEST_MONGO: 1
         ZARR_TEST_REDIS: 1
-        ZARR_V3_API_AVAILABLE: 1
+        ZARR_V3_EXPERIMENTAL_API: 1
       run: |
         conda activate zarr-env
         mkdir ~/blob_emulator

docs/release.rst

@@ -23,7 +23,7 @@ Enhancements
   package has the necessary classes and functions for evaluating Zarr V3.
   Since the format is not yet finalized, the classes and functions are not
   automatically imported into the regular `zarr` name space. Setting the
-  `ZARR_V3_API_AVAILABLE` environment variable will activate them.
+  `ZARR_V3_EXPERIMENTAL_API` environment variable will activate them.
   By :user:`Greggory Lee <grlee77>`; :issue:`898`, :issue:`1006`, and :issue:`1007`.
 
 * **Create FSStore from an existing fsspec filesystem**. If you have created

zarr/_storage/store.py

@@ -18,7 +18,15 @@
 
 DEFAULT_ZARR_VERSION = 2
 
-v3_api_available = os.environ.get('ZARR_V3_API_AVAILABLE', '0').lower() not in ['0', 'false']
+v3_api_available = os.environ.get('ZARR_V3_EXPERIMENTAL_API', '0').lower() not in ['0', 'false']
+
+
+def assert_zarr_v3_api_available():
+    if not v3_api_available:
+        raise NotImplementedError(
+            "# V3 reading and writing is experimental! To enable support, set:\n"
+            "ZARR_V3_EXPERIMENTAL_API=1"
+        )
 
 
 class BaseStore(MutableMapping):

zarr/convenience.py

@@ -5,7 +5,7 @@
 import re
 from collections.abc import Mapping, MutableMapping
 
-from zarr._storage.store import data_root, meta_root
+from zarr._storage.store import data_root, meta_root, assert_zarr_v3_api_available
 from zarr.core import Array
 from zarr.creation import array as _create_array
 from zarr.creation import open_array
@@ -1209,6 +1209,8 @@ def is_zarr_key(key):
 
     else:
 
+        assert_zarr_v3_api_available()
+
         sfx = _get_metadata_suffix(store)  # type: ignore
 
         def is_zarr_key(key):
@@ -1288,6 +1290,7 @@ def open_consolidated(store: StoreLike, metadata_key=".zmetadata", mode="r+", **
     if store._store_version == 2:
         ConsolidatedStoreClass = ConsolidatedMetadataStore
     else:
+        assert_zarr_v3_api_available()
         ConsolidatedStoreClass = ConsolidatedMetadataStoreV3
         # default is to store within 'consolidated' group on v3
         if not metadata_key.startswith('meta/root/'):

zarr/core.py

@@ -11,7 +11,7 @@
 import numpy as np
 from numcodecs.compat import ensure_bytes, ensure_ndarray
 
-from zarr._storage.store import _prefix_to_attrs_key
+from zarr._storage.store import _prefix_to_attrs_key, assert_zarr_v3_api_available
 from zarr.attrs import Attributes
 from zarr.codecs import AsType, get_codec
 from zarr.errors import ArrayNotFoundError, ReadOnlyError, ArrayIndexError
@@ -171,6 +171,9 @@ def __init__(
         if zarr_version is None:
             zarr_version = store._store_version
 
+        if zarr_version != 2:
+            assert_zarr_v3_api_available()
+
         if chunk_store is not None:
             chunk_store = normalize_store_arg(chunk_store,
                                               zarr_version=zarr_version)

zarr/hierarchy.py

@@ -3,7 +3,8 @@
 
 import numpy as np
 
-from zarr._storage.store import _get_metadata_suffix, data_root, meta_root, DEFAULT_ZARR_VERSION
+from zarr._storage.store import (_get_metadata_suffix, data_root, meta_root,
+                                 DEFAULT_ZARR_VERSION, assert_zarr_v3_api_available)
 from zarr.attrs import Attributes
 from zarr.core import Array
 from zarr.creation import (array, create, empty, empty_like, full, full_like,
@@ -117,6 +118,10 @@ def __init__(self, store, path=None, read_only=False, chunk_store=None,
         store: BaseStore = _normalize_store_arg(store, zarr_version=zarr_version)
         if zarr_version is None:
             zarr_version = getattr(store, '_store_version', DEFAULT_ZARR_VERSION)
+
+        if zarr_version != 2:
+            assert_zarr_v3_api_available()
+
         if chunk_store is not None:
             chunk_store: BaseStore = _normalize_store_arg(chunk_store, zarr_version=zarr_version)
         self._store = store
@@ -1178,6 +1183,10 @@ def _normalize_store_arg(store, *, storage_options=None, mode="r",
                          zarr_version=None):
     if zarr_version is None:
         zarr_version = getattr(store, '_store_version', DEFAULT_ZARR_VERSION)
+
+    if zarr_version != 2:
+        assert_zarr_v3_api_available()
+
     if store is None:
         return MemoryStore() if zarr_version == 2 else MemoryStoreV3()
     return normalize_store_arg(store,
@@ -1234,6 +1243,10 @@ def group(store=None, overwrite=False, chunk_store=None,
     store = _normalize_store_arg(store, zarr_version=zarr_version)
     if zarr_version is None:
         zarr_version = getattr(store, '_store_version', DEFAULT_ZARR_VERSION)
+
+    if zarr_version != 2:
+        assert_zarr_v3_api_available()
+
     if zarr_version == 3 and path is None:
         raise ValueError(f"path must be provided for a v{zarr_version} group")
     path = normalize_storage_path(path)
@@ -1305,6 +1318,10 @@ def open_group(store=None, mode='a', cache_attrs=True, synchronizer=None, path=N
         zarr_version=zarr_version)
     if zarr_version is None:
         zarr_version = getattr(store, '_store_version', DEFAULT_ZARR_VERSION)
+
+    if zarr_version != 2:
+        assert_zarr_v3_api_available()
+
     if chunk_store is not None:
         chunk_store = _normalize_store_arg(chunk_store,
                                            storage_options=storage_options,