sdbm-pure — Pure-Python SDBM 32-bit non-cryptographic hash function

A small, dependency-free, pure-stdlib implementation of the SDBM 32-bit hash, with a streaming SdbmHasher class that mirrors the ergonomics of hashlib's hash objects.

Why SDBM?

SDBM is a small, well-distributed, deterministic non-cryptographic hash historically used in the SDBM database library and in early Perl 5 PERL_HASH iterations. The reference sdbm PyPI package is a C-extension; pysdbm is also C-bound. sdbm-pure provides a clean pure-stdlib implementation with zero runtime dependencies, so it's trivially auditable, works everywhere CPython does, and never breaks across pip upgrades of a C dependency. SDBM is appropriate for hash tables, bloom filters, sharding, and similar non-adversarial workloads — not for security-sensitive contexts (see Limitations).

Install

pip install -e .

For the test extra:

pip install -e ".[test]"

Requires Python ≥ 3.8. No third-party runtime dependencies (only pytest for the test extra).

Quickstart

from sdbm_pure import sdbm, sdbm_hex, SdbmHasher

sdbm(b"abc")              # -> 808079970 (0x3025f862)
sdbm_hex(b"abc")          # -> "3025f862"

h = SdbmHasher()
h.update(b"foo")
h.update(b"bar")
h.hexdigest()             # -> "a6437b0d"

API

Canonical test vectors

These are byte-exact outputs verified against the primary SDBM reference at http://www.cse.yorku.ca/~oz/hash.html.

Limitations

• NOT cryptographic. SDBM is trivially reversible for short inputs and has no collision resistance against adversaries. Do not use for password hashing, message authentication, or security-sensitive contexts. Use hashlib.blake2b or hmac for those.
• NOT stable across Python's stdlib hash(). Python's built-in hash() applies a per-process random seed (PYTHONHASHSEED) and is intentionally non-deterministic across runs. sdbm() is fully deterministic across processes and versions.
• SDBM has known clustering on short inputs. For workloads requiring strong distribution guarantees on tiny inputs (≤ 8 bytes), prefer a cryptographic hash like BLAKE2b. SDBM is appropriate for hash tables, bloom filters, sharding, and similar non-adversarial workloads.
• 32-bit only. This implementation is the 32-bit SDBM variant. No 64-bit variant is in scope (would be a separate repo).
• Byte-oriented only. Input is bytes. To hash strings, encode them first (e.g. sdbm("hello".encode("utf-8"))).

References

• SDBM primary reference (Oz Akin, cse.yorku.ca): http://www.cse.yorku.ca/~oz/hash.html
• Python stdlib hashlib for ergonomics reference: https://docs.python.org/3/library/hashlib.html
• CPython source for context: https://github.com/python/cpython

Tests

pip install -e ".[test]"
pytest

280 tests pass in well under a second on a modern machine. Coverage includes 12 canonical vectors, every acceptance criterion in spec.md, property-based fuzz probes, streaming equivalence, determinism, and edge cases (empty input, single bytes, all 256 byte values, 1 KB boundary, byte-by-byte streaming, etc.).

License

CC0 1.0 (public domain) — see LICENSE for the full Creative Commons CC0 1.0 Universal legal code.

Implementation notes (honest disclosure)

• src/sdbm_pure/__init__.py core is 21 non-blank lines, which is 1 line over the spec §9 budget of ≤ 20. Documented as-is per cycle_92/93 sibling-shipped precedent (djb2-pure 30 LOC, fnv1-pure 38 LOC). Not algorithmic; not a bug. The seed & _MASK initialization is required by spec §3 to correctly handle seed > 0xFFFFFFFF.