Skip to content

Commit c112fb1

Browse files
committed
add hh-python 1.0.0: the python implementation with the golden vectors of hh-cpp v1.0.0
0 parents  commit c112fb1

69 files changed

Lines changed: 6743 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.editorconfig‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# EditorConfig: https://editorconfig.org/
2+
3+
root = true
4+
5+
[*]
6+
charset = utf-8
7+
end_of_line = lf
8+
indent_style = space
9+
indent_size = 4
10+
trim_trailing_whitespace = true
11+
insert_final_newline = true
12+
max_line_length = 100
13+
14+
[*.{yml,yaml,json}]
15+
indent_size = 2
16+
17+
# Two trailing spaces are a hard line break in Markdown.
18+
[*.md]
19+
trim_trailing_whitespace = false
20+
21+
# Golden vectors are tab-separated and copied byte for byte from hh-cpp.
22+
[testdata/**]
23+
indent_style = unset
24+
indent_size = unset
25+
trim_trailing_whitespace = false
26+
insert_final_newline = unset
27+
max_line_length = unset

‎.gitattributes‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Line endings are fixed so checkouts are identical on every platform.
2+
* text=auto eol=lf
3+
4+
# Golden vectors are a byte-identical copy of hh-cpp; git must never rewrite them.
5+
testdata/** -text
6+
7+
# The hand-made batch cases hold bytes that are not text, and CR LF line ends on purpose.
8+
tools/edge-cases.txt -text
9+
*.png binary

‎.github/workflows/ci.yml‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
name: ci
2+
3+
on: [push, pull_request]
4+
5+
permissions:
6+
contents: read
7+
8+
jobs:
9+
test:
10+
strategy:
11+
fail-fast: false
12+
matrix:
13+
os: [ubuntu-latest]
14+
python: ["3.10", "3.11", "3.12", "3.13", "3.14", "pypy-3.10"]
15+
include:
16+
# CPython 3.9 is built for the runner images up to Ubuntu 24.04.
17+
- { os: ubuntu-24.04, python: "3.9" }
18+
- { os: macos-latest, python: "3.10" }
19+
- { os: macos-latest, python: "3.14" }
20+
- { os: windows-latest, python: "3.9" }
21+
- { os: windows-latest, python: "3.14" }
22+
runs-on: ${{ matrix.os }}
23+
steps:
24+
- uses: actions/checkout@v7
25+
- uses: actions/setup-python@v7
26+
with:
27+
python-version: ${{ matrix.python }}
28+
- name: Test the source tree, warnings are errors
29+
run: python -W error -X dev -m unittest discover -s tests -t .
30+
31+
# The source distribution and the wheel build, the wheel holds the package only, and the
32+
# tests of the source distribution pass against the installed wheel.
33+
package:
34+
runs-on: ubuntu-latest
35+
steps:
36+
- uses: actions/checkout@v7
37+
- uses: actions/setup-python@v7
38+
with:
39+
python-version: "3.13"
40+
- name: Build
41+
run: |
42+
python -m pip install build
43+
python -m build
44+
- name: The wheel holds the package only, the source distribution the tests and the vectors
45+
run: |
46+
python - <<'PY'
47+
import glob, tarfile, zipfile
48+
(wheel,) = glob.glob("dist/*.whl")
49+
names = zipfile.ZipFile(wheel).namelist()
50+
assert all(n.startswith(("humanized_hash/", "humanized_hash-")) for n in names), names
51+
assert "humanized_hash/py.typed" in names
52+
(sdist,) = glob.glob("dist/*.tar.gz")
53+
members = {n.split("/", 1)[1] for n in tarfile.open(sdist).getnames() if "/" in n}
54+
for needed in ("LICENSE", "testdata/SOURCE", "testdata/vectors.tsv",
55+
"testdata/golden/sampler-universal-128.png", "tests/test_vectors.py",
56+
"tools/crosscheck.sh", "tools/edge-cases.txt", "docs/INTEGRATION.md",
57+
"CHANGELOG.md"):
58+
assert needed in members, needed
59+
PY
60+
- name: Install the wheel into a clean environment and test it
61+
run: |
62+
python -m venv /tmp/clean
63+
/tmp/clean/bin/pip install dist/*.whl
64+
mkdir /tmp/sdist && tar -xzf dist/*.tar.gz -C /tmp/sdist --strip-components=1
65+
cd /tmp/sdist && rm -rf src
66+
HH_TEST_INSTALLED=1 /tmp/clean/bin/python -W error -X dev -m unittest discover -s tests -t .
67+
/tmp/clean/bin/humanized-hash 0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed \
68+
--out /tmp/address.png
69+
cmp /tmp/address.png testdata/golden/evm-1-universal-128.png
70+
71+
# testdata/ must be the vectors of the hh-cpp release that testdata/SOURCE names.
72+
provenance:
73+
runs-on: ubuntu-latest
74+
steps:
75+
- uses: actions/checkout@v7
76+
- name: Read testdata/SOURCE
77+
id: source
78+
run: |
79+
echo "tag=$(sed -n 's/^tag: //p' testdata/SOURCE)" >> "$GITHUB_OUTPUT"
80+
echo "commit=$(sed -n 's/^commit: //p' testdata/SOURCE)" >> "$GITHUB_OUTPUT"
81+
- uses: actions/checkout@v7
82+
with:
83+
repository: censync/hh-cpp
84+
ref: ${{ steps.source.outputs.tag }}
85+
path: hh-cpp
86+
- name: The tag is the recorded commit
87+
run: test "$(git -C hh-cpp rev-parse HEAD)" = "${{ steps.source.outputs.commit }}"
88+
- name: The copy is byte-identical
89+
run: |
90+
diff -r -x SOURCE hh-cpp/testdata testdata
91+
(cd testdata && grep -E '^[0-9a-f]{64} ' SOURCE | sha256sum --check --quiet)
92+
93+
# Pseudo-random and hand-made cases beyond the vector set, against hh_cli built from the same
94+
# release, on the oldest supported Python.
95+
differential:
96+
runs-on: ubuntu-24.04
97+
steps:
98+
- uses: actions/checkout@v7
99+
- uses: actions/setup-python@v7
100+
with:
101+
python-version: "3.9"
102+
- name: Read testdata/SOURCE
103+
id: source
104+
run: |
105+
echo "tag=$(sed -n 's/^tag: //p' testdata/SOURCE)" >> "$GITHUB_OUTPUT"
106+
- uses: actions/checkout@v7
107+
with:
108+
repository: censync/hh-cpp
109+
ref: ${{ steps.source.outputs.tag }}
110+
path: hh-cpp
111+
- name: Build hh_cli
112+
run: |
113+
cmake -S hh-cpp -B hh-cpp/build -DCMAKE_BUILD_TYPE=Release -DHH_BUILD_TESTS=OFF
114+
cmake --build hh-cpp/build --parallel --target hh_cli
115+
- name: Crosscheck
116+
run: |
117+
PYTHON=python tools/crosscheck.sh hh-cpp/build/examples/hh_cli 2000 1
118+
PYTHON=python tools/crosscheck.sh hh-cpp/build/examples/hh_cli 2000 2

‎.gitignore‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Python build state
2+
__pycache__/
3+
*.py[cod]
4+
build/
5+
dist/
6+
*.egg-info/
7+
.eggs/
8+
9+
# Virtual environments and tool caches
10+
.venv/
11+
venv/
12+
.tox/
13+
.mypy_cache/
14+
.pytest_cache/
15+
.ruff_cache/
16+
.coverage
17+
htmlcov/
18+
19+
# Editors and local tooling
20+
.idea/
21+
.vscode/
22+
*.swp
23+
.DS_Store

‎CHANGELOG.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Changelog
2+
3+
All notable changes to this project are documented here. The format follows
4+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to
5+
[Semantic Versioning](https://semver.org/spec/v2.0.0.html). Each release names the hh-cpp release
6+
its golden vectors were copied from. The algorithm itself is frozen and has no version: no
7+
release changes a fingerprint, a pixel or an encoded byte.
8+
9+
## [1.0.0] - 2026-09-21
10+
11+
The first release. Golden vectors: hh-cpp v1.0.0.
12+
13+
### Added
14+
15+
- Public API in `humanized_hash` (type hints, `py.typed`, docstrings): `BaseDigest.of`, `of_hex`
16+
and `of_text` compute the base digest of bytes, hexadecimal or text, and `from_bytes` restores
17+
a stored one; `SecretKey`, a context manager that wipes its copy of the key, with `closed` and
18+
a key check value that stays readable after the key is closed; universal and keyed
19+
`Fingerprint` with layout and six-character tag, and `from_bytes` for a fingerprint computed
20+
elsewhere; `RenderOptions` with square and round shapes, keyed-mode frame markers, any
21+
background colour and transparency, frame transparency and a WCAG contrast measure; `Image`
22+
with RGBA pixels, PNG, BMP and JPEG encoders and `save`. `HhError`, a `ValueError`, carries the
23+
`ErrorCode` of the specification; arguments of the wrong type raise `TypeError`. Values are
24+
immutable, hashable and picklable with every protocol; a key is neither picklable nor
25+
printable, and neither is the buffer that holds it.
26+
- A rasteriser that evaluates whole rows of samples as integer bit sets, exact to the per-sample
27+
definition of the specification; fixed-Huffman deflate, PNG, BMP and a baseline JPEG encoder
28+
written in the library; Adler-32; PBKDF2 over `hashlib.sha256` for interpreters without
29+
OpenSSL. SHA-256, HMAC, PBKDF2 and CRC-32 come from the standard library. No dependencies;
30+
integer arithmetic only.
31+
- The command `humanized-hash` (`python -m humanized_hash`) with the options of `hh_cli` of
32+
hh-cpp, and with `--batch`, which follows the batch format of `hh_cli` to the letter, and
33+
`--generate` for differential tests.
34+
- Tests with `unittest`: known-answer tests (FIPS 180-4, RFC 4231, RFC 7914, CRC-32 and Adler-32
35+
check values); the golden vectors and golden files of hh-cpp; the rasteriser against a
36+
per-sample transcription of the specification for every size from 16 to 96 and samples up to
37+
1024; the deflate stream against a literal transcription of its matching rule; decoders for
38+
PNG (`zlib`), BMP and baseline JPEG; error order, API and robustness tests; source rules
39+
(no floating point, standard library only, documented API).
40+
- `tools/crosscheck.sh`: differential test against `hh_cli` of hh-cpp with pseudo-random cases
41+
and the hand-made cases of `tools/edge-cases.txt`. `tools/update-vectors.sh` copies the vectors
42+
and writes `testdata/SOURCE`. `tools/bench.py` times every step.
43+
- Packaging with setuptools: `humanized-hash` on PyPI, CPython 3.9 to 3.14 and PyPy 3.10; the
44+
source distribution carries the tests and the vectors, the wheel the package only.
45+
46+
[1.0.0]: https://github.com/censync/hh-python/releases/tag/v1.0.0

‎CONTRIBUTING.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Contributing to hh-python
2+
3+
hh-python is the Python implementation of Humanized Hash (`hh`). The C++17 repository hh-cpp is
4+
the reference: it owns `docs/SPEC.md`, `docs/SECURITY.md` and the canonical golden vectors. This
5+
repository carries a byte-identical copy of the vectors in `testdata/` and records the hh-cpp
6+
release and the file hashes in `testdata/SOURCE`. The port follows `SPEC.md`, not the C++ source.
7+
8+
Bug reports and patches are welcome: open an issue or a pull request. Security problems are
9+
reported privately, as `docs/SECURITY.md` of hh-cpp describes.
10+
11+
## The algorithm is frozen
12+
13+
Output is byte-identical with hh-cpp. A mismatch against the vectors is a bug here, never a reason
14+
to change the vectors. The algorithm has no version and never changes; what the specification
15+
leaves open (API shape, error texts, performance) may evolve under SemVer.
16+
17+
hh is a standalone library. Nothing here names a particular host application.
18+
19+
## Dependencies and license
20+
21+
- `dependencies = []`. The package imports the standard library only, and of it only what every
22+
build has: `hashlib`, `hmac`, `binascii`, `struct`, `math.isqrt` and the like. It does not import
23+
`zlib`, which is optional in CPython builds: deflate, Adler-32, PNG, BMP, the JPEG encoder and
24+
the rasteriser are written here. SHA-256, HMAC, PBKDF2 and CRC-32 are the standard library's.
25+
- No third-party packages anywhere, including the tests and the tools. Tests use `unittest` only;
26+
they may cross-check against `zlib` and may use floating point to measure error.
27+
- The build backend is setuptools; `build` is the only package needed to make a release. No
28+
linter, formatter or type checker is required to work on the code, and none is configured.
29+
- License: MIT (`LICENSE`); contributions are accepted under it.
30+
31+
## Style
32+
33+
- Everything is English: code, comments, docstrings, documentation, commit messages. No emoji.
34+
- PEP 8 with 100 columns, double quotes, type hints on every function, a docstring on every
35+
public object. Public names live in `humanized_hash/__init__.py` and `__all__`; every other
36+
module starts with an underscore.
37+
- Python 3.9 is the oldest supported version: `from __future__ import annotations` in every
38+
module, `typing.Optional` and `typing.Union` where an annotation is evaluated at run time, no
39+
`match`, no `int.bit_count`, no `zip(strict=...)`.
40+
- Comments explain the code and cite the section of the specification or the standard
41+
(RFC 1951, ITU-T T.81).
42+
43+
## Library rules (src/humanized_hash)
44+
45+
- Integer arithmetic only: no `float`, no `/`, no `round`, nothing from `math` but `isqrt`.
46+
Python integers are unbounded; mask where the specification works modulo 2^32.
47+
- Invalid values raise `HhError` (a `ValueError`) with the `ErrorCode` of the specification, in
48+
the order of checks the specification gives; arguments of the wrong type raise `TypeError`.
49+
- Buffers that held key material are overwritten before release, as far as Python allows; the
50+
documentation says where it does not.
51+
- A faster path must equal the per-sample definition exactly. `tests/reference.py` is that
52+
definition; `tests/test_raster.py` compares the two.
53+
- `tests/test_package.py` enforces the rules that a program can check.
54+
55+
## Build and test
56+
57+
- `python -m unittest discover -s tests -t .` runs every test against the source tree; it must
58+
pass with `python -W error -X dev` on every supported version. `HH_TEST_INSTALLED=1` tests the
59+
installed package instead, `HH_TESTDATA_DIR` points at the vectors.
60+
- `tools/crosscheck.sh <hh_cli>` runs the differential test against hh-cpp: generated cases and
61+
the hand-made cases of `tools/edge-cases.txt`, a file of bytes that every implementation
62+
carries in the same copy; `python tools/bench.py` times every step. The tools may use floating
63+
point, the library never.
64+
- `tools/update-vectors.sh <hh-cpp checkout>` refreshes `testdata/` and `testdata/SOURCE`; never
65+
edit those files by hand.
66+
- `python -m build` makes the source distribution and the wheel. The version lives in
67+
`src/humanized_hash/_version.py` and nowhere else.
68+
69+
## Commits
70+
71+
Atomic, imperative, lower case, for example "add the baseline jpeg encoder". Every commit passes
72+
the tests.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Dmitry Mandrika
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎MANIFEST.in‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# The source distribution carries everything needed to test it: the tests, the golden vectors of
2+
# hh-cpp, the tools and the documentation. The wheel holds the package only.
3+
include CHANGELOG.md CONTRIBUTING.md
4+
graft docs
5+
graft testdata
6+
recursive-include tests *.py
7+
recursive-include tools *.sh *.py *.txt

0 commit comments

Comments
 (0)