Yet Another Murmurhash3 Binding 0.1.1 documentation

# Welcome to yammh3’s documentation!

Contents:

## Yet Another Murmurhash3 Binding

Python/Cython Murmurhash3 binding.

- Free software: MIT license
- Documentation: https://yammh3.readthedocs.org.

### 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.

## Usage

### In Python

To use the high-level functions in Python:

    from yammh3 import hash32, hash64, hash128

### In Cython

To use the low-level functions in Cython:

    from yammh3._yammh3 cimport mhash64, ...

Use `yammh3.get_include` to get the includes directory.

Note

Functions with `s` suffix return a signed integer.

## Installation

### Stable release

To install Yet Another Murmurhash3 Binding, run this command in your terminal:

    $ pip install yammh3

If you don’t have pip installed, this Python installation guide can guide you through the process.

### From sources

The sources for Yet Another Murmurhash3 Binding can be downloaded from the Github repo.

You can either clone the public repository:

    $ git clone git://github.com/rolando/yammh3

Or download the tarball:

    $ curl  -OL https://github.com/rolando/yammh3/tarball/master

Once you have a copy of the source, you can install it with:

    $ python setup.py install

## History

### 0.1.1 (2016-06-23)

- First usable release :)

### 0.1.0 (2016-06-17)

- First release on PyPI.

# Indices and tables

- Index
- Module Index