From 1163066ab8639af998b52d01866782633875b412 Mon Sep 17 00:00:00 2001 From: Joseph Hamman Date: Mon, 22 Apr 2024 13:59:37 -0700 Subject: [PATCH 1/2] dep(docs): deprecate experimental v3 support in docs --- docs/api/v3.rst | 9 ++++----- docs/release.rst | 6 ++++++ zarr/convenience.py | 25 +++++++++++++++++++++++++ 3 files changed, 35 insertions(+), 5 deletions(-) diff --git a/docs/api/v3.rst b/docs/api/v3.rst index 7665b2ddd1..1f7c035289 100644 --- a/docs/api/v3.rst +++ b/docs/api/v3.rst @@ -1,13 +1,12 @@ V3 Specification Implementation(``zarr._storage.v3``) ===================================================== -This module contains the implementation of the `Zarr V3 Specification `_. +This module contains an experimental implementation of the `Zarr V3 Specification `_. .. 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 alignment 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 diff --git a/docs/release.rst b/docs/release.rst index 07c2a47e7c..c83db58fda 100644 --- a/docs/release.rst +++ b/docs/release.rst @@ -31,6 +31,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 ` :issue:`1802` and :issue `1807`. .. _release_2.17.2: diff --git a/zarr/convenience.py b/zarr/convenience.py index 7ca5d426f0..bd284e0844 100644 --- a/zarr/convenience.py +++ b/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. From ae499d8912fc5a508d5ebae774b54d5c5baa4f79 Mon Sep 17 00:00:00 2001 From: Joe Hamman Date: Tue, 30 Apr 2024 08:05:32 -0700 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Josh Moore Co-authored-by: Sanket Verma --- docs/api/v3.rst | 2 +- docs/release.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/v3.rst b/docs/api/v3.rst index 1f7c035289..3503e3fe81 100644 --- a/docs/api/v3.rst +++ b/docs/api/v3.rst @@ -4,7 +4,7 @@ V3 Specification Implementation(``zarr._storage.v3``) This module contains an experimental implementation of the `Zarr V3 Specification `_. .. warning:: - The experimental v3 implementation included in Zarr Python >2.12,<3 is not alignment with the final + 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. diff --git a/docs/release.rst b/docs/release.rst index c83db58fda..9542da857c 100644 --- a/docs/release.rst +++ b/docs/release.rst @@ -36,7 +36,7 @@ Deprecations * Deprecate experimental v3 support by issuing a `FutureWarning`. Also updated docs to warn about using the experimental v3 version. - By :user:`Joe Hamman ` :issue:`1802` and :issue `1807`. + By :user:`Joe Hamman ` :issue:`1802` and :issue: `1807`. .. _release_2.17.2: