deprecate blosc enums (zarr-developers#3963)

* docs(spec): deprecate BloscShuffle and BloscCname enums

Design for steering BloscCodec users toward literal-string parameters,
with the enum classes kept importable but deprecated on member access.

Canonical: https://gist.github.com/d-v-b/9fd3fe92f82a24c929129f42a6f11f60

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(codecs): deprecate BloscShuffle/BloscCname enums

Member access on BloscShuffle / BloscCname now emits DeprecationWarning
and returns the equivalent string. BloscCodec stores cname/shuffle as
literal strings; passing a real enum.Enum instance to __init__ warns.

BloscShuffle.from_int returns a str. Internal call sites in
migrate_v3 continue to work because BloscCodec accepts both forms.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: use literal strings for BloscCodec shuffle parameter

The BloscShuffle and BloscCname enums are deprecated; update doc
examples to the recommended literal-string form.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore(changes): add changelog entry for blosc enum deprecation

The 0000 filename is a placeholder; rename to the PR number when the
pull request is opened.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: drop local copy of blosc enum deprecation spec

The design doc is published as a public gist linked from the PR
description; the in-tree copy is no longer needed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* style(codecs): use plain backticks in blosc docstrings

Replace Sphinx :class: roles and double-backticks with single
backticks in the new docstrings added by the blosc enum deprecation.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test(codecs): cover blosc error branches

Add tests for the ValueError paths in _parse_cname / _parse_shuffle
and the AttributeError path in the deprecated-enum metaclass, which
codecov reported as uncovered. Drop a few "type: ignore" markers
that mypy now flags as unused after the init signature widened.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test(codecs): use typing.cast instead of type-ignore in blosc tests

mypy's per-file (pre-commit) and project-wide views disagree on
whether the deliberately-wrong arguments need a type ignore. Using
typing.cast keeps both views happy and is more explicit about what
each test is asserting.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor(codecs): rename blosc literal aliases to Blosc*Literal

Rename Shuffle -> BloscShuffleLiteral and CName -> BloscCnameLiteral.
The bare Shuffle name collided with numcodecs.Shuffle re-exported
from zarr.codecs, which would have caused mkdocstrings cross-refs in
the BloscCodec docstring to resolve to the wrong symbol. The Literal
suffix also clearly distinguishes the type alias from the deprecated
BloscShuffle / BloscCname enum classes.

Update the BloscCodec docstring to reference the new names in the
Attributes and Parameters sections (Convention A from cast_value.py),
with literal values enumerated in prose.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: rename blosc constants

* test(codecs): address review feedback on blosc deprecation tests

- Parametrize the BloscShuffle / BloscCname member-access warning tests
  into a single test_blosc_enum_member_access_warns.
- Parametrize the cname / shuffle reject-unknown tests into a single
  test_blosc_codec_rejects_unknown driven by **kwargs.
- Parametrize the AttributeError-on-unknown-member tests into a single
  test_blosc_enum_attribute_error_for_unknown_member.
- Add a docstring to every new test explaining what behavior it verifies,
  so reviewers don't have to read the body to understand the intent.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test(codecs): parametrize blosc cname/shuffle coverage and JSON roundtrip

Backfill missing coverage: previously every test in the blosc suite used
only "lz4" or "zstd" for cname and only "bitshuffle" or "shuffle" for
shuffle. Add four parametrized tests driven by BLOSC_CNAME / BLOSC_SHUFFLE:

- accepts_all_cnames / accepts_all_shuffles: every value in the runtime
  tuple is accepted by BloscCodec and round-trips on the stored attribute.
  Catches drift between the BloscCnameLiteral / BloscShuffleLiteral type
  aliases and their runtime BLOSC_* counterparts.
- json_roundtrip_all_cnames / json_roundtrip_all_shuffles: BloscCodec
  to_dict / from_dict preserves every value. Codec fields are fully
  specified so the test doesn't trip over tunable-attribute state, which
  is not part of the JSON form.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test(codecs): collapse blosc JSON roundtrip tests into one parametrize

Replace the cname/shuffle JSON-roundtrip pair with a single parametrized
test driven by [("cname", v) for v in BLOSC_CNAME] + [("shuffle", v) for
v in BLOSC_SHUFFLE]. They asserted the same property (to_dict / from_dict
preserves every literal) on two independent axes, so a single test
covers both with clear per-case IDs (e.g. cname-lz4, shuffle-bitshuffle).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test(codecs): cross-product blosc JSON roundtrip over cname x shuffle

Stacked parametrize over BLOSC_CNAME and BLOSC_SHUFFLE so the JSON
roundtrip exercises every (cname, shuffle) pair (18 cases instead of 9
in a disjoint union). Drops the **kwargs/dict[str, Any] indirection
the disjoint form needed, since the cross-product form passes typed
arguments directly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Rename 0000.removal.md to 3963.removal.md

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: d-v-b

changes/3963.removal.md

@@ -0,0 +1,6 @@
+The ``BloscShuffle`` and ``BloscCname`` enums (``zarr.codecs.BloscShuffle``,
+``zarr.codecs.BloscCname``) are now deprecated. Pass the equivalent literal
+string (e.g. ``"zstd"``, ``"bitshuffle"``) when constructing a ``BloscCodec``.
+The enum classes remain importable but emit ``DeprecationWarning`` on member
+access, and will be removed in a future release. ``BloscCodec.cname`` and
+``BloscCodec.shuffle`` are now plain strings rather than enum members.

docs/quick-start.md

@@ -58,7 +58,7 @@ z = zarr.create_array(
     compressors=zarr.codecs.BloscCodec(
         cname="zstd",
         clevel=3,
-        shuffle=zarr.codecs.BloscShuffle.shuffle
+        shuffle="shuffle"
     )
 )
 

docs/user-guide/arrays.md

@@ -201,7 +201,7 @@ Different compressors can be provided via the `compressors` keyword
 argument accepted by all array creation functions. For example:
 
 ```python exec="true" session="arrays" source="above" result="ansi"
-compressors = zarr.codecs.BloscCodec(cname='zstd', clevel=3, shuffle=zarr.codecs.BloscShuffle.bitshuffle)
+compressors = zarr.codecs.BloscCodec(cname='zstd', clevel=3, shuffle='bitshuffle')
 data = np.arange(100000000, dtype='int32').reshape(10000, 10000)
 z = zarr.create_array(store='data/example-5.zarr', shape=data.shape, dtype=data.dtype, chunks=(1000, 1000), compressors=compressors)
 z[:] = data
@@ -298,7 +298,7 @@ Here is an example using a delta filter with the Blosc compressor:
 from zarr.codecs.numcodecs import Delta
 
 filters = [Delta(dtype='int32')]
-compressors = zarr.codecs.BloscCodec(cname='zstd', clevel=1, shuffle=zarr.codecs.BloscShuffle.shuffle)
+compressors = zarr.codecs.BloscCodec(cname='zstd', clevel=1, shuffle='shuffle')
 data = np.arange(100000000, dtype='int32').reshape(10000, 10000)
 z = zarr.create_array(store='data/example-9.zarr', shape=data.shape, dtype=data.dtype, chunks=(1000, 1000), filters=filters, compressors=compressors)
 print(z.info_complete())

src/zarr/codecs/blosc.py

@@ -1,18 +1,19 @@
 from __future__ import annotations
 
 import asyncio
+import warnings
 from dataclasses import dataclass, field, replace
 from enum import Enum
 from functools import cached_property
-from typing import TYPE_CHECKING, Final, Literal, NotRequired, TypedDict
+from typing import TYPE_CHECKING, ClassVar, Final, Literal, NotRequired, TypedDict
 
 import numcodecs
 from numcodecs.blosc import Blosc
 from packaging.version import Version
 
 from zarr.abc.codec import BytesBytesCodec
 from zarr.core.buffer.cpu import as_numpy_array_wrapper
-from zarr.core.common import JSON, NamedRequiredConfig, parse_enum, parse_named_configuration
+from zarr.core.common import JSON, NamedRequiredConfig, parse_named_configuration
 from zarr.core.dtype.common import HasItemSize
 
 if TYPE_CHECKING:
@@ -21,19 +22,21 @@
     from zarr.core.array_spec import ArraySpec
     from zarr.core.buffer import Buffer
 
-Shuffle = Literal["noshuffle", "shuffle", "bitshuffle"]
+BloscShuffleLiteral = Literal["noshuffle", "shuffle", "bitshuffle"]
 """The shuffle values permitted for the blosc codec"""
 
-SHUFFLE: Final = ("noshuffle", "shuffle", "bitshuffle")
+BLOSC_SHUFFLE: Final = ("noshuffle", "shuffle", "bitshuffle")
 
-CName = Literal["lz4", "lz4hc", "blosclz", "snappy", "zlib", "zstd"]
-"""The codec identifiers used in the blosc codec """
+BloscCnameLiteral = Literal["lz4", "lz4hc", "blosclz", "snappy", "zlib", "zstd"]
+"""The codec identifiers used in the blosc codec"""
+
+BLOSC_CNAME: Final = ("lz4", "lz4hc", "blosclz", "snappy", "zlib", "zstd")
 
 
 class BloscConfigV2(TypedDict):
     """Configuration for the V2 Blosc codec"""
 
-    cname: CName
+    cname: BloscCnameLiteral
     clevel: int
     shuffle: int
     blocksize: int
@@ -43,9 +46,9 @@ class BloscConfigV2(TypedDict):
 class BloscConfigV3(TypedDict):
     """Configuration for the V3 Blosc codec"""
 
-    cname: CName
+    cname: BloscCnameLiteral
     clevel: int
-    shuffle: Shuffle
+    shuffle: BloscShuffleLiteral
     blocksize: int
     typesize: int
 
@@ -56,38 +59,66 @@ class BloscJSON_V3(NamedRequiredConfig[Literal["blosc"], BloscConfigV3]):
     """
 
 
-class BloscShuffle(Enum):
+class _DeprecatedStrEnumMeta(type):
     """
-    Enum for shuffle filter used by blosc.
+    Metaclass for the legacy `BloscShuffle` / `BloscCname` classes. Accessing
+    a member name (e.g. `BloscShuffle.bitshuffle`) emits a `DeprecationWarning`
+    and returns the equivalent string.
     """
 
-    noshuffle = "noshuffle"
-    shuffle = "shuffle"
-    bitshuffle = "bitshuffle"
+    _members: dict[str, str]
 
-    @classmethod
-    def from_int(cls, num: int) -> BloscShuffle:
-        blosc_shuffle_int_to_str = {
+    def __getattr__(cls, name: str) -> str:
+        members: dict[str, str] = type.__getattribute__(cls, "_members")
+        if name in members:
+            warnings.warn(
+                f"{cls.__name__}.{name} is deprecated; pass the string {members[name]!r} instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return members[name]
+        raise AttributeError(name)
+
+
+class BloscShuffle(metaclass=_DeprecatedStrEnumMeta):
+    """
+    Deprecated. Pass a literal string (`"noshuffle"`, `"shuffle"`, or
+    `"bitshuffle"`) directly to `BloscCodec` instead.
+    """
+
+    _members: ClassVar[dict[str, str]] = {
+        "noshuffle": "noshuffle",
+        "shuffle": "shuffle",
+        "bitshuffle": "bitshuffle",
+    }
+
+    @staticmethod
+    def from_int(num: int) -> BloscShuffleLiteral:
+        mapping: dict[int, BloscShuffleLiteral] = {
             0: "noshuffle",
             1: "shuffle",
             2: "bitshuffle",
         }
-        if num not in blosc_shuffle_int_to_str:
+        if num not in mapping:
             raise ValueError(f"Value must be between 0 and 2. Got {num}.")
-        return BloscShuffle[blosc_shuffle_int_to_str[num]]
+        return mapping[num]
 
 
-class BloscCname(Enum):
+class BloscCname(metaclass=_DeprecatedStrEnumMeta):
     """
-    Enum for compression library used by blosc.
+    Deprecated. Pass a literal string (one of `"lz4"`, `"lz4hc"`,
+    `"blosclz"`, `"snappy"`, `"zlib"`, `"zstd"`) directly to
+    `BloscCodec` instead.
     """
 
-    lz4 = "lz4"
-    lz4hc = "lz4hc"
-    blosclz = "blosclz"
-    zstd = "zstd"
-    snappy = "snappy"
-    zlib = "zlib"
+    _members: ClassVar[dict[str, str]] = {
+        "lz4": "lz4",
+        "lz4hc": "lz4hc",
+        "blosclz": "blosclz",
+        "snappy": "snappy",
+        "zstd": "zstd",
+        "zlib": "zlib",
+    }
 
 
 # See https://zarr.readthedocs.io/en/stable/user-guide/performance.html#configuring-blosc
@@ -118,6 +149,34 @@ def parse_blocksize(data: JSON) -> int:
     raise TypeError(f"Value should be an int. Got {type(data)} instead.")
 
 
+def _coerce_enum_input(value: object, param_name: str) -> object:
+    """
+    If `value` is a real `enum.Enum` instance, emit a deprecation warning
+    and return `value.value`. Otherwise return `value` unchanged.
+    """
+    if isinstance(value, Enum):
+        warnings.warn(
+            f"Passing an enum to BloscCodec(..., {param_name}=...) is deprecated; "
+            "pass the equivalent literal string instead.",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+        return value.value
+    return value
+
+
+def _parse_cname(data: object) -> BloscCnameLiteral:
+    if isinstance(data, str) and data in BLOSC_CNAME:
+        return data  # type: ignore[return-value]
+    raise ValueError(f"cname must be one of {list(BLOSC_CNAME)!r}. Got {data!r}.")
+
+
+def _parse_shuffle(data: object) -> BloscShuffleLiteral:
+    if isinstance(data, str) and data in BLOSC_SHUFFLE:
+        return data  # type: ignore[return-value]
+    raise ValueError(f"shuffle must be one of {list(BLOSC_SHUFFLE)!r}. Got {data!r}.")
+
+
 @dataclass(frozen=True)
 class BloscCodec(BytesBytesCodec):
     """
@@ -133,12 +192,14 @@ class BloscCodec(BytesBytesCodec):
         Always False for Blosc codec, as compression produces variable-sized output.
     typesize : int
         The data type size in bytes used for shuffle filtering.
-    cname : BloscCname
-        The compression algorithm being used (lz4, lz4hc, blosclz, snappy, zlib, or zstd).
+    cname : BloscCnameLiteral
+        The compression algorithm being used; one of "lz4", "lz4hc",
+        "blosclz", "snappy", "zlib", or "zstd".
     clevel : int
         The compression level (0-9).
-    shuffle : BloscShuffle
-        The shuffle filter mode (noshuffle, shuffle, or bitshuffle).
+    shuffle : BloscShuffleLiteral
+        The shuffle filter mode; one of "noshuffle", "shuffle", or
+        "bitshuffle".
     blocksize : int
         The size of compressed blocks in bytes (0 for automatic).
 
@@ -148,13 +209,16 @@ class BloscCodec(BytesBytesCodec):
         The data type size in bytes. This affects how the shuffle filter processes
         the data. If None, defaults to 1 and the attribute is marked as tunable.
         Default: 1.
-    cname : BloscCname or {'lz4', 'lz4hc', 'blosclz', 'snappy', 'zlib', 'zstd'}, optional
-        The compression algorithm to use. Default: 'zstd'.
+    cname : BloscCnameLiteral, optional
+        The compression algorithm to use; one of "lz4", "lz4hc", "blosclz",
+        "snappy", "zlib", or "zstd". Default is "zstd". Passing a `BloscCname`
+        enum is deprecated.
     clevel : int, optional
         The compression level, from 0 (no compression) to 9 (maximum compression).
         Higher values provide better compression at the cost of speed. Default: 5.
-    shuffle : BloscShuffle or {'noshuffle', 'shuffle', 'bitshuffle'}, optional
-        The shuffle filter to apply before compression:
+    shuffle : BloscShuffleLiteral or None, optional
+        The shuffle filter to apply before compression; one of "noshuffle",
+        "shuffle", or "bitshuffle":
 
         - 'noshuffle': No shuffling
         - 'shuffle': Byte shuffling (better for typesize > 1)
@@ -183,57 +247,51 @@ class BloscCodec(BytesBytesCodec):
     >>> codec.typesize
     1
     >>> codec.shuffle
-    <BloscShuffle.bitshuffle: 'bitshuffle'>
+    'bitshuffle'
 
     Create a codec with specific compression settings:
 
     >>> codec = BloscCodec(cname='zstd', clevel=9, shuffle='shuffle')
     >>> codec.cname
-    <BloscCname.zstd: 'zstd'>
-
-    See Also
-    --------
-    BloscShuffle : Enum for shuffle filter options
-    BloscCname : Enum for compression algorithm options
+    'zstd'
     """
 
     # This attribute tracks parameters were set to None at init time, and thus tunable
     _tunable_attrs: set[Literal["typesize", "shuffle"]] = field(init=False)
     is_fixed_size = False
 
     typesize: int
-    cname: BloscCname
+    cname: BloscCnameLiteral
     clevel: int
-    shuffle: BloscShuffle
+    shuffle: BloscShuffleLiteral
     blocksize: int
 
     def __init__(
         self,
         *,
         typesize: int | None = None,
-        cname: BloscCname | CName = BloscCname.zstd,
+        cname: BloscCname | BloscCnameLiteral = "zstd",
         clevel: int = 5,
-        shuffle: BloscShuffle | Shuffle | None = None,
+        shuffle: BloscShuffle | BloscShuffleLiteral | None = None,
         blocksize: int = 0,
     ) -> None:
         object.__setattr__(self, "_tunable_attrs", set())
 
-        # If typesize was set to None, replace it with a valid typesize
-        # and flag the typesize attribute as safe to replace later
         if typesize is None:
             typesize = 1
             self._tunable_attrs.update({"typesize"})
 
-        # If shuffle was set to None, replace it with a valid shuffle
-        # and flag the shuffle attribute as safe to replace later
         if shuffle is None:
-            shuffle = BloscShuffle.bitshuffle
+            shuffle = "bitshuffle"
             self._tunable_attrs.update({"shuffle"})
 
+        cname = _coerce_enum_input(cname, "cname")  # type: ignore[assignment]
+        shuffle = _coerce_enum_input(shuffle, "shuffle")  # type: ignore[assignment]
+
         typesize_parsed = parse_typesize(typesize)
-        cname_parsed = parse_enum(cname, BloscCname)
+        cname_parsed = _parse_cname(cname)
         clevel_parsed = parse_clevel(clevel)
-        shuffle_parsed = parse_enum(shuffle, BloscShuffle)
+        shuffle_parsed = _parse_shuffle(shuffle)
         blocksize_parsed = parse_blocksize(blocksize)
 
         object.__setattr__(self, "typesize", typesize_parsed)
@@ -252,9 +310,9 @@ def to_dict(self) -> dict[str, JSON]:
             "name": "blosc",
             "configuration": {
                 "typesize": self.typesize,
-                "cname": self.cname.value,
+                "cname": self.cname,
                 "clevel": self.clevel,
-                "shuffle": self.shuffle.value,
+                "shuffle": self.shuffle,
                 "blocksize": self.blocksize,
             },
         }
@@ -276,20 +334,20 @@ def evolve_from_array_spec(self, array_spec: ArraySpec) -> Self:
         if "shuffle" in self._tunable_attrs:
             new_codec = replace(
                 new_codec,
-                shuffle=(BloscShuffle.bitshuffle if item_size == 1 else BloscShuffle.shuffle),
+                shuffle=("bitshuffle" if item_size == 1 else "shuffle"),
             )
 
         return new_codec
 
     @cached_property
     def _blosc_codec(self) -> Blosc:
-        map_shuffle_str_to_int = {
-            BloscShuffle.noshuffle: 0,
-            BloscShuffle.shuffle: 1,
-            BloscShuffle.bitshuffle: 2,
+        map_shuffle_str_to_int: dict[BloscShuffleLiteral, int] = {
+            "noshuffle": 0,
+            "shuffle": 1,
+            "bitshuffle": 2,
         }
         config_dict: BloscConfigV2 = {
-            "cname": self.cname.name,  # type: ignore[typeddict-item]
+            "cname": self.cname,
             "clevel": self.clevel,
             "shuffle": map_shuffle_str_to_int[self.shuffle],
             "blocksize": self.blocksize,