Metadata-Version: 2.4
Name: jump-consistent-hash
Version: 3.6.0
Summary: Implementation of the Jump Consistent Hash algorithm
Keywords: jump,consistent,hash,jumphash,algorithm
Author-Email: Peter Lithammer <peter.lithammer@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: Free Threading :: 2 - Beta
Project-URL: Source, https://github.com/lithammer/python-jump-consistent-hash
Project-URL: Issues, https://github.com/lithammer/python-jump-consistent-hash/issues
Project-URL: Changelog, https://github.com/lithammer/python-jump-consistent-hash/releases
Project-URL: Documentation, https://github.com/lithammer/python-jump-consistent-hash#readme
Requires-Python: >=3.10
Description-Content-Type: text/x-rst

Jump Consistent Hash
--------------------

.. image:: https://github.com/lithammer/python-jump-consistent-hash/workflows/Python/badge.svg
   :alt: Build Status
   :target: https://github.com/lithammer/python-jump-consistent-hash/actions

Python and C implementation of the jump consistent hash algorithm by John
Lamping and Eric Veach[1]. Tested on Python 3.10+.

Install
-------

To install Jump Consistent Hash, simply run this simple command in your
terminal of choice::

   $ pip install jump-consistent-hash

The C implementation is optional but is about 10x faster than the pure Python
implementation in CPython.

Usage
`````

.. code:: python

   >>> import jump
   >>> jump.hash(256, 1024)
   520

If you want to use a ``str`` as a key instead of an ``int``, you can pass it
through a hash function to compute a real key. Here's a couple of examples
using Python 3:

.. code:: python

   >>> import hashlib
   >>> int(hashlib.md5(b"127.0.0.1").hexdigest(), 16)
   325870950296970981340734819828239218902

   >>> int(hashlib.sha1(b"127.0.0.1").hexdigest(), 16)
   431133456357828263809343936597625557575256328153

   >>> import binascii
   >>> binascii.crc32(b"127.0.0.1") & 0xffffffff
   3619153832

Do not reach for the built-in ``hash()`` here. Python salts the hashes of
``str`` objects with a seed chosen per process, so the same key lands in a
different bucket after every restart and in every worker of a pool, which is
the opposite of what consistent hashing is for. The functions above are stable
across processes and machines.

Links
`````

[1] http://arxiv.org/pdf/1406.2294v1.pdf
