Restore zarr-python v2 compatibility in 0.16.x by re-exporting cbuffer_sizes / cbuffer_metainfo

[mkitti]

Summary

numcodecs 0.16.x (and main) cannot be imported by zarr-python v2. Importing zarr v2 fails immediately:

ImportError: cannot import name 'cbuffer_sizes' from 'numcodecs.blosc'. Did you mean: '_cbuffer_sizes'?

zarr-python v2 has already worked around this by capping its dependency: zarr 2.18.7 requires numcodecs!=0.14.0,!=0.14.1,<0.16,>=0.10.0. So today zarr v2 and numcodecs 0.16+ cannot be installed together at all.

This issue proposes a small shim that would let numcodecs 0.16.x / main remain importable by zarr v2 (so zarr-python could relax the <0.16 cap).

Root cause

zarr v2's zarr/util.py imports two functions from the Blosc extension:

# zarr/util.py:34 (zarr-python v2)
from numcodecs.blosc import cbuffer_sizes, cbuffer_metainfo

In #826 ("Migrate build system from setuptools to meson-python", commit 8b882dc) these were renamed to private names:

old (public, ≤0.15.x)	new (0.16.x / main)
numcodecs.blosc.cbuffer_sizes	numcodecs.blosc._cbuffer_sizes
numcodecs.blosc.cbuffer_metainfo	numcodecs.blosc._cbuffer_metainfo

Because zarr v2 imports the public names at module load time, the rename breaks import zarr outright.

Proposed fix (≈2 lines)

Re-export public aliases in src/numcodecs/blosc.pyx:

# Backwards-compatibility aliases for zarr-python v2, which imports these names.
cbuffer_sizes = _cbuffer_sizes
cbuffer_metainfo = _cbuffer_metainfo

Verification

Tested with numcodecs==0.16.5 + zarr==2.18.6 on Python 3.12:

• Before: import zarr raises the ImportError above.
• After monkeypatching the two aliases: import zarr succeeds, and round-tripping data through the numcodecs compressors (Blosc, Zstd, Zlib, GZip, BZ2) and filters (Delta, Quantize) via the zarr v2 array API all works. Every other symbol zarr v2 imports (numcodecs.abc, numcodecs.compat, numcodecs.registry, numcodecs.ndarray_like, the codec classes) already exists in 0.16.x.

Caveats / things to decide

1. Python floor. main raises requires-python to >=3.12 (and numpy>=2.0). zarr v2 still supports 3.11, so the combination would only be usable on 3.12+. The currently released 0.16.x keeps >=3.11.
2. numcodecs.tests.common moved. With the src/ + top-level tests/ layout, numcodecs.tests.common is no longer importable. Only zarr v2's own test suite imports it (greetings), not its runtime — so normal usage is unaffected, but zarr v2's tests would need a tweak.
3. Policy. Whether 0.16.x should commit to supporting zarr v2 (and whether zarr-python would then relax the <0.16 cap) is a maintainer decision. If desired, the shim is trivial and I'm happy to open a PR.

🤖 Generated with Claude Code