ap-pure

Pure-stdlib Python implementation of Arash Partow's AP Hash Function (§08 of the General Hash Function Library, originally released 2002 under MIT).

The implementation is a bit-exact translation of the original C reference: identical inputs produce identical 32-bit unsigned hashes on every platform, with no I/O, no clock, and no random involvement.

Installation

pip install -e .

Requires Python ≥ 3.8. No runtime dependencies (pure stdlib). The only dev dependency is pytest.

Usage

from ap_pure import ap_hash

ap_hash(b"abc")                  # 633864072   (0x25C7FF88)
ap_hash(b"")                     # 2863311530  (0xAAAAAAAA)  — initial value
ap_hash(b"The quick brown fox…") # 2709835459  (0xA18CAEC3)

API:

def ap_hash(data: bytes) -> int: ...

• Input: bytes. Raises TypeError for str, int, None, bytearray, memoryview, etc. — bytes only.
• Output: 32-bit unsigned integer in [0, 0xFFFFFFFF].
• Side effects: none. Pure function.

To pass a bytearray explicitly, convert it first: ap_hash(bytes(b)).

Tests

pip install pytest
pytest -q

Currently 262 tests, all passing in <0.5s. Coverage spans the 13 canonical vectors from the spec, plus determinism, avalanche, type safety, edge cases, and a LOC-guard.

Algorithm

Bit-exact Python translation of:

unsigned int APHash(const char* str, unsigned int length)
{
   unsigned int hash = 0xAAAAAAAA;
   for (unsigned int i = 0; i < length; ++str, ++i)
      hash ^= ((i & 1) == 0)
                ? (  (hash <<  7) ^ (*str) * (hash >> 3))
                : (~((hash << 11) + ((*str) ^ (hash >> 5))));
   return hash;
}

See docs/CANONICAL_REFERENCE.md for the original C source and the full MIT notice.

License

• This implementation: CC0-1.0 (public domain).
• Original algorithm: MIT, © Arash Partow — preserved verbatim in docs/CANONICAL_REFERENCE.md per the MIT terms.

See LICENSE.

Limitations / non-goals

• Non-cryptographic. AP Hash is a general-purpose hash function intended for hash tables, Bloom-filter seeding, and similar applications. It is not suitable for security, integrity, or adversarial-input settings.
• Single function, single width. One function, one 32-bit output. No streaming variant, no class hierarchy, no CLI.
• No comparative benchmarks vs. mmh3, fnv, etc. — AP Hash is provided for users who want this specific algorithm.
• Determinism is contractual. The output of ap_hash(x) will match the C reference output of APHash(x, len(x)) for any byte string x, on any platform, forever.