Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions .github/workflows/ci.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
3 changes: 3 additions & 0 deletions docs/release.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 4 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
203 changes: 203 additions & 0 deletions tests/test_codec_contract.py
Original file line number Diff line number Diff line change
@@ -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
25 changes: 25 additions & 0 deletions tests/typing/README.md
Original file line number Diff line number Diff line change
@@ -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.
Empty file added tests/typing/__init__.py
Empty file.
15 changes: 15 additions & 0 deletions tests/typing/mypy.ini
Original file line number Diff line number Diff line change
@@ -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
14 changes: 14 additions & 0 deletions tests/typing/pyrightconfig.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
{
"include": [
"."
],
"typeCheckingMode": "strict",
"pythonVersion": "3.12",
"extraPaths": [
"../../src"
],
"reportMissingTypeStubs": "none",
"reportUnknownVariableType": "none",
"reportUnknownMemberType": "none",
"reportUnknownArgumentType": "none"
}
31 changes: 31 additions & 0 deletions tests/typing/test_compat_types.py
Original file line number Diff line number Diff line change
@@ -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)
Loading