From 97dc1873f4007263db590b63c57ea01ad95a7808 Mon Sep 17 00:00:00 2001
From: Joseph Hamman <joe@earthmover.io>
Date: Fri, 19 Apr 2024 10:20:48 -0700
Subject: [PATCH 1/4] deprecate(exp-v3): Add a future warning about the pending
 removal of the experimental v3 implementation

---
 zarr/_storage/store.py | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/zarr/_storage/store.py b/zarr/_storage/store.py
index 8daedae48f..56f48ca114 100644
--- a/zarr/_storage/store.py
+++ b/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
@@ -22,9 +23,21 @@
 DEFAULT_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"

From 775dccd6aa2bc3489aa5cde61a72d808dfa5c4d2 Mon Sep 17 00:00:00 2001
From: Joseph Hamman <joe@earthmover.io>
Date: Fri, 19 Apr 2024 10:24:43 -0700
Subject: [PATCH 2/4] ignore warning

---
 pyproject.toml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/pyproject.toml b/pyproject.toml
index 22ea19f28f..1073f545dd 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -136,4 +136,5 @@ 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",
 ]

From af563846879625c28018c8579a8e932dda73171c Mon Sep 17 00:00:00 2001
From: Joseph Hamman <joe@earthmover.io>
Date: Fri, 19 Apr 2024 14:14:26 -0700
Subject: [PATCH 3/4] add test

---
 zarr/tests/test_storage_v3.py | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/zarr/tests/test_storage_v3.py b/zarr/tests/test_storage_v3.py
index ded9296059..8747a0ca57 100644
--- a/zarr/tests/test_storage_v3.py
+++ b/zarr/tests/test_storage_v3.py
@@ -9,7 +9,12 @@
 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
@@ -678,6 +683,14 @@ def test_top_level_imports():
             assert not hasattr(zarr, store_name)  # pragma: no cover
 
 
+def test_assert_zarr_v3_api_available_warns_once():
+    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

From 834a3e107691d0444c6c000948283f16c1481dda Mon Sep 17 00:00:00 2001
From: Joseph Hamman <joe@earthmover.io>
Date: Mon, 22 Apr 2024 06:47:58 -0700
Subject: [PATCH 4/4] reset warnings before test

---
 zarr/tests/test_storage_v3.py | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/zarr/tests/test_storage_v3.py b/zarr/tests/test_storage_v3.py
index 429c50f53e..c096f9cb02 100644
--- a/zarr/tests/test_storage_v3.py
+++ b/zarr/tests/test_storage_v3.py
@@ -4,6 +4,7 @@
 import inspect
 import os
 import tempfile
+import warnings
 
 import numpy as np
 import pytest
@@ -674,6 +675,10 @@ def test_top_level_imports():
 
 
 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()