emit warning about unstable dtype when serializing Structured dtype t…

…o JSON

src/zarr/core/dtype/common.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import warnings
 from dataclasses import dataclass
 from typing import Final, Literal
 
@@ -42,4 +43,23 @@
 
     @property
     def item_size(self) -> int:
         raise NotImplementedError
+
+
+class UnstableSpecificationWarning(FutureWarning): ...
+
+
+def v3_unstable_dtype_warning(dtype: object) -> None:
+    """
+    Emit this warning when a data type does not have a stable zarr v3 spec
+    """
+    msg = (
+        f"The data type ({dtype}) does not have a Zarr V3 specification. "
+        "That means that the representation of data saved with this data type may change without "
+        "warning in a future version of Zarr Python. "
+        "Arrays stored with this data type may be unreadable by other Zarr libraries "
+        "Use this data type at your own risk! "
+        "Check https://github.com/zarr-developers/zarr-extensions/tree/main/data-types for the "
+        "status of data type specifications for Zarr V3."
+    )
+    warnings.warn(msg, category=UnstableSpecificationWarning, stacklevel=2)

src/zarr/core/dtype/npy/sized.py

@@ -7,7 +7,13 @@
 import numpy as np
 
 from zarr.core.common import JSON, ZarrFormat
-from zarr.core.dtype.common import DataTypeValidationError, HasEndianness, HasItemSize, HasLength
+from zarr.core.dtype.common import (
+    DataTypeValidationError,
+    HasEndianness,
+    HasItemSize,
+    HasLength,
+    v3_unstable_dtype_warning,
+)
 from zarr.core.dtype.npy.common import (
     EndiannessNumpy,
     bytes_from_json,
@@ -308,7 +314,7 @@
         fields: list[tuple[str, ZDType[TBaseDType, TBaseScalar]]] = []
 
         if dtype.fields is None:
             raise ValueError("numpy dtype has no fields")
 
         # fields of a structured numpy dtype are either 2-tuples or 3-tuples. we only
         # care about the first element in either case.
@@ -325,6 +331,7 @@
         if zarr_format == 2:
             return fields
         elif zarr_format == 3:
+            v3_unstable_dtype_warning(self)
             base_dict = {"name": self._zarr_v3_name}
             base_dict["configuration"] = {"fields": fields}  # type: ignore[assignment]
             return cast("JSON", base_dict)
@@ -388,7 +395,7 @@
                         f"Invalid type: {data}. Expected a dictionary."
                     )  # pragma: no cover
             raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
         raise DataTypeValidationError(f"Invalid JSON representation of data type {cls}.")
 
     def to_dtype(self) -> np.dtypes.VoidDType[int]:
         return cast(

src/zarr/core/dtype/wrapper.py

@@ -22,7 +22,6 @@
 
 from __future__ import annotations
 
-import warnings
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, ClassVar, Generic, Self, TypeGuard, TypeVar
@@ -159,13 +158,13 @@
         """
         if self.check_value(data):
             return self._cast_value_unsafe(data)
         msg = (
             f"The value {data} failed a type check. "
             f"It cannot be safely cast to a scalar compatible with {self.dtype_cls}. "
             f"Consult the documentation for {self} to determine the possible values that can "
             "be cast to scalars of the wrapped data type."
         )
         raise TypeError(msg)
 
     @abstractmethod
     def check_value(self, data: object) -> bool:
@@ -336,15 +335,3 @@
             The native scalar value.
         """
         ...
-
-
-def v3_unstable_dtype_warning(dtype: ZDType[TBaseDType, TBaseScalar]) -> None:
-    msg = (
-        f"You are using a data type ({dtype}) that does not have a stable Zarr V3 specification."
-        "Be advised that arrays stored with this data type may be unreadable by other Zarr "
-        "libraries, and possibly future versions of Zarr-Python as well. "
-        "Use this data type at your own risk."
-        "See https://github.com/zarr-developers/zarr-extensions/tree/main/data-types for a list"
-        "of data types with a stable Zarr V3 specification."
-    )
-    warnings.warn(msg, category=FutureWarning, stacklevel=2)

tests/test_array.py

@@ -189,6 +189,7 @@ def test_array_name_properties_with_group(
     assert spam.basename == "spam"
 
 
+@pytest.mark.filterwarnings("ignore::zarr.core.dtype.common.UnstableSpecificationWarning")
 @pytest.mark.parametrize("store", ["memory"], indirect=True)
 @pytest.mark.parametrize("specifiy_fill_value", [True, False])
 @pytest.mark.parametrize(
@@ -199,7 +200,7 @@ def test_array_fill_value_default(
 ) -> None:
     """
     Test that creating an array with the fill_value parameter set to None, or unspecified,
-    results in the expected fill_value attribute of the array, i.e. 0 cast to the array's dtype.
+    results in the expected fill_value attribute of the array, i.e. the default value of the dtype
     """
     shape = (10,)
     if specifiy_fill_value:
@@ -994,6 +995,7 @@ def test_chunks_and_shards(store: Store) -> None:
 
     @staticmethod
     @pytest.mark.parametrize("dtype", zdtype_examples)
+    @pytest.mark.filterwarnings("ignore::zarr.core.dtype.common.UnstableSpecificationWarning")
     def test_default_fill_value(dtype: ZDType[Any, Any], store: Store) -> None:
         """
         Test that the fill value of an array is set to the default value for the dtype object
@@ -1005,6 +1007,7 @@ def test_default_fill_value(dtype: ZDType[Any, Any], store: Store) -> None:
             assert a.fill_value == dtype.default_value()
 
     @staticmethod
+    @pytest.mark.filterwarnings("ignore::zarr.core.dtype.common.UnstableSpecificationWarning")
     @pytest.mark.parametrize("dtype", zdtype_examples)
     def test_dtype_forms(dtype: ZDType[Any, Any], store: Store, zarr_format: ZarrFormat) -> None:
         """
@@ -1050,6 +1053,7 @@ def test_dtype_forms(dtype: ZDType[Any, Any], store: Store, zarr_format: ZarrFor
             assert a.dtype == c.dtype
 
     @staticmethod
+    @pytest.mark.filterwarnings("ignore::zarr.core.dtype.common.UnstableSpecificationWarning")
     @pytest.mark.parametrize("dtype", zdtype_examples)
     def test_dtype_roundtrip(
         dtype: ZDType[Any, Any], store: Store, zarr_format: ZarrFormat

tests/test_dtype/conftest.py

@@ -1,4 +1,5 @@
 # Generate a collection of zdtype instances for use in testing.
+import warnings
 from typing import Any
 
 import numpy as np
@@ -13,7 +14,11 @@
 for wrapper_cls in data_type_registry.contents.values():
     # The Structured dtype has to be constructed with some actual fields
     if wrapper_cls is Structured:
-        zdtype_examples += (wrapper_cls.from_dtype(np.dtype([("a", np.float64), ("b", np.int8)])),)
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            zdtype_examples += (
+                wrapper_cls.from_dtype(np.dtype([("a", np.float64), ("b", np.int8)])),
+            )
     elif issubclass(wrapper_cls, HasLength):
         zdtype_examples += (wrapper_cls(length=1),)
     elif issubclass(wrapper_cls, DateTime64 | TimeDelta64):

tests/test_dtype/test_wrapper.py

@@ -105,6 +105,7 @@ def test_from_json_roundtrip_v2(self, valid_json_v2: Any) -> None:
         zdtype = self.test_cls.from_json(valid_json_v2, zarr_format=2)
         assert zdtype.to_json(zarr_format=2) == valid_json_v2
 
+    @pytest.mark.filterwarnings("ignore::zarr.core.dtype.common.UnstableSpecificationWarning")
     def test_from_json_roundtrip_v3(self, valid_json_v3: Any) -> None:
         zdtype = self.test_cls.from_json(valid_json_v3, zarr_format=3)
         assert zdtype.to_json(zarr_format=3) == valid_json_v3

tests/test_dtype_registry.py

@@ -94,6 +94,7 @@ def test_unregistered_dtype(data_type_registry_fixture: DataTypeRegistry) -> Non
             data_type_registry_fixture.get(outside_dtype)
 
     @staticmethod
+    @pytest.mark.filterwarnings("ignore::zarr.core.dtype.common.UnstableSpecificationWarning")
     @pytest.mark.parametrize("zdtype", zdtype_examples)
     def test_registered_dtypes(
         zdtype: ZDType[TBaseDType, TBaseScalar], zarr_format: ZarrFormat
@@ -111,6 +112,7 @@ def test_registered_dtypes(
         )
 
     @staticmethod
+    @pytest.mark.filterwarnings("ignore::zarr.core.dtype.common.UnstableSpecificationWarning")
     @pytest.mark.parametrize("zdtype", zdtype_examples)
     def test_match_dtype_unique(
         zdtype: ZDType[Any, Any],