From ff36c016cebef004d4b896609a951daa854d24b8 Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Sat, 21 Nov 2026 13:48:18 +0100 Subject: [PATCH] test: check the Codec contract for every codec and add static type tests Add tests/test_codec_contract.py, which runs every registered codec through the behavior the Codec base class promises: encode and decode return buffers, decode(out=...) returns the caller's out, and get_config round-trips through from_config. Known violations are strict xfails, so fixing one forces its entry to be removed. Add tests/typing, where assert_type checks (verified by mypy and pyright in strict mode) sit next to runtime assertions (verified by pytest), and a `typing` CI job that runs both checkers plus the repository's own mypy configuration. The type checkers are pinned in a new `typing` dependency group. Assisted-by: ClaudeCode:claude-opus-5-5 --- .github/workflows/ci.yaml | 37 ++++++ docs/release.md | 3 + pyproject.toml | 4 + tests/test_codec_contract.py | 203 ++++++++++++++++++++++++++++++ tests/typing/README.md | 25 ++++ tests/typing/__init__.py | 0 tests/typing/mypy.ini | 15 +++ tests/typing/pyrightconfig.json | 14 +++ tests/typing/test_compat_types.py | 31 +++++ 9 files changed, 332 insertions(+) create mode 100644 tests/test_codec_contract.py create mode 100644 tests/typing/README.md create mode 100644 tests/typing/__init__.py create mode 100644 tests/typing/mypy.ini create mode 100644 tests/typing/pyrightconfig.json create mode 100644 tests/typing/test_compat_types.py diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 9f6583327..bec8fb69b 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -125,6 +125,43 @@ jobs: token: ${{ secrets.CODECOV_TOKEN }} verbose: true + typing: + # Static types: the repository's own mypy configuration over src and tests, and the + # strict type tests in tests/typing under both mypy and pyright (see its README). + runs-on: ubuntu-latest + + defaults: + run: + shell: bash -el {0} + + steps: + - name: Checkout source + uses: actions/checkout@v6 + with: + submodules: recursive + fetch-depth: 0 # required for version resolution + + - name: Set up Python + uses: actions/setup-python@v6 + with: + python-version: "3.13" + cache: 'pip' + + - name: Install numcodecs and the type checkers + run: | + python -m pip install --upgrade pip # --group needs pip >= 25.1 + python -m pip install -v ".[test,msgpack,crc32c]" + python -m pip install --group typing + + - name: mypy (repository configuration) + run: mypy --config-file pyproject.toml src tests + + - name: mypy (strict type tests) + run: mypy --config-file tests/typing/mypy.ini tests/typing + + - name: pyright (strict type tests) + run: pyright -p tests/typing + test-zarr: runs-on: ubuntu-latest strategy: diff --git a/docs/release.md b/docs/release.md index b54747679..6847e8ea6 100644 --- a/docs/release.md +++ b/docs/release.md @@ -29,6 +29,9 @@ wheels) rather than every branch, test the oldest supported and latest Zarr releases, use Alpine's numpy in the i386 job, and remove the unused release-notes labeler. +* Check the behavior every codec promises through `numcodecs.abc.Codec` in a new + `tests/test_codec_contract.py`, and add strict static type tests in `tests/typing`, run by + mypy and pyright in a new `typing` CI job. ### Fixes diff --git a/pyproject.toml b/pyproject.toml index f71320993..721d18125 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -90,6 +90,10 @@ dev = [ "pytest==9.0.3", "pytest-cov", ] +typing = [ + "mypy==2.4.1", + "pyright==1.1.414", +] test-zarr-313 = [ {include-group="dev"}, "zarr==3.1.3", diff --git a/tests/test_codec_contract.py b/tests/test_codec_contract.py new file mode 100644 index 000000000..c328a25cc --- /dev/null +++ b/tests/test_codec_contract.py @@ -0,0 +1,203 @@ +"""The behavior every codec promises through `numcodecs.abc.Codec`, checked for every codec. + +These tests pin down the contract that the type annotations on `Codec` describe: + +- `encode` and `decode` return a buffer-like object (one that exports the buffer protocol). +- `decode(buf, out=out)` writes into `out` and returns that same object. +- `get_config()` holds an `id` and JSON-serializable values, and `from_config` rebuilds an + equal codec from it once `id` is removed. +""" + +from __future__ import annotations + +import json +import warnings +from collections.abc import Callable +from dataclasses import dataclass + +import numpy as np +import pytest + +import numcodecs +from numcodecs import pickles +from numcodecs.abc import Codec + + +@dataclass(frozen=True) +class Case: + """A codec and an array it can round-trip.""" + + make: Callable[[], Codec] + data: np.ndarray + + @property + def is_object(self) -> bool: + return self.data.dtype == object + + +f8 = np.linspace(0, 100, 16, dtype="f8") +obj_str = np.array(["foo", "bar", "baz", "qux"], dtype=object) + +CASES: dict[str, Case] = { + "zlib": Case(lambda: numcodecs.Zlib(), f8), + "gzip": Case(lambda: numcodecs.GZip(), f8), + "bz2": Case(lambda: numcodecs.BZ2(), f8), + "lzma": Case(lambda: numcodecs.LZMA(), f8), + "blosc": Case(lambda: numcodecs.Blosc(), f8), + "zstd": Case(lambda: numcodecs.Zstd(), f8), + "lz4": Case(lambda: numcodecs.LZ4(), f8), + "base64": Case(lambda: numcodecs.Base64(), f8), + "shuffle": Case(lambda: numcodecs.Shuffle(elementsize=8), f8), + "crc32": Case(lambda: numcodecs.CRC32(), f8), + "adler32": Case(lambda: numcodecs.Adler32(), f8), + "jenkins_lookup3": Case(lambda: numcodecs.JenkinsLookup3(), f8), + "fletcher32": Case(lambda: numcodecs.Fletcher32(), f8), + "astype": Case(lambda: numcodecs.AsType(encode_dtype="f4", decode_dtype="f8"), f8), + "delta": Case(lambda: numcodecs.Delta(dtype="i4"), np.arange(16, dtype="i4")), + "quantize": Case(lambda: numcodecs.Quantize(digits=1, dtype="f8"), f8), + "fixedscaleoffset": Case( + lambda: numcodecs.FixedScaleOffset(offset=0, scale=10, dtype="f8", astype="i4"), f8 + ), + "bitround": Case(lambda: numcodecs.BitRound(keepbits=10), f8), + "packbits": Case(lambda: numcodecs.PackBits(), np.array([True, False] * 8)), + "categorize": Case( + lambda: numcodecs.Categorize(labels=["foo", "bar", "baz", "qux"], dtype=object), obj_str + ), + "pickle": Case(lambda: numcodecs.Pickle(), obj_str), + "json2": Case(lambda: numcodecs.JSON(), obj_str), + "vlen-utf8": Case(lambda: numcodecs.VLenUTF8(), obj_str), + "vlen-bytes": Case( + lambda: numcodecs.VLenBytes(), np.array([b"foo", b"bar", b"baz", b"qux"], dtype=object) + ), + "vlen-array": Case( + lambda: numcodecs.VLenArray(dtype="i4"), + np.array([np.arange(3, dtype="i4"), np.arange(2, dtype="i4")] * 2, dtype=object), + ), + "msgpack2": Case(lambda: numcodecs.MsgPack(), obj_str), + "zfpy": Case(lambda: numcodecs.ZFPY(), f8), + "pcodec": Case(lambda: numcodecs.PCodec(), f8), + "crc32c": Case(lambda: numcodecs.CRC32C(), f8), +} + +# Codecs whose decode(..., out=bytearray) cannot work, because the codec needs `out` to carry +# a dtype: PCodec decodes straight into a typed array. +NO_BYTEARRAY_OUT = frozenset({"pcodec"}) + +# Known violations of the `out` contract. Each entry is a bug; remove it when fixed. +# `strict=True` makes a fixed entry fail, so this list cannot go stale. +OUT_NDARRAY_XFAIL: set[str] = { + "zlib", + "bz2", + "lzma", + "base64", + "shuffle", + "zfpy", + "pcodec", + "vlen-utf8", + "vlen-bytes", + "vlen-array", +} +OUT_BYTEARRAY_XFAIL: set[str] = { + "zlib", + "bz2", + "lzma", + "base64", + "shuffle", + "crc32", + "adler32", + "crc32c", + "jenkins_lookup3", + "astype", + "delta", + "quantize", + "fixedscaleoffset", + "bitround", + "packbits", + "zfpy", +} +DECODE_RETURNS_BUFFER_XFAIL: set[str] = set() + + +def _codec(codec_id: str) -> Codec: + case = CASES[codec_id] + try: + with warnings.catch_warnings(): + warnings.simplefilter("ignore", DeprecationWarning) + return case.make() + except AttributeError: + pytest.skip(f"{codec_id} is not available (optional dependency missing)") + + +def _params( + xfail: set[str], *, skip: frozenset[str] = frozenset(), objects: bool = True +) -> list[object]: + params: list[object] = [] + for codec_id, case in CASES.items(): + if codec_id in skip or (case.is_object and not objects): + continue + marks = [pytest.mark.xfail(strict=True, reason="known bug")] if codec_id in xfail else [] + params.append(pytest.param(codec_id, marks=marks, id=codec_id)) + return params + + +@pytest.fixture(autouse=True) +def _allow_pickle(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setattr(pickles, "ALLOW_UNSAFE_PICKLE_DECODE", True) + + +def _is_buffer_like(obj: object) -> bool: + try: + memoryview(obj) # type: ignore[arg-type] + except TypeError: + return False + return True + + +def test_every_registered_codec_has_a_case() -> None: + """A new codec must be added to `CASES` so that the contract is checked for it.""" + assert set(numcodecs.registry.codec_registry) <= set(CASES) + + +@pytest.mark.parametrize("codec_id", _params(DECODE_RETURNS_BUFFER_XFAIL)) +def test_encode_decode_return_buffers(codec_id: str) -> None: + codec, data = _codec(codec_id), CASES[codec_id].data + enc = codec.encode(data) + assert _is_buffer_like(enc), type(enc) + dec = codec.decode(enc) + assert _is_buffer_like(dec), type(dec) + + +@pytest.mark.parametrize("codec_id", _params(OUT_NDARRAY_XFAIL)) +def test_decode_into_ndarray_returns_out(codec_id: str) -> None: + codec, data = _codec(codec_id), CASES[codec_id].data + enc = codec.encode(data) + expected = codec.decode(enc) + out = np.empty_like(data) + assert codec.decode(enc, out=out) is out + if CASES[codec_id].is_object: + assert all(np.array_equal(a, b) for a, b in zip(out, expected, strict=True)) + else: + assert np.asarray(memoryview(expected)).tobytes() == out.tobytes() + + +@pytest.mark.parametrize( + "codec_id", _params(OUT_BYTEARRAY_XFAIL, skip=NO_BYTEARRAY_OUT, objects=False) +) +def test_decode_into_bytearray_returns_out(codec_id: str) -> None: + codec, data = _codec(codec_id), CASES[codec_id].data + enc = codec.encode(data) + expected = codec.decode(enc) + out = bytearray(data.nbytes) + assert codec.decode(enc, out=out) is out + assert bytes(out) == np.asarray(memoryview(expected)).tobytes() + + +@pytest.mark.parametrize("codec_id", _params(set())) +def test_config_round_trip(codec_id: str) -> None: + codec = _codec(codec_id) + config = codec.get_config() + assert config["id"] == codec.codec_id + rebuilt_json = json.loads(json.dumps(config)) + assert numcodecs.get_codec(rebuilt_json) == codec + without_id = {k: v for k, v in config.items() if k != "id"} + assert type(codec).from_config(without_id) == codec diff --git a/tests/typing/README.md b/tests/typing/README.md new file mode 100644 index 000000000..a885a0967 --- /dev/null +++ b/tests/typing/README.md @@ -0,0 +1,25 @@ +# Static type tests + +The files here check numcodecs' type annotations against its runtime behavior. Each test +pairs `typing.assert_type`, which mypy and pyright check, with a runtime assertion, which +pytest checks. An annotation that type checkers accept but the runtime contradicts makes one +of the two fail. + +Run them from the repository root: + +```bash +uv pip install --group typing +pytest tests/typing +mypy --config-file tests/typing/mypy.ini tests/typing +pyright -p tests/typing +``` + +`mypy.ini` and `pyrightconfig.json` run both checkers in strict mode and read numcodecs from +`src/`. Errors inside numcodecs itself are not reported here: the repository's own mypy +configuration in `pyproject.toml` covers those. + +`pyrightconfig.json` turns off pyright's three `reportUnknown*` rules, because most numcodecs +parameters are not annotated yet. Turn them back on once they are. + +When you change an annotation in numcodecs, add or update an `assert_type` here that shows +what callers now get. diff --git a/tests/typing/__init__.py b/tests/typing/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/tests/typing/mypy.ini b/tests/typing/mypy.ini new file mode 100644 index 000000000..26579ad7e --- /dev/null +++ b/tests/typing/mypy.ini @@ -0,0 +1,15 @@ +# Strict mypy configuration for the static type tests in this directory. +# Run from the repository root: `mypy --config-file tests/typing/mypy.ini tests/typing` +[mypy] +strict = true +warn_unreachable = true +enable_error_code = ignore-without-code, redundant-expr, truthy-bool +# Read numcodecs from the source tree. It does not ship a py.typed marker yet, so mypy +# would otherwise refuse to analyze the installed copy. +mypy_path = src + +# Report errors in the tests only. numcodecs itself is checked by the repository's own +# configuration in pyproject.toml. +[mypy-numcodecs.*] +follow_imports = silent +ignore_errors = true diff --git a/tests/typing/pyrightconfig.json b/tests/typing/pyrightconfig.json new file mode 100644 index 000000000..42540aad6 --- /dev/null +++ b/tests/typing/pyrightconfig.json @@ -0,0 +1,14 @@ +{ + "include": [ + "." + ], + "typeCheckingMode": "strict", + "pythonVersion": "3.12", + "extraPaths": [ + "../../src" + ], + "reportMissingTypeStubs": "none", + "reportUnknownVariableType": "none", + "reportUnknownMemberType": "none", + "reportUnknownArgumentType": "none" +} diff --git a/tests/typing/test_compat_types.py b/tests/typing/test_compat_types.py new file mode 100644 index 000000000..f656c4111 --- /dev/null +++ b/tests/typing/test_compat_types.py @@ -0,0 +1,31 @@ +"""Static types of `numcodecs.compat`, checked against runtime behavior. + +Each `assert_type` is verified by mypy and pyright (see `tests/typing/README.md`), and the +`assert isinstance` next to it is verified by pytest. Together they keep the annotations +honest: a claim that type checkers accept but the runtime contradicts fails here. +""" + +from typing import Any, assert_type + +import numpy as np +import numpy.typing as npt + +from numcodecs.compat import ensure_bytes, ensure_contiguous_ndarray, ensure_ndarray + + +def test_ensure_bytes() -> None: + for buf in (b"abc", bytearray(b"abc"), memoryview(b"abc"), np.arange(3, dtype="u1")): + result = assert_type(ensure_bytes(buf), bytes) + assert isinstance(result, bytes) + + +def test_ensure_ndarray() -> None: + for buf in (b"abc", bytearray(b"abc"), memoryview(b"abc"), np.arange(3, dtype="u1")): + result = assert_type(ensure_ndarray(buf), npt.NDArray[Any]) + assert isinstance(result, np.ndarray) + + +def test_ensure_contiguous_ndarray() -> None: + for buf in (b"abc", bytearray(b"abc"), memoryview(b"abc"), np.arange(3, dtype="u1")): + result = assert_type(ensure_contiguous_ndarray(buf), npt.NDArray[Any]) + assert isinstance(result, np.ndarray)