Skip to content

rmax/yammh3

Repository files navigation

Yet Another Murmurhash3 Binding

Documentation Status

Python/Cython Murmurhash3 binding.

Features

  • Provides a high-level Python API.
  • Provides a low-level Cython binding.
  • Python 2 and 3 support.

Example

Here is an example in Python:

from yammh3 import hash64

key = b"yammh3!"

# hash* functions return a signed integer by default.
print("signed 64 bits hash is %s" % hash64(key))  # -> -1339990020854215562
print("unsigned 64 bits hash is %s" % hash64(key, signed=False))  # -> 17106754052855336054L

In Cython, first we need to write a .pyx file with our code:

# file: yammh3_example.pyx
# mhash* functions are only available via cimport.
from yammh3._yammh3 cimport mhash64, mhash64s
from yammh3._yammh3 cimport int64_t, uint64_t, uint32_t

def print_hashes(bytes key):
    cdef uint64_t h1
    cdef int64_t h2
    cdef uint32_t n = len(key)
    cdef char *c_key = <char *>key

    with nogil:  # releasing the GIL!
        h1 = mhash64(c_key, n)
        h2 = mhash64s(c_key, n)

    print("unsigned 64 bits hash is %d" % h1)
    print("signed 64 bits hash is %d" % h2)

We need to compile it as a module, usually by using a setup script:

# file: setup.py
from setuptools import setup
from setuptools.extension import Extension
from Cython.Build import cythonize

import yammh3  # already installed

setup(
    name='yammh3-example',
    ext_modules=cythonize([
        Extension('*', ['*.pyx'], include_dirs=[yammh3.get_include()]),
    ])
)

Then we build the modules in-place:

$ python setup.py build_ext --inplace
Running build_ext
building 'yammh3_example' extension
... [snip] ...
copying build/lib.macosx-10.5-x86_64-2.7/yammh3_example.so ->

Now we are ready to run our code:

$ python -c 'import yammh3_example; yammh3_example.print_hashes(b"yammh3!")'
unsigned 64 bits hash is 17106754052855336054
signed 64 bits hash is -1339990020854215562

Credits

Murmurhash3 was originally created by Austin Appleby.

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.