refactor warnings

pyproject.toml

@@ -408,7 +408,7 @@ filterwarnings = [
     "ignore:Automatic shard shape inference is experimental and may change without notice.*:UserWarning",
     "ignore:The codec .* is currently not part in the Zarr format 3 specification.*:UserWarning",
     "ignore:The dtype .* is currently not part in the Zarr format 3 specification.*:UserWarning",
-    "ignore:Use zarr.create_array instead.:DeprecationWarning",
+    "ignore:Use zarr.create_array instead.:zarr.errors.ZarrDeprecationWarning",
     "ignore:Duplicate name.*:UserWarning",
     "ignore:The `compressor` argument is deprecated. Use `compressors` instead.:UserWarning",
     "ignore:Numcodecs codecs are not in the Zarr version 3 specification and may not be supported by other zarr implementations.:UserWarning",

src/zarr/_compat.py

@@ -4,6 +4,8 @@
 from inspect import Parameter, signature
 from typing import Any, TypeVar
 
+from zarr.errors import ZarrFutureWarning
+
 T = TypeVar("T")
 
 # Based off https://github.com/scikit-learn/scikit-learn/blob/e87b32a81c70abed8f2e97483758eb64df8255e9/sklearn/utils/validation.py#L63
@@ -54,7 +56,7 @@
                     f"{version} passing these as positional arguments "
                     "will result in an error"
                 ),
-                FutureWarning,
+                ZarrFutureWarning,
                 stacklevel=2,
             )
             kwargs.update(zip(sig.parameters, args, strict=False))

src/zarr/api/asynchronous.py

@@ -40,7 +40,7 @@
     create_hierarchy,
 )
 from zarr.core.metadata import ArrayMetadataDict, ArrayV2Metadata, ArrayV3Metadata
-from zarr.errors import GroupNotFoundError, NodeTypeValidationError
+from zarr.errors import GroupNotFoundError, NodeTypeValidationError, ZarrDeprecationWarning
 from zarr.storage import StorePath
 from zarr.storage._common import make_store_path
 
@@ -161,7 +161,7 @@
         )
     if zarr_version is not None:
         warnings.warn(
-            "zarr_version is deprecated, use zarr_format", DeprecationWarning, stacklevel=2
+            "zarr_version is deprecated, use zarr_format", ZarrDeprecationWarning, stacklevel=2
         )
         return zarr_version
     return zarr_format
@@ -535,7 +535,7 @@
     await asyncio.gather(*aws)
 
 
-@deprecated("Use AsyncGroup.tree instead.")
+@deprecated("Use AsyncGroup.tree instead.", category=ZarrDeprecationWarning)
 async def tree(grp: AsyncGroup, expand: bool | None = None, level: int | None = None) -> Any:
     """Provide a rich display of the hierarchy.
 

src/zarr/api/synchronous.py

@@ -11,6 +11,7 @@
 from zarr.core.group import Group
 from zarr.core.sync import sync
 from zarr.core.sync_group import create_hierarchy
+from zarr.errors import ZarrDeprecationWarning
 
 if TYPE_CHECKING:
     from collections.abc import Iterable
@@ -341,7 +342,7 @@
     )
 
 
-@deprecated("Use Group.tree instead.")
+@deprecated("Use Group.tree instead.", category=ZarrDeprecationWarning)
 def tree(grp: Group, expand: bool | None = None, level: int | None = None) -> Any:
     """Provide a rich display of the hierarchy.
 

src/zarr/convenience.py

@@ -22,6 +22,7 @@
     save_group,
     tree,
 )
+from zarr.errors import ZarrDeprecationWarning
 
 __all__ = [
     "consolidate_metadata",
@@ -40,6 +41,6 @@
 warnings.warn(
     "zarr.convenience is deprecated. "
     "Import these functions from the top level zarr. namespace instead.",
-    DeprecationWarning,
+    ZarrDeprecationWarning,
     stacklevel=2,
 )

src/zarr/core/array.py

@@ -114,7 +114,7 @@
 )
 from zarr.core.metadata.v3 import parse_node_type_array
 from zarr.core.sync import sync
-from zarr.errors import MetadataValidationError
+from zarr.errors import MetadataValidationError, ZarrDeprecationWarning
 from zarr.registry import (
     _parse_array_array_codec,
     _parse_array_bytes_codec,
@@ -401,7 +401,7 @@
     ) -> AsyncArray[ArrayV3Metadata] | AsyncArray[ArrayV2Metadata]: ...
 
     @classmethod
-    @deprecated("Use zarr.api.asynchronous.create_array instead.")
+    @deprecated("Use zarr.api.asynchronous.create_array instead.", category=ZarrDeprecationWarning)
     @_deprecate_positional_args
     async def create(
         cls,
@@ -1009,7 +1009,7 @@
         )
 
     @property
-    @deprecated("Use AsyncArray.compressors instead.")
+    @deprecated("Use AsyncArray.compressors instead.", category=ZarrDeprecationWarning)
     def compressor(self) -> numcodecs.abc.Codec | None:
         """
         Compressor that is applied to each chunk of the array.
@@ -1740,7 +1740,7 @@
     _async_array: AsyncArray[ArrayV3Metadata] | AsyncArray[ArrayV2Metadata]
 
     @classmethod
-    @deprecated("Use zarr.create_array instead.")
+    @deprecated("Use zarr.create_array instead.", category=ZarrDeprecationWarning)
     @_deprecate_positional_args
     def create(
         cls,
@@ -2128,7 +2128,7 @@
         return self._async_array.serializer
 
     @property
-    @deprecated("Use Array.compressors instead.")
+    @deprecated("Use Array.compressors instead.", category=ZarrDeprecationWarning)
     def compressor(self) -> numcodecs.abc.Codec | None:
         """
         Compressor that is applied to each chunk of the array.

src/zarr/core/dtype/common.py

@@ -14,6 +14,7 @@
 )
 
 from zarr.core.common import NamedConfig
+from zarr.errors import ZarrFutureWarning
 
 EndiannessStr = Literal["little", "big"]
 ENDIANNESS_STR: Final = "little", "big"
@@ -205,7 +206,7 @@
     object_codec_id: ClassVar[str]
 
 
-class UnstableSpecificationWarning(FutureWarning): ...
+class UnstableSpecificationWarning(ZarrFutureWarning): ...
 
 
 def v3_unstable_dtype_warning(dtype: object) -> None:

src/zarr/core/group.py

@@ -50,7 +50,12 @@
 from zarr.core.config import config
 from zarr.core.metadata import ArrayV2Metadata, ArrayV3Metadata
 from zarr.core.sync import SyncMixin, sync
-from zarr.errors import ContainsArrayError, ContainsGroupError, MetadataValidationError
+from zarr.errors import (
+    ContainsArrayError,
+    ContainsGroupError,
+    MetadataValidationError,
+    ZarrDeprecationWarning,
+)
 from zarr.storage import StoreLike, StorePath
 from zarr.storage._common import ensure_no_existing_node, make_store_path
 from zarr.storage._utils import _join_paths, _normalize_path_keys, normalize_path
@@ -1132,7 +1137,7 @@
             config=config,
         )
 
-    @deprecated("Use AsyncGroup.create_array instead.")
+    @deprecated("Use AsyncGroup.create_array instead.", category=ZarrDeprecationWarning)
     async def create_dataset(
         self, name: str, *, shape: ShapeLike, **kwargs: Any
     ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
@@ -1166,7 +1171,7 @@
             await array.setitem(slice(None), data)
         return array
 
-    @deprecated("Use AsyncGroup.require_array instead.")
+    @deprecated("Use AsyncGroup.require_array instead.", category=ZarrDeprecationWarning)
     async def require_dataset(
         self,
         name: str,
@@ -2545,7 +2550,7 @@
             )
         )
 
-    @deprecated("Use Group.create_array instead.")
+    @deprecated("Use Group.create_array instead.", category=ZarrDeprecationWarning)
     def create_dataset(self, name: str, **kwargs: Any) -> Array:
         """Create an array.
 
@@ -2569,7 +2574,7 @@
         """
         return Array(self._sync(self._async_group.create_dataset(name, **kwargs)))
 
-    @deprecated("Use Group.require_array instead.")
+    @deprecated("Use Group.require_array instead.", category=ZarrDeprecationWarning)
     def require_dataset(self, name: str, *, shape: ShapeLike, **kwargs: Any) -> Array:
         """Obtain an array, creating if it doesn't exist.
 
@@ -2799,7 +2804,7 @@
         """
         return self._sync(self._async_group.move(source, dest))
 
-    @deprecated("Use Group.create_array instead.")
+    @deprecated("Use Group.create_array instead.", category=ZarrDeprecationWarning)
     @_deprecate_positional_args
     def array(
         self,

src/zarr/creation.py

@@ -23,6 +23,7 @@
     zeros,
     zeros_like,
 )
+from zarr.errors import ZarrDeprecationWarning
 
 __all__ = [
     "array",
@@ -42,6 +43,6 @@
 warnings.warn(
     "zarr.creation is deprecated. "
     "Import these functions from the top level zarr. namespace instead.",
-    DeprecationWarning,
+    ZarrDeprecationWarning,
     stacklevel=2,
 )

src/zarr/errors.py

@@ -66,3 +66,9 @@ class NodeTypeValidationError(MetadataValidationError):
     This can be raised when the value is invalid or unexpected given the context,
     for example an 'array' node when we expected a 'group'.
     """
+
+
+class ZarrFutureWarning(FutureWarning): ...
+
+
+class ZarrDeprecationWarning(DeprecationWarning): ...

src/zarr/storage/__init__.py

@@ -3,6 +3,7 @@
 from types import ModuleType
 from typing import Any
 
+from zarr.errors import ZarrDeprecationWarning
 from zarr.storage._common import StoreLike, StorePath
 from zarr.storage._fsspec import FsspecStore
 from zarr.storage._local import LocalStore
@@ -33,7 +34,7 @@
                 "setting zarr.storage.default_compressor is deprecated, use "
                 "zarr.config to configure array.v2_default_compressor "
                 "e.g. config.set({'codecs.zstd':'numcodecs.Zstd', 'array.v2_default_compressor.numeric': 'zstd'})",
-                DeprecationWarning,
+                ZarrDeprecationWarning,
                 stacklevel=1,
             )
         else:

tests/test_api.py

@@ -5,6 +5,8 @@
 
 import zarr.codecs
 import zarr.storage
+from zarr.storage._local import LocalStore
+from zarr.storage._zip import ZipStore
 
 if TYPE_CHECKING:
     import pathlib
@@ -38,8 +40,8 @@
     save_group,
 )
 from zarr.core.buffer import NDArrayLike
-from zarr.errors import MetadataValidationError
-from zarr.storage import LocalStore, MemoryStore, ZipStore
+from zarr.errors import MetadataValidationError, ZarrDeprecationWarning, ZarrFutureWarning
+from zarr.storage import MemoryStore
 from zarr.storage._utils import normalize_path
 from zarr.testing.utils import gpu_test
 
@@ -441,7 +443,7 @@ def test_tree() -> None:
     g3.create_group("baz")
     g5 = g3.create_group("qux")
     g5.create_array("baz", shape=(100,), chunks=(10,), dtype="float64")
-    with pytest.warns(DeprecationWarning):
+    with pytest.warns(ZarrDeprecationWarning):
         assert repr(zarr.tree(g1)) == repr(g1.tree())
         assert str(zarr.tree(g1)) == str(g1.tree())
 
@@ -1115,17 +1117,17 @@ def test_tree() -> None:
 
 def test_open_positional_args_deprecated() -> None:
     store = MemoryStore()
-    with pytest.warns(FutureWarning, match="pass"):
+    with pytest.warns(ZarrFutureWarning, match="pass"):
         zarr.api.synchronous.open(store, "w", shape=(1,))
 
 
 def test_save_array_positional_args_deprecated() -> None:
     store = MemoryStore()
     with warnings.catch_warnings():
         warnings.filterwarnings(
-            "ignore", message="zarr_version is deprecated", category=DeprecationWarning
+            "ignore", message="zarr_version is deprecated", category=ZarrDeprecationWarning
         )
-        with pytest.warns(FutureWarning, match="pass"):
+        with pytest.warns(ZarrFutureWarning, match="pass"):
             save_array(
                 store,
                 np.ones(
@@ -1137,13 +1139,13 @@ def test_save_array_positional_args_deprecated() -> None:
 
 def test_group_positional_args_deprecated() -> None:
     store = MemoryStore()
-    with pytest.warns(FutureWarning, match="pass"):
+    with pytest.warns(ZarrFutureWarning, match="pass"):
         group(store, True)
 
 
 def test_open_group_positional_args_deprecated() -> None:
     store = MemoryStore()
-    with pytest.warns(FutureWarning, match="pass"):
+    with pytest.warns(ZarrFutureWarning, match="pass"):
         open_group(store, "w")
 
 

tests/test_array.py

@@ -56,7 +56,12 @@
 from zarr.core.indexing import BasicIndexer, ceildiv
 from zarr.core.metadata.v2 import ArrayV2Metadata
 from zarr.core.sync import sync
-from zarr.errors import ContainsArrayError, ContainsGroupError
+from zarr.errors import (
+    ContainsArrayError,
+    ContainsGroupError,
+    ZarrDeprecationWarning,
+    ZarrFutureWarning,
+)
 from zarr.storage import LocalStore, MemoryStore, StorePath
 
 from .test_dtype.conftest import zdtype_examples
@@ -251,46 +256,46 @@ def test_array_v3_fill_value(store: MemoryStore, fill_value: int, dtype_str: str
 
 
 async def test_create_deprecated() -> None:
-    with pytest.warns(DeprecationWarning):
-        with pytest.warns(FutureWarning, match=re.escape("Pass shape=(2, 2) as keyword args")):
+    with pytest.warns(ZarrDeprecationWarning):
+        with pytest.warns(ZarrFutureWarning, match=re.escape("Pass shape=(2, 2) as keyword args")):
             await zarr.AsyncArray.create(MemoryStore(), (2, 2), dtype="f8")  # type: ignore[call-overload]
-    with pytest.warns(DeprecationWarning):
-        with pytest.warns(FutureWarning, match=re.escape("Pass shape=(2, 2) as keyword args")):
+    with pytest.warns(ZarrDeprecationWarning):
+        with pytest.warns(ZarrFutureWarning, match=re.escape("Pass shape=(2, 2) as keyword args")):
             zarr.Array.create(MemoryStore(), (2, 2), dtype="f8")
 
 
 def test_selection_positional_args_deprecated() -> None:
     store = MemoryStore()
     arr = zarr.create_array(store, shape=(2, 2), dtype="f8")
 
-    with pytest.warns(FutureWarning, match="Pass out"):
+    with pytest.warns(ZarrFutureWarning, match="Pass out"):
         arr.get_basic_selection(..., NDBuffer(array=np.empty((2, 2))))
 
-    with pytest.warns(FutureWarning, match="Pass fields"):
+    with pytest.warns(ZarrFutureWarning, match="Pass fields"):
         arr.set_basic_selection(..., 1, None)
 
-    with pytest.warns(FutureWarning, match="Pass out"):
+    with pytest.warns(ZarrFutureWarning, match="Pass out"):
         arr.get_orthogonal_selection(..., NDBuffer(array=np.empty((2, 2))))
 
-    with pytest.warns(FutureWarning, match="Pass"):
+    with pytest.warns(ZarrFutureWarning, match="Pass"):
         arr.set_orthogonal_selection(..., 1, None)
 
-    with pytest.warns(FutureWarning, match="Pass"):
+    with pytest.warns(ZarrFutureWarning, match="Pass"):
         arr.get_mask_selection(np.zeros((2, 2), dtype=bool), NDBuffer(array=np.empty((0,))))
 
-    with pytest.warns(FutureWarning, match="Pass"):
+    with pytest.warns(ZarrFutureWarning, match="Pass"):
         arr.set_mask_selection(np.zeros((2, 2), dtype=bool), 1, None)
 
-    with pytest.warns(FutureWarning, match="Pass"):
+    with pytest.warns(ZarrFutureWarning, match="Pass"):
         arr.get_coordinate_selection(([0, 1], [0, 1]), NDBuffer(array=np.empty((2,))))
 
-    with pytest.warns(FutureWarning, match="Pass"):
+    with pytest.warns(ZarrFutureWarning, match="Pass"):
         arr.set_coordinate_selection(([0, 1], [0, 1]), 1, None)
 
-    with pytest.warns(FutureWarning, match="Pass"):
+    with pytest.warns(ZarrFutureWarning, match="Pass"):
         arr.get_block_selection((0, slice(None)), NDBuffer(array=np.empty((2, 2))))
 
-    with pytest.warns(FutureWarning, match="Pass"):
+    with pytest.warns(ZarrFutureWarning, match="Pass"):
         arr.set_block_selection((0, slice(None)), 1, None)