dep(docs): deprecate experimental v3 support in docs (#1807)

* dep(docs): deprecate experimental v3 support in docs

* Apply suggestions from code review

Co-authored-by: Josh Moore <[email protected]>
Co-authored-by: Sanket Verma <[email protected]>

---------

Co-authored-by: Josh Moore <[email protected]>
Co-authored-by: Sanket Verma <[email protected]>

Author: 3 people

docs/api/v3.rst

@@ -1,13 +1,12 @@
 V3 Specification Implementation(``zarr._storage.v3``)
 =====================================================
 
-This module contains the implementation of the `Zarr V3 Specification <https://zarr-specs.readthedocs.io/en/latest/v3/core/v3.0.html>`_.
+This module contains an experimental implementation of the `Zarr V3 Specification <https://zarr-specs.readthedocs.io/en/latest/v3/core/v3.0.html>`_.
 
 .. warning::
-    Since Zarr Python 2.12 release, this module provides experimental infrastructure for reading and
-    writing the upcoming V3 spec of the Zarr format. Users wishing to prepare for the migration can set
-    the environment variable ``ZARR_V3_EXPERIMENTAL_API=1`` to begin experimenting, however data
-    written with this API should be expected to become stale, as the implementation will still change.
+    The experimental v3 implementation included in Zarr Python >2.12,<3 is not aligned with the final
+    V3 specification. This version is deprecated and will be removed in Zarr Python 3.0 in favor of a
+    spec compliant version.
 
 The new ``zarr._store.v3`` package has the necessary classes and functions for evaluating Zarr V3.
 Since the design is not finalised, the classes and functions are not automatically imported into

docs/release.rst

@@ -36,6 +36,12 @@ Docs
 Maintenance
 ~~~~~~~~~~~
 
+Deprecations
+~~~~~~~~~~~~
+
+* Deprecate experimental v3 support by issuing a `FutureWarning`.
+  Also updated docs to warn about using the experimental v3 version.
+  By :user:`Joe Hamman <jhamman>` :issue:`1802` and :issue: `1807`.
 
 .. _release_2.17.2:
 

zarr/convenience.py

@@ -55,6 +55,11 @@ def open(store: StoreLike = None, mode: str = "a", *, zarr_version=None, path=No
         The zarr protocol version to use. The default value of None will attempt
         to infer the version from `store` if possible, otherwise it will fall
         back to 2.
+
+        .. warning:: `zarr_version=3` is currently using the experimental Zarr V3
+          implementation. This implementation is not in sync with the final specification
+          and will be replaced with a spec compliant version in the version 3.0.
+
     path : str or None, optional
         The path within the store to open.
     **kwargs
@@ -150,6 +155,11 @@ def save_array(store: StoreLike, arr, *, zarr_version=None, path=None, **kwargs)
         The zarr protocol version to use when saving. The default value of None
         will attempt to infer the version from `store` if possible, otherwise
         it will fall back to 2.
+
+        .. warning:: `zarr_version=3` is currently using the experimental Zarr V3
+          implementation. This implementation is not in sync with the final specification
+          and will be replaced with a spec compliant version in the version 3.0.
+
     path : str or None, optional
         The path within the store where the array will be saved.
     kwargs
@@ -200,6 +210,11 @@ def save_group(store: StoreLike, *args, zarr_version=None, path=None, **kwargs):
         The zarr protocol version to use when saving. The default value of None
         will attempt to infer the version from `store` if possible, otherwise
         it will fall back to 2.
+
+        .. warning:: `zarr_version=3` is currently using the experimental Zarr V3
+          implementation. This implementation is not in sync with the final specification
+          and will be replaced with a spec compliant version in the version 3.0.
+
     path : str or None, optional
         Path within the store where the group will be saved.
     kwargs
@@ -282,6 +297,11 @@ def save(store: StoreLike, *args, zarr_version=None, path=None, **kwargs):
         The zarr protocol version to use when saving. The default value of None
         will attempt to infer the version from `store` if possible, otherwise
         it will fall back to 2.
+
+        .. warning:: `zarr_version=3` is currently using the experimental Zarr V3
+          implementation. This implementation is not in sync with the final specification
+          and will be replaced with a spec compliant version in the version 3.0.
+
     path : str or None, optional
         The path within the group where the arrays will be saved.
     kwargs
@@ -395,6 +415,11 @@ def load(store: StoreLike, zarr_version=None, path=None):
         The zarr protocol version to use when loading. The default value of
         None will attempt to infer the version from `store` if possible,
         otherwise it will fall back to 2.
+
+        .. warning:: `zarr_version=3` is currently using the experimental Zarr V3
+          implementation. This implementation is not in sync with the final specification
+          and will be replaced with a spec compliant version in the version 3.0.
+
     path : str or None, optional
         The path within the store from which to load.