Python reference implementation of matrix256v1 — a SHA-256 fingerprint over the (path, size) records of a rooted filesystem tree.
Zero runtime dependencies — stdlib only, Python 3.10+. One of several language implementations of the same normative spec; every implementation must produce byte-identical digests on the same input.
The project's only dev dependency is ruff (declared under [dependency-groups.dev] in pyproject.toml) — used to enforce the library discipline below. Dev deps are not installed when consumers pip install matrix256 or uv add matrix256; they only land in a contributor's environment via uv sync --group dev.
The library promise is: a consumer's process must never break because of code in this package. The rules below are enforced by ruff (CI runs uv run ruff check . on every push); a few rows are intent rules that still require code review.
| Category | What's guarded | Enforced by |
|---|---|---|
| Exception discipline | No assert in library code (stripped under python -O), no bare except:, no sys.exit. Failures raise specific, typed exceptions — OSError from filesystem calls is propagated unchanged per spec §3. |
S101, E722, BLE001, TID251 (banned-api on sys.exit) |
| Output discipline | No print(...), no logging configuration, no writes to sys.stdout / sys.stderr from library code. A fingerprint call has no business producing output. |
T201, T203 (in T20); logging/direct sys.stdout writes are intent rules |
| Total functions | Where reasonable, public functions are made total by construction. _utf8_encode substitutes U+FFFD for any lone surrogate so no caller can hand it a string that triggers UnicodeEncodeError. |
code review |
| Side effects at import | No top-level work beyond imports and the VERSION constant. Importing the package never touches the filesystem, the network, or os.environ. |
code review |
| Documentation | Every public class and function carries a """...""" docstring. Public API stays self-describing. |
D100–D104 |
Tests under tests/ are exempt via [tool.ruff.lint.per-file-ignores] — they use assert, print, and sys.exit freely, as Python's testing idiom expects.
uv sync --group dev # install ruff into a contributor venv
uv run ruff check . # run the discipline checks
from matrix256 import v1
digest = v1.fingerprint("/media/user/DISC")The package exposes nothing at the top level. Future algorithm versions will be added as sibling submodules (matrix256.v2, …) so callers always address an explicit version.
This implementation's Tier-1 conformance test is the synthetic fixture suite at tests/generate_fixtures.py. The script constructs each fixture in a temporary directory, runs matrix256.v1.fingerprint against it, and verifies the produced digest against the canonical value published in the spec repo's conformance_fixtures.json (human-readable companion: CONFORMANCE_FIXTURES.md). The suite has no external data dependency and runs on every commit in CI.
python tests/generate_fixtures.py # run all fixtures
python tests/generate_fixtures.py --fixture 14 # one fixture
python tests/generate_fixtures.py --range 1-10 # a range
python tests/generate_fixtures.py --generate # emit JSON for the spec repo
By default the runner expects the spec repo to be cloned alongside this one as ../matrix256/. Override with --fixtures PATH. Platform-incompatible fixtures (e.g. case-sensitive sort on a case-insensitive filesystem, surrogate-escape paths off Linux) are reported as skips rather than failures.
The script doubles as the canonical fixture generator: implementers in other languages should mirror its construction logic in their own runner so all language implementations agree on the on-disk state under test.
See also (in the spec repo)
SPEC.md— normative algorithmRATIONALE.md— design rationaleIMPLEMENTERS.md— practical guidance (encoding, mount handling, bridge discs)CORPUS.md— known-good digests across real discsCONFORMANCE_FIXTURES.md/conformance_fixtures.json— Tier-1 synthetic fixture suite
Licensed under the Apache License, Version 2.0. Apache 2.0 grants an explicit patent license to users and includes a patent-retaliation clause that terminates those rights for anyone who sues a contributor over the licensed work.