Steer users from BloscShuffle / BloscCname enum members toward the equivalent literal strings ("shuffle", "zstd", etc.) when constructing a BloscCodec. The enum classes remain importable, but accessing a member emits a DeprecationWarning. Internal storage of the codec, and the public cname / shuffle attributes, become literal strings.
- Removing the
BloscShuffle/BloscCnameclasses. Deletion is deferred to a future major release. - Other codecs that accept enum-style parameters (Zstd, etc.).
BloscCodec(cname="zstd", shuffle="bitshuffle")— preferred form, no warning.BloscCodec(cname=BloscCname.zstd)— works, but emitsDeprecationWarningfrom the enum-member access and from the codec init (the access warning fires first; the init normalization treats the resolved string the same as a direct string).from zarr.codecs import BloscShuffle, BloscCname— silent (no warning on import).BloscShuffle.shuffle(member access) —DeprecationWarning, returns the string"shuffle".codec.cname,codec.shuffle— returnstr(typed asCName/Shuffleliterals), not enum members.
In src/zarr/codecs/blosc.py, replace BloscShuffle(Enum) and BloscCname(Enum) with classes whose metaclass intercepts attribute access:
class _DeprecatedStrEnumMeta(type):
_members: dict[str, str]
def __getattr__(cls, name: str) -> str:
members = type.__getattribute__(cls, "_members")
if name in members:
warnings.warn(
f"{cls.__name__}.{name} is deprecated; pass the string "
f"{members[name]!r} instead.",
DeprecationWarning,
stacklevel=2,
)
return members[name]
raise AttributeError(name)
class BloscShuffle(metaclass=_DeprecatedStrEnumMeta):
_members = {"noshuffle": "noshuffle", "shuffle": "shuffle", "bitshuffle": "bitshuffle"}
@staticmethod
def from_int(num: int) -> Shuffle:
mapping = {0: "noshuffle", 1: "shuffle", 2: "bitshuffle"}
if num not in mapping:
raise ValueError(f"Value must be between 0 and 2. Got {num}.")
return mapping[num]
class BloscCname(metaclass=_DeprecatedStrEnumMeta):
_members = {
"lz4": "lz4", "lz4hc": "lz4hc", "blosclz": "blosclz",
"zstd": "zstd", "snappy": "snappy", "zlib": "zlib",
}Notes:
BloscShuffle.from_intis now a@staticmethodreturning astr(was a@classmethodreturning an enum member). The only internal caller ismigrate_v3._convert_compressor, which passes the result toBloscCodec(shuffle=...). That call site needs no change because the codec already accepts strings._membersis read viatype.__getattribute__to avoid recursing through__getattr__.- No warning fires on
from zarr.codecs import BloscShuffle— the class object is imported by name, not by member access.
The init signature stays type-compatible (still accepts BloscCname | CName and BloscShuffle | Shuffle | None). The body changes to:
- If
cnameorshuffleis anenum.Enuminstance, emitDeprecationWarning("Passing a {BloscCname,BloscShuffle} enum to BloscCodec is deprecated; pass a literal string instead.")and convert viavalue.value. (The newBloscShuffle/BloscCnameshims never produce an enum instance — member access already returns a string — so this branch primarily catches code that pickled or otherwise materialized a realenum.Enumfrom the old definition.) - Replace
parse_enum(cname, BloscCname)andparse_enum(shuffle, BloscShuffle)with explicit membership checks against theSHUFFLE/CNAMEtuples; raiseValueErrorlisting valid options on miss. - Internal stores:
typesize: int,cname: CName,clevel: int,shuffle: Shuffle,blocksize: int. Update class-level annotations and the dataclass field declarations.
to_dict: drop.value; emitself.cname/self.shuffledirectly.evolve_from_array_spec: use string literals"bitshuffle"/"shuffle"instead ofBloscShuffle.bitshuffle._blosc_codec: rebuild themap_shuffle_str_to_intmapping with string keys; rebuildcnamedirectly fromself.cname(no.nameneeded).- Update the docstring:
cname/shuffletyped as literal strings; remove the<BloscCname.zstd: 'zstd'>example output; drop or rephrase theSee Alsosection.
- src/zarr/metadata/migrate_v3.py: no change needed beyond confirming
BloscShuffle.from_int(...)still resolves. Withfrom_intas a staticmethod on the new class body, attribute access on the class itself goes through_DeprecatedStrEnumMeta.__getattr__, which only intercepts_memberskeys —from_intis on the class normally and is not deprecated. - Tests / docs that read
codec.cname.valueor compare against enum members must switch to string comparison.
In tests/test_codecs/test_blosc.py:
- Update
test_tunable_attrs_param:- The parametrized
BloscShuffle.shufflecase must wrap codec construction inpytest.warns(DeprecationWarning). - Assertions like
codec.shuffle == BloscShuffle.bitshufflebecomecodec.shuffle == "bitshuffle".
- The parametrized
- New test:
BloscShuffle.shuffleaccess raisesDeprecationWarningand returns"shuffle". Same forBloscCname.zstd. - New test:
BloscCodec(cname=BloscCname.zstd)triggersDeprecationWarningand produces a codec withcodec.cname == "zstd". - New test: importing the names is silent (
with warnings.catch_warnings(record=True)confirms no warning).
- docs/quick-start.md, docs/user-guide/arrays.md: replace each
zarr.codecs.BloscShuffle.<name>/BloscCname.<name>with the literal string. BloscCodecdocstring (in src/zarr/codecs/blosc.py): drop enum-typed parameter docs in favor of literal string docs; remove the<BloscShuffle.bitshuffle: 'bitshuffle'>example output line.
Add changes/<PR#>.removal.md containing one paragraph: "BloscShuffle and BloscCname enums are now deprecated. Pass the equivalent literal string (e.g. 'zstd', 'bitshuffle') when constructing BloscCodec. The enum classes remain importable but emit DeprecationWarning on member access; they will be removed in a future release." Use a placeholder filename like 0000.removal.md and let the PR-creator rename it.
- Type-check fallout for downstream code that annotates a variable as
BloscShuffleand assigns it tocodec.shuffle. After this changecodec.shuffle: strso static checkers will flag the mismatch. This is the desired migration nudge, but worth calling out in the changelog. isinstance(codec.shuffle, BloscShuffle)checks in downstream code will silently start returningFalse. Same intent — those callers need to migrate — but harder to discover than a type error.