adds filters, serializer, compressors properties to Array

Author: normanrz

src/zarr/api/synchronous.py

@@ -802,7 +802,7 @@ def create_array(
         Use ``None`` to omit default filters.
     compressors : Iterable[Codec], optional
         List of compressors to apply to the array. Compressors are applied in order, and after any
-        filters are applied (if any are specified).
+        filters are applied (if any are specified) and the data is serialized into bytes.
 
         For Zarr v3, a "compressor" is a codec that takes a bytestrea, and
         returns another bytestream. Multiple compressors my be provided for Zarr v3.

src/zarr/core/_info.py

@@ -87,7 +87,7 @@ class ArrayInfo:
     _store_type: str
     _compressor: numcodecs.abc.Codec | None = None
     _filters: tuple[numcodecs.abc.Codec, ...] | None = None
-    _codecs: list[Codec] | None = None
+    _codecs: tuple[Codec, ...] | None = None
     _count_bytes: int | None = None
     _count_bytes_stored: int | None = None
     _count_chunks_initialized: int | None = None

src/zarr/core/array.py

@@ -20,6 +20,7 @@
 from warnings import warn
 
 import numcodecs
+import numcodecs.abc
 import numpy as np
 import numpy.typing as npt
 from typing_extensions import deprecated
@@ -911,6 +912,57 @@ def size(self) -> int:
         """
         return np.prod(self.metadata.shape).item()
 
+    @property
+    def filters(self) -> tuple[numcodecs.abc.Codec, ...] | tuple[ArrayArrayCodec, ...]:
+        """
+        Filters that are applied to each chunk of the array, in order, before serializing that
+        chunk to bytes.
+        """
+        if self.metadata.zarr_format == 2:
+            filters = self.metadata.filters
+            if filters is None:
+                return ()
+            return filters
+
+        return tuple(codec for codec in self.metadata.codecs if isinstance(codec, ArrayArrayCodec))
+
+    @property
+    def serializer(self) -> ArrayBytesCodec | None:
+        """
+        Array-to-bytes codec to use for serializing the chunks into bytes.
+        """
+        if self.metadata.zarr_format == 2:
+            return None
+
+        return next(codec for codec in self.metadata.codecs if isinstance(codec, ArrayBytesCodec))
+
+    @property
+    @deprecated("Use AsyncArray.compressors instead.")
+    def compressor(self) -> numcodecs.abc.Codec | None:
+        """
+        Compressor that is applied to each chunk of the array.
+
+        .. deprecated:: 3.0.0
+            `array.compressor` is deprecated and will be removed in a future release.
+            Use `array.compressors` instead.
+        """
+        if self.metadata.zarr_format == 2:
+            return self.metadata.compressor
+        raise TypeError("`compressor` is not available for Zarr format 3 arrays.")
+
+    @property
+    def compressors(self) -> tuple[numcodecs.abc.Codec, ...] | tuple[BytesBytesCodec, ...]:
+        """
+        Compressors that are applied to each chunk of the array. Compressors are applied in order, and after any
+        filters are applied (if any are specified) and the data is serialized into bytes.
+        """
+        if self.metadata.zarr_format == 2:
+            if self.metadata.compressor is not None:
+                return (self.metadata.compressor,)
+            return ()
+
+        return tuple(codec for codec in self.metadata.codecs if isinstance(codec, BytesBytesCodec))
+
     @property
     def dtype(self) -> np.dtype[Any]:
         """Returns the data type of the array.
@@ -1967,6 +2019,41 @@ def read_only(self) -> bool:
     def fill_value(self) -> Any:
         return self.metadata.fill_value
 
+    @property
+    def filters(self) -> tuple[numcodecs.abc.Codec, ...] | tuple[ArrayArrayCodec, ...]:
+        """
+        Filters that are applied to each chunk of the array, in order, before serializing that
+        chunk to bytes.
+        """
+        return self._async_array.filters
+
+    @property
+    def serializer(self) -> None | ArrayBytesCodec:
+        """
+        Array-to-bytes codec to use for serializing the chunks into bytes.
+        """
+        return self._async_array.serializer
+
+    @property
+    @deprecated("Use Array.compressors instead.")
+    def compressor(self) -> numcodecs.abc.Codec | None:
+        """
+        Compressor that is applied to each chunk of the array.
+
+        .. deprecated:: 3.0.0
+            `array.compressor` is deprecated and will be removed in a future release.
+            Use `array.compressors` instead.
+        """
+        return self._async_array.compressor
+
+    @property
+    def compressors(self) -> tuple[numcodecs.abc.Codec, ...] | tuple[BytesBytesCodec, ...]:
+        """
+        Compressors that are applied to each chunk of the array. Compressors are applied in order, and after any
+        filters are applied (if any are specified) and the data is serialized into bytes.
+        """
+        return self._async_array.compressors
+
     @property
     def cdata_shape(self) -> ChunkCoords:
         """
@@ -3710,7 +3797,7 @@ async def create_array(
         Use ``None`` to omit default filters.
     compressors : Iterable[Codec], optional
         List of compressors to apply to the array. Compressors are applied in order, and after any
-        filters are applied (if any are specified).
+        filters are applied (if any are specified) and the data is serialized into bytes.
 
         For Zarr v3, a "compressor" is a codec that takes a bytestrea, and
         returns another bytestream. Multiple compressors my be provided for Zarr v3.

src/zarr/core/group.py

@@ -1065,7 +1065,7 @@ async def create_array(
             Use ``None`` to omit default filters.
         compressors : Iterable[Codec], optional
             List of compressors to apply to the array. Compressors are applied in order, and after any
-            filters are applied (if any are specified).
+            filters are applied (if any are specified) and the data is serialized into bytes.
 
             For Zarr v3, a "compressor" is a codec that takes a bytestrea, and
             returns another bytestream. Multiple compressors my be provided for Zarr v3.
@@ -2321,7 +2321,7 @@ def create_array(
             Use ``None`` to omit default filters.
         compressors : Iterable[Codec], optional
             List of compressors to apply to the array. Compressors are applied in order, and after any
-            filters are applied (if any are specified).
+            filters are applied (if any are specified) and the data is serialized into bytes.
 
             For Zarr v3, a "compressor" is a codec that takes a bytestrea, and
             returns another bytestream. Multiple compressors my be provided for Zarr v3.
@@ -2710,7 +2710,7 @@ def array(
             Use ``None`` to omit default filters.
         compressors : Iterable[Codec], optional
             List of compressors to apply to the array. Compressors are applied in order, and after any
-            filters are applied (if any are specified).
+            filters are applied (if any are specified) and the data is serialized into bytes.
 
             For Zarr v3, a "compressor" is a codec that takes a bytestrea, and
             returns another bytestream. Multiple compressors my be provided for Zarr v3.

src/zarr/core/metadata/v3.py

@@ -254,7 +254,7 @@ def __init__(
             config=ArrayConfig.from_dict({}),  # TODO: config is not needed here.
             prototype=default_buffer_prototype(),  # TODO: prototype is not needed here.
         )
-        codecs_parsed = [c.evolve_from_array_spec(array_spec) for c in codecs_parsed_partial]
+        codecs_parsed = tuple(c.evolve_from_array_spec(array_spec) for c in codecs_parsed_partial)
         validate_codecs(codecs_parsed_partial, data_type_parsed)
 
         object.__setattr__(self, "shape", shape_parsed)

tests/test_array.py

@@ -510,9 +510,9 @@ def test_info_v3(self, chunks: tuple[int, int], shards: tuple[int, int] | None)
             _order="C",
             _read_only=False,
             _store_type="MemoryStore",
-            _codecs=[BytesCodec(), ZstdCodec()]
+            _codecs=(BytesCodec(), ZstdCodec())
             if shards is None
-            else [ShardingCodec(chunk_shape=chunks, codecs=[BytesCodec(), ZstdCodec()])],
+            else (ShardingCodec(chunk_shape=chunks, codecs=[BytesCodec(), ZstdCodec()]),),
             _count_bytes=512,
         )
         assert result == expected
@@ -536,7 +536,7 @@ def test_info_complete(self, chunks: tuple[int, int], shards: tuple[int, int] |
             _order="C",
             _read_only=False,
             _store_type="MemoryStore",
-            _codecs=[BytesCodec()] if shards is None else [ShardingCodec(chunk_shape=chunks)],
+            _codecs=(BytesCodec(),) if shards is None else (ShardingCodec(chunk_shape=chunks),),
             _count_bytes=512,
             _count_chunks_initialized=0,
             _count_bytes_stored=373 if shards is None else 578,  # the metadata?
@@ -596,9 +596,9 @@ async def test_info_v3_async(
             _order="C",
             _read_only=False,
             _store_type="MemoryStore",
-            _codecs=[BytesCodec(), ZstdCodec()]
+            _codecs=(BytesCodec(), ZstdCodec())
             if shards is None
-            else [ShardingCodec(chunk_shape=chunks, codecs=[BytesCodec(), ZstdCodec()])],
+            else (ShardingCodec(chunk_shape=chunks, codecs=[BytesCodec(), ZstdCodec()]),),
             _count_bytes=512,
         )
         assert result == expected
@@ -624,7 +624,7 @@ async def test_info_complete_async(
             _order="C",
             _read_only=False,
             _store_type="MemoryStore",
-            _codecs=[BytesCodec()] if shards is None else [ShardingCodec(chunk_shape=chunks)],
+            _codecs=(BytesCodec(),) if shards is None else (ShardingCodec(chunk_shape=chunks),),
             _count_bytes=512,
             _count_chunks_initialized=0,
             _count_bytes_stored=373 if shards is None else 578,  # the metadata?
@@ -839,7 +839,8 @@ def test_array_create_metadata_order_v2(
     arr = zarr.create_array(store=store, shape=(2, 2), order=order, zarr_format=2, dtype="i4")
 
     expected = order or zarr.config.get("array.order")
-    assert arr.metadata.order == expected  # type: ignore[union-attr]
+    assert arr.metadata.zarr_format == 2  # guard for mypy
+    assert arr.metadata.order == expected
 
 
 @pytest.mark.parametrize("order_config", ["C", "F", None])
@@ -1048,10 +1049,15 @@ async def test_create_array_no_filters_compressors(
         compressors=empty_value,
         filters=empty_value,
     )
+    # Test metadata explicitly
+    assert arr.metadata.zarr_format == 2  # guard for mypy
     # The v2 metadata stores None and () separately
-    assert arr.metadata.filters == empty_value  # type: ignore[union-attr]
+    assert arr.metadata.filters == empty_value
     # The v2 metadata does not allow tuple for compressor, therefore it is turned into None
-    assert arr.metadata.compressor is None  # type: ignore[union-attr]
+    assert arr.metadata.compressor is None
+
+    assert arr.filters == ()
+    assert arr.compressors == ()
 
     # v3
     arr = await create_array(
@@ -1061,10 +1067,13 @@ async def test_create_array_no_filters_compressors(
         compressors=empty_value,
         filters=empty_value,
     )
+    assert arr.metadata.zarr_format == 3  # guard for mypy
     if dtype == "str":
-        assert arr.metadata.codecs == [VLenUTF8Codec()]  # type: ignore[union-attr]
+        assert arr.metadata.codecs == (VLenUTF8Codec(),)
+        assert arr.serializer == VLenUTF8Codec()
     else:
-        assert arr.metadata.codecs == [BytesCodec()]  # type: ignore[union-attr]
+        assert arr.metadata.codecs == (BytesCodec(),)
+        assert arr.serializer == BytesCodec()
 
 
 @pytest.mark.parametrize("store", ["memory"], indirect=True)
@@ -1130,12 +1139,11 @@ async def test_create_array_v3_chunk_encoding(
         filters=filters,
         compressors=compressors,
     )
-    aa_codecs_expected, _, bb_codecs_expected = _parse_chunk_encoding_v3(
+    filters_expected, _, compressors_expected = _parse_chunk_encoding_v3(
         filters=filters, compressors=compressors, serializer="auto", dtype=np.dtype(dtype)
     )
-    # TODO: find a better way to get the filters / compressors from the array.
-    assert arr.codec_pipeline.array_array_codecs == aa_codecs_expected  # type: ignore[attr-defined]
-    assert arr.codec_pipeline.bytes_bytes_codecs == bb_codecs_expected  # type: ignore[attr-defined]
+    assert arr.filters == filters_expected
+    assert arr.compressors == compressors_expected
 
 
 @pytest.mark.parametrize("store", ["memory"], indirect=True)
@@ -1167,9 +1175,16 @@ async def test_create_array_v2_chunk_encoding(
     filters_expected, compressor_expected = _parse_chunk_encoding_v2(
         filters=filters, compressor=compressors, dtype=np.dtype(dtype)
     )
-    # TODO: find a better way to get the filters/compressor from the array.
-    assert arr.metadata.compressor == compressor_expected  # type: ignore[union-attr]
-    assert arr.metadata.filters == filters_expected  # type: ignore[union-attr]
+    assert arr.metadata.zarr_format == 2  # guard for mypy
+    assert arr.metadata.compressor == compressor_expected
+    assert arr.metadata.filters == filters_expected
+
+    # Normalize for property getters
+    compressor_expected = () if compressor_expected is None else (compressor_expected,)
+    filters_expected = () if filters_expected is None else filters_expected
+
+    assert arr.compressors == compressor_expected
+    assert arr.filters == filters_expected
 
 
 @pytest.mark.parametrize("store", ["memory"], indirect=True)
@@ -1185,12 +1200,12 @@ async def test_create_array_v3_default_filters_compressors(store: MemoryStore, d
         shape=(10,),
         zarr_format=3,
     )
-    expected_aa, expected_ab, expected_bb = _get_default_chunk_encoding_v3(np_dtype=np.dtype(dtype))
-    # TODO: define the codec pipeline class such that these fields are required, which will obviate the
-    # type ignore statements
-    assert arr.codec_pipeline.array_array_codecs == expected_aa  # type: ignore[attr-defined]
-    assert arr.codec_pipeline.bytes_bytes_codecs == expected_bb  # type: ignore[attr-defined]
-    assert arr.codec_pipeline.array_bytes_codec == expected_ab  # type: ignore[attr-defined]
+    expected_filters, expected_serializer, expected_compressors = _get_default_chunk_encoding_v3(
+        np_dtype=np.dtype(dtype)
+    )
+    assert arr.filters == expected_filters
+    assert arr.serializer == expected_serializer
+    assert arr.compressors == expected_compressors
 
 
 @pytest.mark.parametrize("store", ["memory"], indirect=True)
@@ -1209,8 +1224,15 @@ async def test_create_array_v2_default_filters_compressors(store: MemoryStore, d
     expected_filters, expected_compressors = _get_default_chunk_encoding_v2(
         np_dtype=np.dtype(dtype)
     )
-    assert arr.metadata.filters == expected_filters  # type: ignore[union-attr]
-    assert arr.metadata.compressor == expected_compressors  # type: ignore[union-attr]
+    assert arr.metadata.zarr_format == 2  # guard for mypy
+    assert arr.metadata.filters == expected_filters
+    assert arr.metadata.compressor == expected_compressors
+
+    # Normalize for property getters
+    expected_filters = () if expected_filters is None else expected_filters
+    expected_compressors = () if expected_compressors is None else (expected_compressors,)
+    assert arr.filters == expected_filters
+    assert arr.compressors == expected_compressors
 
 
 @pytest.mark.parametrize("store", ["memory"], indirect=True)

tests/test_info.py

@@ -59,7 +59,7 @@ def test_array_info(zarr_format: ZarrFormat) -> None:
         _order="C",
         _read_only=True,
         _store_type="MemoryStore",
-        _codecs=[BytesCodec()],
+        _codecs=(BytesCodec(),),
     )
     result = repr(info)
     assert result == textwrap.dedent(f"""\
@@ -71,7 +71,7 @@ def test_array_info(zarr_format: ZarrFormat) -> None:
         Order              : C
         Read-only          : True
         Store type         : MemoryStore
-        Codecs             : [{{'endian': <Endian.little: 'little'>}}]""")
+        Codecs             : ({{'endian': <Endian.little: 'little'>}},)""")
 
 
 @pytest.mark.parametrize("zarr_format", ZARR_FORMATS)
@@ -95,7 +95,7 @@ def test_array_info_complete(
         _order="C",
         _read_only=True,
         _store_type="MemoryStore",
-        _codecs=[BytesCodec()],
+        _codecs=(BytesCodec(),),
         _count_bytes=count_bytes,
         _count_bytes_stored=count_bytes_stored,
         _count_chunks_initialized=count_chunks_initialized,
@@ -110,7 +110,7 @@ def test_array_info_complete(
         Order              : C
         Read-only          : True
         Store type         : MemoryStore
-        Codecs             : [{{'endian': <Endian.little: 'little'>}}]
+        Codecs             : ({{'endian': <Endian.little: 'little'>}},)
         No. bytes          : {count_bytes} ({count_bytes_formatted})
         No. bytes stored   : {count_bytes_stored_formatted}
         Storage ratio      : {storage_ratio_formatted}