Metadata-Version: 2.4
Name: fnv-c
Version: 0.3.0
Summary: Python 3.10+ FNV (fnv0, fnv1, fnv1a) non-cryptographic hash library implemented in C through libffi
Author-email: Fabien MARTY <fabien.marty@botify.com>
License: MIT License
        
        Copyright (c) 2023 Fabien MARTY
        Copyright (c) 2023 Botify and contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/botify-labs/fnv-c
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cffi>=1.0.0
Dynamic: license-file

# fnv-c

[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/botify-labs/fnv-c/ci.yaml)](https://github.com/botify-labs/fnv-c/actions/workflows/ci.yaml)
[![pypi badge](https://img.shields.io/pypi/v/fnv-c?color=brightgreen)](https://pypi.org/project/fnv-c/)

## What is it?

**fnv-c** is a Python 3.7+ FNV (`fnv0`, `fnv1`, `fnv1a`) **non-cryptographic** hash library implemented in C through libffi.

FNV ("Fowler–Noll–Vo") is is a non-cryptographic hash function created by Glenn Fowler, Landon Curt Noll, and Kiem-Phong.
FNV is probably not the "best" non-cryptographic hash function but:

- it has a reasonably good distribution
- it's very fast
- it's very easy to implement *(even in some exotic stored procedures for example)* so you can use it everywhere

More details on [this Wikepedia article](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function).

## Features

- speed: 
    - up to **800 MB/s** hashing speed *(on Macbook Pro M1 (2020) with `fnv0_64`)*
    - **6 800%** faster than basic Python implementation, **70%** faster than `pyhash` *(when hashing 100 bytes with `fnv0_64` on a cloud VM)*
- portability:
    - tested with recent Python versions (3.7+)
    - compatible with ARM64
    - compatible (and tested) with PyPy

## Non features

- other hash algorithms *(this library is only about FNV algorithm)*
- too agressive CPU optimizations *(we prefer maximizing binary portability)*

## Benchmark

You have a benchmark script [here](bench.py) to bench `fnv-c` by yourself and to compare it with:
- [`fnvhash`](https://github.com/znerol/py-fnvhash) (pure python implementation)
- [`pyhash`](https://github.com/flier/pyfasthash) (more general hashing library with C++ extension)

### Comparisons with other libraries (`fnv0_64` on a cloud VM)

Differences with `fnvhash` are huge (from **35%** for one byte hashing to **19 000%** for 1 000 bytes hashing with `fnv0_64`)

Differences with `pyhash` (on `fnv0_64`) are shown with the following diagram:

![](bench.png)

### Influence of string size on `fnv-c` hashing speed (on a Macbook Pro M1 (2020) with `fnv0_64`)

![](bench2.png)

## How to install/use it?

```
pip install fnv-c
```

```python
import fnv_c

print(fnv_c.fnv0_32(b"foo bar"))
print(fnv_c.fnv0_64(b"foo bar"))
print(fnv_c.fnv1_32(b"foo bar"))
print(fnv_c.fnv1_64(b"foo bar"))
print(fnv_c.fnv1a_32(b"foo bar"))
print(fnv_c.fnv1a_64(b"foo bar"))
```

## Function signatures / API

Full API doc is available at: [https://botify-labs.github.io/fnv-c/fnv_c/](https://botify-labs.github.io/fnv-c/fnv_c/)

## Contributing

See [CONTRIBUTING](./CONTRIBUTING.md)

## License

**fnv-c** is licensed under the [MIT license](./LICENSE).
