Deprecate the experimental v3 implementation (#1802)

* deprecate(exp-v3): Add a future warning about the pending removal of the experimental v3 implementation

* ignore warning

* add test

Author: jhamman

pyproject.toml

@@ -137,6 +137,7 @@ filterwarnings = [
     "error:::zarr.*",
     "ignore:PY_SSIZE_T_CLEAN will be required.*:DeprecationWarning",
     "ignore:The loop argument is deprecated since Python 3.8.*:DeprecationWarning",
+    "ignore:The experimental Zarr V3 implementation in this version .*:FutureWarning",
 ]
 
 

zarr/_storage/store.py

@@ -1,5 +1,6 @@
 import abc
 import os
+import warnings
 from collections import defaultdict
 from collections.abc import MutableMapping
 from copy import copy
@@ -23,9 +24,21 @@
 DEFAULT_ZARR_VERSION: ZARR_VERSION = 2
 
 v3_api_available = os.environ.get("ZARR_V3_EXPERIMENTAL_API", "0").lower() not in ["0", "false"]
+_has_warned_about_v3 = False  # to avoid printing the warning multiple times
 
 
 def assert_zarr_v3_api_available():
+    # we issue a warning about the experimental v3 implementation when it is first used
+    global _has_warned_about_v3
+    if v3_api_available and not _has_warned_about_v3:
+        warnings.warn(
+            "The experimental Zarr V3 implementation in this version of Zarr-Python is not "
+            "in alignment with the final V3 specification. This version will be removed in "
+            "Zarr-Python 3 in favor of a spec compliant version.",
+            FutureWarning,
+            stacklevel=1,
+        )
+        _has_warned_about_v3 = True
     if not v3_api_available:
         raise NotImplementedError(
             "# V3 reading and writing is experimental! To enable support, set:\n"

zarr/tests/test_storage_v3.py

@@ -4,12 +4,18 @@
 import inspect
 import os
 import tempfile
+import warnings
 
 import numpy as np
 import pytest
 
 import zarr
-from zarr._storage.store import _get_hierarchy_metadata, v3_api_available, StorageTransformer
+from zarr._storage.store import (
+    _get_hierarchy_metadata,
+    assert_zarr_v3_api_available,
+    v3_api_available,
+    StorageTransformer,
+)
 from zarr._storage.v3_storage_transformers import ShardingStorageTransformer, v3_sharding_available
 from zarr.core import Array
 from zarr.meta import _default_entry_point_metadata_v3
@@ -668,6 +674,18 @@ def test_top_level_imports():
             assert not hasattr(zarr, store_name)  # pragma: no cover
 
 
+def test_assert_zarr_v3_api_available_warns_once():
+    import zarr._storage.store
+
+    zarr._storage.store._has_warned_about_v3 = False
+    warnings.resetwarnings()
+    with pytest.warns() as record:
+        assert_zarr_v3_api_available()
+        assert_zarr_v3_api_available()
+    assert len(record) == 1
+    assert "The experimental Zarr V3 implementation" in str(record[0].message)
+
+
 def _get_public_and_dunder_methods(some_class):
     return set(
         name