Backport PR #3098: refactor warnings (#3344)

Co-authored-by: Davis Bennett <[email protected]>

Author: meeseeksmachine

changes/3098.misc.rst

@@ -0,0 +1,3 @@
+Define Zarr-specific warning classes that subclass the Python built-in warnings.
+These classes makes it easier to control the visibility of warnings emitted by Zarr Python.
+See `zarr.errors` for these warning classes.

docs/user-guide/arrays.rst

@@ -238,6 +238,8 @@ built-in delta filter::
 
    >>> import lzma
    >>> from numcodecs.zarr3 import LZMA
+   >>> import warnings
+   >>> warnings.filterwarnings("ignore", category=UserWarning)
    >>>
    >>> lzma_filters = [dict(id=lzma.FILTER_DELTA, dist=4), dict(id=lzma.FILTER_LZMA2, preset=1)]
    >>> compressors = LZMA(filters=lzma_filters)

docs/user-guide/consolidated_metadata.rst

@@ -27,6 +27,8 @@ In Python, the consolidated metadata is available on the ``.consolidated_metadat
 attribute of the ``GroupMetadata`` object.
 
    >>> import zarr
+   >>> import warnings
+   >>> warnings.filterwarnings("ignore", category=UserWarning)
    >>>
    >>> store = zarr.storage.MemoryStore()
    >>> group = zarr.create_group(store=store)

pyproject.toml

@@ -389,16 +389,6 @@ addopts = [
 ]
 filterwarnings = [
     "error",
-    # TODO: explicitly filter or catch the warnings below where we expect them to be emitted in the tests
-    "ignore:Consolidated metadata is currently not part in the Zarr format 3 specification.*:UserWarning",
-    "ignore:Creating a zarr.buffer.gpu.Buffer with an array that does not support the __cuda_array_interface__.*:UserWarning",
-    "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: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",
     "ignore:Unclosed client session <aiohttp.client.ClientSession.*:ResourceWarning"
 ]
 markers = [

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 @@ def inner_f(*args: Any, **kwargs: Any) -> T:
                     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

@@ -39,7 +39,13 @@
     create_hierarchy,
 )
 from zarr.core.metadata import ArrayMetadataDict, ArrayV2Metadata, ArrayV3Metadata
-from zarr.errors import GroupNotFoundError, NodeTypeValidationError
+from zarr.errors import (
+    GroupNotFoundError,
+    NodeTypeValidationError,
+    ZarrDeprecationWarning,
+    ZarrRuntimeWarning,
+    ZarrUserWarning,
+)
 from zarr.storage import StorePath
 from zarr.storage._common import make_store_path
 
@@ -162,7 +168,7 @@ def _handle_zarr_version_or_format(
         )
     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
@@ -228,7 +234,7 @@ async def consolidate_metadata(
         warnings.warn(
             "Consolidated metadata is currently not part in the Zarr format 3 specification. It "
             "may not be supported by other zarr implementations and may change in the future.",
-            category=UserWarning,
+            category=ZarrUserWarning,
             stacklevel=1,
         )
 
@@ -536,7 +542,7 @@ async def save_group(
     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.
 
@@ -674,13 +680,13 @@ async def group(
     store_path = await make_store_path(store, path=path, mode=mode, storage_options=storage_options)
 
     if chunk_store is not None:
-        warnings.warn("chunk_store is not yet implemented", RuntimeWarning, stacklevel=2)
+        warnings.warn("chunk_store is not yet implemented", ZarrRuntimeWarning, stacklevel=2)
     if cache_attrs is not None:
-        warnings.warn("cache_attrs is not yet implemented", RuntimeWarning, stacklevel=2)
+        warnings.warn("cache_attrs is not yet implemented", ZarrRuntimeWarning, stacklevel=2)
     if synchronizer is not None:
-        warnings.warn("synchronizer is not yet implemented", RuntimeWarning, stacklevel=2)
+        warnings.warn("synchronizer is not yet implemented", ZarrRuntimeWarning, stacklevel=2)
     if meta_array is not None:
-        warnings.warn("meta_array is not yet implemented", RuntimeWarning, stacklevel=2)
+        warnings.warn("meta_array is not yet implemented", ZarrRuntimeWarning, stacklevel=2)
 
     if attributes is None:
         attributes = {}
@@ -827,13 +833,13 @@ async def open_group(
     zarr_format = _handle_zarr_version_or_format(zarr_version=zarr_version, zarr_format=zarr_format)
 
     if cache_attrs is not None:
-        warnings.warn("cache_attrs is not yet implemented", RuntimeWarning, stacklevel=2)
+        warnings.warn("cache_attrs is not yet implemented", ZarrRuntimeWarning, stacklevel=2)
     if synchronizer is not None:
-        warnings.warn("synchronizer is not yet implemented", RuntimeWarning, stacklevel=2)
+        warnings.warn("synchronizer is not yet implemented", ZarrRuntimeWarning, stacklevel=2)
     if meta_array is not None:
-        warnings.warn("meta_array is not yet implemented", RuntimeWarning, stacklevel=2)
+        warnings.warn("meta_array is not yet implemented", ZarrRuntimeWarning, stacklevel=2)
     if chunk_store is not None:
-        warnings.warn("chunk_store is not yet implemented", RuntimeWarning, stacklevel=2)
+        warnings.warn("chunk_store is not yet implemented", ZarrRuntimeWarning, stacklevel=2)
 
     store_path = await make_store_path(store, mode=mode, storage_options=storage_options, path=path)
     if attributes is None:
@@ -1011,19 +1017,19 @@ async def create(
     )
 
     if synchronizer is not None:
-        warnings.warn("synchronizer is not yet implemented", RuntimeWarning, stacklevel=2)
+        warnings.warn("synchronizer is not yet implemented", ZarrRuntimeWarning, stacklevel=2)
     if chunk_store is not None:
-        warnings.warn("chunk_store is not yet implemented", RuntimeWarning, stacklevel=2)
+        warnings.warn("chunk_store is not yet implemented", ZarrRuntimeWarning, stacklevel=2)
     if cache_metadata is not None:
-        warnings.warn("cache_metadata is not yet implemented", RuntimeWarning, stacklevel=2)
+        warnings.warn("cache_metadata is not yet implemented", ZarrRuntimeWarning, stacklevel=2)
     if cache_attrs is not None:
-        warnings.warn("cache_attrs is not yet implemented", RuntimeWarning, stacklevel=2)
+        warnings.warn("cache_attrs is not yet implemented", ZarrRuntimeWarning, stacklevel=2)
     if object_codec is not None:
-        warnings.warn("object_codec is not yet implemented", RuntimeWarning, stacklevel=2)
+        warnings.warn("object_codec is not yet implemented", ZarrRuntimeWarning, stacklevel=2)
     if read_only is not None:
-        warnings.warn("read_only is not yet implemented", RuntimeWarning, stacklevel=2)
+        warnings.warn("read_only is not yet implemented", ZarrRuntimeWarning, stacklevel=2)
     if meta_array is not None:
-        warnings.warn("meta_array is not yet implemented", RuntimeWarning, stacklevel=2)
+        warnings.warn("meta_array is not yet implemented", ZarrRuntimeWarning, stacklevel=2)
 
     if write_empty_chunks is not None:
         _warn_write_empty_chunks_kwarg()
@@ -1042,7 +1048,7 @@ async def create(
                 "This is redundant. When both are set, write_empty_chunks will be used instead "
                 "of the value in config."
             )
-            warnings.warn(UserWarning(msg), stacklevel=1)
+            warnings.warn(ZarrUserWarning(msg), stacklevel=1)
         config_parsed = dataclasses.replace(config_parsed, write_empty_chunks=write_empty_chunks)
 
     return await AsyncArray._create(

src/zarr/api/synchronous.py

@@ -10,6 +10,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
@@ -339,7 +340,7 @@ def save_group(
     )
 
 
-@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/codecs/transpose.py

@@ -56,7 +56,7 @@ def validate(
     ) -> None:
         if len(self.order) != len(shape):
             raise ValueError(
-                f"The `order` tuple needs have as many entries as there are dimensions in the array. Got {self.order}."
+                f"The `order` tuple must have as many entries as there are dimensions in the array. Got {self.order}."
             )
         if len(self.order) != len(set(self.order)):
             raise ValueError(
@@ -71,7 +71,7 @@ def evolve_from_array_spec(self, array_spec: ArraySpec) -> Self:
         ndim = array_spec.ndim
         if len(self.order) != ndim:
             raise ValueError(
-                f"The `order` tuple needs have as many entries as there are dimensions in the array. Got {self.order}."
+                f"The `order` tuple must have as many entries as there are dimensions in the array. Got {self.order}."
             )
         if len(self.order) != len(set(self.order)):
             raise ValueError(

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

@@ -119,7 +119,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, ZarrUserWarning
 from zarr.registry import (
     _parse_array_array_codec,
     _parse_array_bytes_codec,
@@ -232,7 +232,7 @@ async def get_array_metadata(
         if zarr_json_bytes is not None and zarray_bytes is not None:
             # warn and favor v3
             msg = f"Both zarr.json (Zarr format 3) and .zarray (Zarr format 2) metadata objects exist at {store_path}. Zarr v3 will be used."
-            warnings.warn(msg, stacklevel=1)
+            warnings.warn(msg, category=ZarrUserWarning, stacklevel=1)
         if zarr_json_bytes is None and zarray_bytes is None:
             raise FileNotFoundError(store_path)
         # set zarr_format based on which keys were found
@@ -441,7 +441,7 @@ async def create(
     ) -> AsyncArray[ArrayV3Metadata] | AsyncArray[ArrayV2Metadata]: ...
 
     @classmethod
-    @deprecated("Use zarr.api.asynchronous.create_array instead.")
+    @deprecated("Use zarr.api.asynchronous.create_array instead.", category=ZarrDeprecationWarning)
     async def create(
         cls,
         store: StoreLike,
@@ -1061,7 +1061,7 @@ def serializer(self) -> ArrayBytesCodec | None:
         )
 
     @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.
@@ -1855,7 +1855,7 @@ class Array:
     _async_array: AsyncArray[ArrayV3Metadata] | AsyncArray[ArrayV2Metadata]
 
     @classmethod
-    @deprecated("Use zarr.create_array instead.")
+    @deprecated("Use zarr.create_array instead.", category=ZarrDeprecationWarning)
     def create(
         cls,
         store: StoreLike,
@@ -2242,7 +2242,7 @@ def serializer(self) -> None | ArrayBytesCodec:
         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.
@@ -4648,7 +4648,7 @@ def _parse_keep_array_attr(
             warnings.warn(
                 "The 'order' attribute of a Zarr format 2 array does not have a direct analogue in Zarr format 3. "
                 "The existing order='F' of the source Zarr format 2 array will be ignored.",
-                UserWarning,
+                ZarrUserWarning,
                 stacklevel=2,
             )
         elif order is None and zarr_format == 2:
@@ -4937,7 +4937,7 @@ def _parse_deprecated_compressor(
         if zarr_format == 3:
             warn(
                 "The `compressor` argument is deprecated. Use `compressors` instead.",
-                category=UserWarning,
+                category=ZarrUserWarning,
                 stacklevel=2,
             )
         if compressor is None: