prune old string dtype class (#3973)

d-v-b · maxrjones · web-flow · commit 1907ad6422d1 · 2026-05-22T13:07:03.000Z
* chore: remove old stringdtype specialized for numpy &lt; 2

* chore: narrow test fn signature

* docs: changelog

* chore: rename test class

* Update changes/3973.removal.md

Co-authored-by: Max Jones &lt;14077947+maxrjones@users.noreply.github.com&gt;

---------

Co-authored-by: Max Jones &lt;14077947+maxrjones@users.noreply.github.com&gt;
diff --git a/changes/3973.removal.md b/changes/3973.removal.md
@@ -0,0 +1 @@
+Removed the NumPy 1.x implementation of the `VariableLengthUTF8` data type because NumPy 1.x is no longer supported under [SPEC0](https://scientific-python.org/specs/spec-0000/).
diff --git a/src/zarr/core/dtype/npy/string.py b/src/zarr/core/dtype/npy/string.py
@@ -38,8 +38,6 @@
     from zarr.core.common import JSON, ZarrFormat
     from zarr.core.dtype.wrapper import TBaseDType
 
-_NUMPY_SUPPORTS_VLEN_STRING = hasattr(np.dtypes, "StringDType")
-
 
 @runtime_checkable
 class SupportsStr(Protocol):
@@ -451,36 +449,40 @@ class VariableLengthUTF8JSON_V2(DTypeConfig_V2[Literal["|O"], Literal["vlen-utf8
     """
 
 
-# VariableLengthUTF8 is defined in two places, conditioned on the version of NumPy.
-# If NumPy 2 is installed, then VariableLengthUTF8 is defined with the NumPy variable length
-# string dtype as the native dtype. Otherwise, VariableLengthUTF8 is defined with the NumPy object
-# dtype as the native dtype.
-class UTF8Base[DType: TBaseDType](ZDType[DType, str], HasObjectCodec):
+@dataclass(frozen=True, kw_only=True)
+class VariableLengthUTF8(ZDType[np.dtypes.StringDType, str], HasObjectCodec):  # type: ignore[type-var]
     """
-    A base class for variable-length UTF-8 string data types.
+    A Zarr data type for arrays containing variable-length UTF-8 strings.
+
+    Wraps the ``np.dtypes.StringDType`` data type. Scalars for this data type are instances
+    of ``str``.
 
-    Not intended for direct use, but as a base for concrete implementations.
 
     Attributes
     ----------
-    object_codec_id : ClassVar[Literal["vlen-utf8"]]
+    dtype_cls : Type[np.dtypes.StringDType]
+        The NumPy dtype class for this data type.
+    _zarr_v3_name : ClassVar[Literal["variable_length_utf8"]] = "variable_length_utf8"
+        The name of this data type in Zarr V3.
+    object_codec_id : ClassVar[Literal["vlen-utf8"]] = "vlen-utf8"
         The object codec ID for this data type.
 
     References
     ----------
-    This data type does not have a Zarr V3 specification.
+    https://github.com/zarr-developers/zarr-extensions/tree/main/data-types/string
 
-    The Zarr V2 data type specification can be found [here](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).
     """
 
+    dtype_cls = np.dtypes.StringDType  # type: ignore[assignment]
     _zarr_v3_name: ClassVar[Literal["string"]] = "string"
     object_codec_id: ClassVar[Literal["vlen-utf8"]] = "vlen-utf8"
 
     @classmethod
     def from_native_dtype(cls, dtype: TBaseDType) -> Self:
         """
         Create an instance of this data type from a compatible NumPy data type.
-
+        We reject NumPy StringDType instances that have the `na_object` field set,
+        because this is not representable by the Zarr `string` data type.
 
         Parameters
         ----------
@@ -496,13 +498,33 @@ def from_native_dtype(cls, dtype: TBaseDType) -> Self:
         ------
         DataTypeValidationError
             If the input is not compatible with this data type.
+        ValueError
+            If the input is `numpy.dtypes.StringDType` and has `na_object` set.
         """
         if cls._check_native_dtype(dtype):
+            if hasattr(dtype, "na_object"):
+                msg = (
+                    f"Zarr data type resolution from {dtype} failed. "
+                    "Attempted to resolve a zarr data type from a `numpy.dtypes.StringDType` "
+                    "with `na_object` set, which is not supported."
+                )
+                raise ValueError(msg)
             return cls()
         raise DataTypeValidationError(
             f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
         )
 
+    def to_native_dtype(self) -> np.dtypes.StringDType:
+        """
+        Create a NumPy string dtype from this VariableLengthUTF8 ZDType.
+
+        Returns
+        -------
+        np.dtypes.StringDType
+            The NumPy string dtype.
+        """
+        return self.dtype_cls()
+
     @classmethod
     def _check_json_v2(
         cls,
@@ -719,109 +741,3 @@ def cast_scalar(self, data: object) -> str:
             f"data type {self}."
         )
         raise TypeError(msg)  # pragma: no cover
-
-
-if _NUMPY_SUPPORTS_VLEN_STRING:
-
-    @dataclass(frozen=True, kw_only=True)
-    class VariableLengthUTF8(UTF8Base[np.dtypes.StringDType]):  # type: ignore[type-var]
-        """
-        A Zarr data type for arrays containing variable-length UTF-8 strings.
-
-        Wraps the ``np.dtypes.StringDType`` data type. Scalars for this data type are instances
-        of ``str``.
-
-
-        Attributes
-        ----------
-        dtype_cls : Type[np.dtypes.StringDType]
-            The NumPy dtype class for this data type.
-        _zarr_v3_name : ClassVar[Literal["variable_length_utf8"]] = "variable_length_utf8"
-            The name of this data type in Zarr V3.
-        object_codec_id : ClassVar[Literal["vlen-utf8"]] = "vlen-utf8"
-            The object codec ID for this data type.
-        """
-
-        dtype_cls = np.dtypes.StringDType  # type: ignore[assignment]
-
-        @classmethod
-        def from_native_dtype(cls, dtype: TBaseDType) -> Self:
-            """
-            Create an instance of this data type from a compatible NumPy data type.
-            We reject NumPy StringDType instances that have the `na_object` field set,
-            because this is not representable by the Zarr `string` data type.
-
-            Parameters
-            ----------
-            dtype : TBaseDType
-                The native data type.
-
-            Returns
-            -------
-            Self
-                An instance of this data type.
-
-            Raises
-            ------
-            DataTypeValidationError
-                If the input is not compatible with this data type.
-            ValueError
-                If the input is `numpy.dtypes.StringDType` and has `na_object` set.
-            """
-            if cls._check_native_dtype(dtype):
-                if hasattr(dtype, "na_object"):
-                    msg = (
-                        f"Zarr data type resolution from {dtype} failed. "
-                        "Attempted to resolve a zarr data type from a `numpy.dtypes.StringDType` "
-                        "with `na_object` set, which is not supported."
-                    )
-                    raise ValueError(msg)
-                return cls()
-            raise DataTypeValidationError(
-                f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
-            )
-
-        def to_native_dtype(self) -> np.dtypes.StringDType:
-            """
-            Create a NumPy string dtype from this VariableLengthUTF8 ZDType.
-
-            Returns
-            -------
-            np.dtypes.StringDType
-                The NumPy string dtype.
-            """
-            return self.dtype_cls()
-
-else:
-    # Numpy pre-2 does not have a variable length string dtype, so we use the Object dtype instead.
-    @dataclass(frozen=True, kw_only=True)
-    class VariableLengthUTF8(UTF8Base[np.dtypes.ObjectDType]):  # type: ignore[no-redef]
-        """
-        A Zarr data type for arrays containing variable-length UTF-8 strings.
-
-        Wraps the ``np.dtypes.ObjectDType`` data type. Scalars for this data type are instances
-        of ``str``.
-
-
-        Attributes
-        ----------
-        dtype_cls : Type[np.dtypes.ObjectDType]
-            The NumPy dtype class for this data type.
-        _zarr_v3_name : ClassVar[Literal["variable_length_utf8"]] = "variable_length_utf8"
-            The name of this data type in Zarr V3.
-        object_codec_id : ClassVar[Literal["vlen-utf8"]] = "vlen-utf8"
-            The object codec ID for this data type.
-        """
-
-        dtype_cls = np.dtypes.ObjectDType
-
-        def to_native_dtype(self) -> np.dtypes.ObjectDType:
-            """
-            Create a NumPy object dtype from this VariableLengthUTF8 ZDType.
-
-            Returns
-            -------
-            np.dtypes.ObjectDType
-                The NumPy object dtype.
-            """
-            return self.dtype_cls()
diff --git a/tests/test_array.py b/tests/test_array.py
@@ -69,7 +69,6 @@
 )
 from zarr.core.dtype.common import ENDIANNESS_STR, EndiannessStr
 from zarr.core.dtype.npy.common import NUMPY_ENDIANNESS_STR, endianness_from_numpy_str
-from zarr.core.dtype.npy.string import UTF8Base
 from zarr.core.group import AsyncGroup
 from zarr.core.indexing import BasicIndexer, _iter_grid, _iter_regions
 from zarr.core.metadata.v2 import ArrayV2Metadata
@@ -1981,23 +1980,14 @@ def test_array_repr(store: Store) -> None:
     assert str(arr) == f"<Array {store} shape={shape} dtype={dtype}>"
 
 
-class UnknownObjectDtype(UTF8Base[np.dtypes.ObjectDType]):
-    object_codec_id = "unknown"  # type: ignore[assignment]
-
-    def to_native_dtype(self) -> np.dtypes.ObjectDType:
-        """
-        Create a NumPy object dtype from this VariableLengthUTF8 ZDType.
+class UnknownObjectCodecDtype(VariableLengthUTF8):
+    """A data type that requires an object codec with an unknown id, used for error-path tests."""
 
-        Returns
-        -------
-        np.dtypes.ObjectDType
-            The NumPy object dtype.
-        """
-        return np.dtype("o")  # type: ignore[return-value]
+    object_codec_id = "unknown"  # type: ignore[assignment]
 
 
 @pytest.mark.parametrize(
-    "dtype", [VariableLengthUTF8(), VariableLengthBytes(), UnknownObjectDtype()]
+    "dtype", [VariableLengthUTF8(), VariableLengthBytes(), UnknownObjectCodecDtype()]
 )
 def test_chunk_encoding_no_object_codec_errors(dtype: ZDType[Any, Any]) -> None:
     """
@@ -2024,7 +2014,7 @@ def test_unknown_object_codec_default_serializer_v3() -> None:
     Test that we get a valueerrror when trying to create the default serializer for a data type
     that requires an unknown object codec
     """
-    dtype = UnknownObjectDtype()
+    dtype = UnknownObjectCodecDtype()
     msg = f"Data type {dtype} requires an unknown object codec: {dtype.object_codec_id!r}."
     with pytest.raises(ValueError, match=re.escape(msg)):
         default_serializer_v3(dtype)
@@ -2035,7 +2025,7 @@ def test_unknown_object_codec_default_filters_v2() -> None:
     Test that we get a valueerrror when trying to create the default serializer for a data type
     that requires an unknown object codec
     """
-    dtype = UnknownObjectDtype()
+    dtype = UnknownObjectCodecDtype()
     msg = f"Data type {dtype} requires an unknown object codec: {dtype.object_codec_id!r}."
     with pytest.raises(ValueError, match=re.escape(msg)):
         default_filters_v2(dtype)
diff --git a/tests/test_codecs/test_vlen.py b/tests/test_codecs/test_vlen.py
@@ -10,17 +10,19 @@
 from zarr.codecs import ZstdCodec
 from zarr.codecs.vlen_utf8 import VLenBytesCodec, VLenUTF8Codec
 from zarr.core.dtype import get_data_type_from_native_dtype
-from zarr.core.dtype.npy.string import _NUMPY_SUPPORTS_VLEN_STRING
 from zarr.core.metadata.v3 import ArrayV3Metadata
 from zarr.storage import StorePath
 
-numpy_str_dtypes: list[type | str | None] = [None, str, "str", np.dtypes.StrDType, "S", "U"]
-expected_array_string_dtype: np.dtype[Any]
-if _NUMPY_SUPPORTS_VLEN_STRING:
-    numpy_str_dtypes.append(np.dtypes.StringDType)
-    expected_array_string_dtype = np.dtypes.StringDType()
-else:
-    expected_array_string_dtype = np.dtype("O")
+numpy_str_dtypes: list[type | str | None] = [
+    None,
+    str,
+    "str",
+    np.dtypes.StrDType,
+    "S",
+    "U",
+    np.dtypes.StringDType,
+]
+expected_array_string_dtype: np.dtype[Any] = np.dtypes.StringDType()
 
 
 @pytest.mark.filterwarnings("ignore::zarr.core.dtype.common.UnstableSpecificationWarning")
diff --git a/tests/test_dtype/test_npy/test_string.py b/tests/test_dtype/test_npy/test_string.py
diff --git a/tests/test_dtype_registry.py b/tests/test_dtype_registry.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Removed the NumPy 1.x implementation of the `VariableLengthUTF8` data type because NumPy 1.x is no longer supported under [SPEC0](https://scientific-python.org/specs/spec-0000/).