Metadata-Version: 2.4
Name: ap-pure
Version: 0.1.0
Summary: Pure-stdlib Python implementation of Arash Partow AP Hash Function
License: CC0-1.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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

```bash
pip install -e .
```

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

## Usage

```python
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:

```python
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

```bash
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:

```c
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.
