deprecate(stores): add deprecation warnings to stores that we plan to…

… remove in v3 (#1801)

* deprecate(stores): add deprecation warnings to DBMStore, LMDBStore, SQLiteStore, MongoDBStore, RedisStore, and ABSStore

* filter warnings in pytest config

* more deprecation warnings in docstrings

* add release note

docs/release.rst

@@ -43,6 +43,13 @@ Deprecations
   Also updated docs to warn about using the experimental v3 version.
   By :user:`Joe Hamman <jhamman>` :issue:`1802` and :issue: `1807`.
 
+Deprecations
+~~~~~~~~~~~~
+* Deprecate the following stores: :class:`zarr.storage.DBMStore`, :class:`zarr.storage.LMDBStore`,
+  :class:`zarr.storage.SQLiteStore`, :class:`zarr.storage.MongoDBStore`, :class:`zarr.storage.RedisStore`,
+  and :class:`zarr.storage.ABSStore`. These stores are slated to be removed from Zarr-Python in version 3.0.
+  By :user:`Joe Hamman <jhamman>` :issue:`1801`.
+
 .. _release_2.17.2:
 
 2.17.2

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 .* is deprecated and will be removed in a Zarr-Python version 3*:FutureWarning",
     "ignore:The experimental Zarr V3 implementation in this version .*:FutureWarning",
 ]
 

zarr/_storage/absstore.py

@@ -5,7 +5,14 @@
 
 from numcodecs.compat import ensure_bytes
 from zarr.util import normalize_storage_path
-from zarr._storage.store import _get_metadata_suffix, data_root, meta_root, Store, StoreV3
+from zarr._storage.store import (
+    _get_metadata_suffix,
+    data_root,
+    meta_root,
+    Store,
+    StoreV3,
+    V3_DEPRECATION_MESSAGE,
+)
 from zarr.types import DIMENSION_SEPARATOR
 
 __doctest_requires__ = {
@@ -73,6 +80,12 @@ def __init__(
         dimension_separator: Optional[DIMENSION_SEPARATOR] = None,
         client=None,
     ):
+        warnings.warn(
+            V3_DEPRECATION_MESSAGE.format(store=self.__class__.__name__),
+            FutureWarning,
+            stacklevel=3,
+        )
+
         self._dimension_separator = dimension_separator
         self.prefix = normalize_storage_path(prefix)
         if client is None:

zarr/_storage/store.py

@@ -26,6 +26,11 @@
 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
 
+V3_DEPRECATION_MESSAGE = (
+    "The {store} is deprecated and will be removed in a Zarr-Python version 3, see "
+    "https://github.com/zarr-developers/zarr-python/issues/1274 for more information."
+)
+
 
 def assert_zarr_v3_api_available():
     # we issue a warning about the experimental v3 implementation when it is first used

zarr/storage.py

@@ -88,6 +88,7 @@
     DEFAULT_ZARR_VERSION,
     BaseStore,
     Store,
+    V3_DEPRECATION_MESSAGE,
 )
 
 __doctest_requires__ = {
@@ -1604,6 +1605,12 @@ class NestedDirectoryStore(DirectoryStore):
     special handling for chunk keys so that chunk files for multidimensional
     arrays are stored in a nested directory tree.
 
+    .. deprecated:: 2.18.0
+            NestedDirectoryStore will be removed in Zarr-Python 3.0 where controlling
+            the chunk key encoding will be supported as part of the array metadata. See
+            `GH1274 <https://github.com/zarr-developers/zarr-python/issues/1274>`_
+            for more information.
+
     Parameters
     ----------
     path : string
@@ -1675,6 +1682,13 @@ class NestedDirectoryStore(DirectoryStore):
     def __init__(
         self, path, normalize_keys=False, dimension_separator: Optional[DIMENSION_SEPARATOR] = "/"
     ):
+
+        warnings.warn(
+            V3_DEPRECATION_MESSAGE.format(store=self.__class__.__name__),
+            FutureWarning,
+            stacklevel=2,
+        )
+
         super().__init__(path, normalize_keys=normalize_keys)
         if dimension_separator is None:
             dimension_separator = "/"
@@ -1995,6 +2009,11 @@ def migrate_1to2(store):
 class DBMStore(Store):
     """Storage class using a DBM-style database.
 
+    .. deprecated:: 2.18.0
+            DBMStore will be removed in Zarr-Python 3.0. See
+            `GH1274 <https://github.com/zarr-developers/zarr-python/issues/1274>`_
+            for more information.
+
     Parameters
     ----------
     path : string
@@ -2083,6 +2102,12 @@ def __init__(
         dimension_separator: Optional[DIMENSION_SEPARATOR] = None,
         **open_kwargs,
     ):
+        warnings.warn(
+            V3_DEPRECATION_MESSAGE.format(store=self.__class__.__name__),
+            FutureWarning,
+            stacklevel=2,
+        )
+
         if open is None:
             import dbm
 
@@ -2200,6 +2225,10 @@ class LMDBStore(Store):
     """Storage class using LMDB. Requires the `lmdb <https://lmdb.readthedocs.io/>`_
     package to be installed.
 
+    .. deprecated:: 2.18.0
+        LMDBStore will be removed in Zarr-Python 3.0. See
+        `GH1274 <https://github.com/zarr-developers/zarr-python/issues/1274>`_
+        for more information.
 
     Parameters
     ----------
@@ -2261,6 +2290,12 @@ def __init__(
     ):
         import lmdb
 
+        warnings.warn(
+            V3_DEPRECATION_MESSAGE.format(store=self.__class__.__name__),
+            FutureWarning,
+            stacklevel=2,
+        )
+
         # set default memory map size to something larger than the lmdb default, which is
         # very likely to be too small for any moderate array (logic copied from zict)
         map_size = 2**40 if sys.maxsize >= 2**32 else 2**28
@@ -2580,6 +2615,11 @@ def __delitem__(self, key):
 class SQLiteStore(Store):
     """Storage class using SQLite.
 
+    .. deprecated:: 2.18.0
+            SQLiteStore will be removed in Zarr-Python 3.0. See
+            `GH1274 <https://github.com/zarr-developers/zarr-python/issues/1274>`_
+            for more information.
+
     Parameters
     ----------
     path : string
@@ -2612,6 +2652,12 @@ class SQLiteStore(Store):
     def __init__(self, path, dimension_separator: Optional[DIMENSION_SEPARATOR] = None, **kwargs):
         import sqlite3
 
+        warnings.warn(
+            V3_DEPRECATION_MESSAGE.format(store=self.__class__.__name__),
+            FutureWarning,
+            stacklevel=2,
+        )
+
         self._dimension_separator = dimension_separator
 
         # normalize path
@@ -2778,6 +2824,11 @@ class MongoDBStore(Store):
 
     .. note:: This is an experimental feature.
 
+    .. deprecated:: 2.18.0
+            MongoDBStore will be removed in Zarr-Python 3.0. See
+            `GH1274 <https://github.com/zarr-developers/zarr-python/issues/1274>`_
+            for more information.
+
     Requires the `pymongo <https://pymongo.readthedocs.io/en/stable/>`_
     package to be installed.
 
@@ -2810,6 +2861,12 @@ def __init__(
     ):
         import pymongo
 
+        warnings.warn(
+            V3_DEPRECATION_MESSAGE.format(store=self.__class__.__name__),
+            FutureWarning,
+            stacklevel=2,
+        )
+
         self._database = database
         self._collection = collection
         self._dimension_separator = dimension_separator
@@ -2866,6 +2923,11 @@ class RedisStore(Store):
 
     .. note:: This is an experimental feature.
 
+    .. deprecated:: 2.18.0
+            RedisStore will be removed in Zarr-Python 3.0. See
+            `GH1274 <https://github.com/zarr-developers/zarr-python/issues/1274>`_
+            for more information.
+
     Requires the `redis <https://redis-py.readthedocs.io/>`_
     package to be installed.
 
@@ -2885,6 +2947,12 @@ def __init__(
     ):
         import redis
 
+        warnings.warn(
+            V3_DEPRECATION_MESSAGE.format(store=self.__class__.__name__),
+            FutureWarning,
+            stacklevel=2,
+        )
+
         self._prefix = prefix
         self._kwargs = kwargs
         self._dimension_separator = dimension_separator