Package: mmh3
mmh3mmh3 is a Python extension forMurmurHash (MurmurHash3), a set of fast and robust non-cryptographic hash functions invented by Austin Appleby.Combined with probabilistic techniques like aBloom filter,MinHash, andfeature hashing, mmh3 allows you to develop high-performance systems in fields such as data mining, machine learning, and natural language processing.Another common use of mmh3 is tocalculate favicon hashesused byShodan, the world's first IoT search engine.How to useInstallpipinstallmmh3# for macOS, use "pip3 install mmh3" and python3Simple functionsQuickstart:>>>importmmh3
>>>mmh3.hash("foo")# returns a 32-bit signed int-156908512
>>>mmh3.hash("foo",42)# uses 42 as a seed-1322301282
>>>mmh3.hash("foo",signed=False)# returns a 32-bit unsigned int4138058784Other functions:>>>mmh3.hash64("foo")# two 64 bit signed ints (by using the 128-bit algorithm as its backend)(-2129773440516405919,9128664383759220103)>>>mmh3.hash64("foo",signed=False)#  two 64 bit unsigned ints(16316970633193145697,9128664383759220103)>>>mmh3.hash128("foo",42)# 128 bit unsigned int215966891540331383248189432718888555506>>>mmh3.hash128("foo",42,signed=True)# 128 bit signed int-124315475380607080215185174712879655950
>>>mmh3.hash_bytes("foo")# 128 bit value as bytes'aE\xf5\x01W\x86q\xe2\x87}\xba+\xe4\x87\xaf~'>>>importnumpyasnp
>>>a=np.zeros(2**32,dtype=np.int8)>>>mmh3.hash_bytes(a)b'V\x8f}\xad\x8eNM\xa84\x07FU\x9c\xc4\xcc\x8e'Beware thathash64returnstwovalues, because it uses the 128-bit version of MurmurHash3 as its backend.hash_from_bufferhashes byte-likes without memory copying. The method is suitable when you hash a large memory-view such asnumpy.ndarray.>>>mmh3.hash_from_buffer(numpy.random.rand(100))-2137204694
>>>mmh3.hash_from_buffer(numpy.random.rand(100),signed=False)3812874078hash64,hash128, andhash_byteshave the third argument for architecture optimization (keyword arg:x64arch). Use True for x64 and False for x86 (default: True):>>>mmh3.hash64("foo",42,True)(-840311307571801102,-6739155424061121879)hashlib-style hashersmmh3implements hashers whose interfaces are similar tohashlibin the standard library:mmh3_32()for 32 bit hashing,mmh3_x64_128()for 128 bit hashing optimized for x64 architectures, andmmh3_x86_128()for 128 bit hashing optimized for x86 architectures.In addition to the standarddigest()method, each hasher hassintdigest(), which returns a signed integer, anduintdigest(), which returns an unsigned integer. 128 bit hashers also havestupledigest()andutupledigest()which return two 64 bit integers.Note that as of version 4.1.0, the implementation is still experimental and its performance can be unsatisfactory (especiallymmh3_x86_128()). Also,hexdigest()is not supported. Usedigest().hex()instead.>>>importmmh3
>>>hasher=mmh3.mmh3_x64_128(seed=42)>>>hasher.update(b"foo")>>>hasher.update(b"bar")>>>hasher.update("foo")# str inputs are not allowed for hashersTypeError:Stringsmustbeencodedbeforehashing
Traceback(mostrecentcalllast):File"<stdin>",line1,in<module>
>>>hasher.digest()b'\x82_n\xdd \xac\xb6j\xef\x99\xb1e\xc4\n\xc9\xfd'>>>hasher.sintdigest()# 128 bit signed int-2943813934500665152301506963178627198
>>>hasher.uintdigest()# 128 bit unsigned int337338552986437798311073100468589584258>>>hasher.stupledigest()# two 64 bit signed ints(7689522670935629698,-159584473158936081)>>>hasher.utupledigest()# two 64 bit unsigned ints(7689522670935629698,18287159600550615535)Changelog4.1.0 (2024-01-09)Add support for Python 3.12.Change the project structure to fix issues when using Bazel (https://github.com/hajimes/mmh3/issues/50).Fix incorrect type hints (https://github.com/hajimes/mmh3/issues/51).Fix invalid results on s390x when the argx64archofhash64orhash_bytesis set toFalse(https://github.com/hajimes/mmh3/issues/52).4.0.1 (2023-07-14)Fix incorrect type hints.Refactor the project structure (https://github.com/hajimes/mmh3/issues/48).4.0.0 (2023-05-22)Add experimental support forhashlib-compliant hasher classes (https://github.com/hajimes/mmh3/issues/39). Note that they are not yet fully tuned for performance.Add support for type hints (https://github.com/hajimes/mmh3/issues/44).Add wheels for more platforms (musllinux,s390x,win_arm64, andmacosx_universal2).Drop support for Python 3.7, as it will reach the end of life on 2023-06-27.Switch license from CC0 to MIT (https://github.com/hajimes/mmh3/issues/43).Add a code of conduct (the ACM Code of Ethics and Professional Conduct).Backward incompatible changes:A hash function now returns the same value under big-endian platforms as that under little-endian ones (https://github.com/hajimes/mmh3/issues/47).Remove the__version__constant from the module (https://github.com/hajimes/mmh3/issues/42). Useimportlib.metadatainstead.SeeCHANGELOG.mdfor the complete changelog.LicenseMIT, unless otherwise noted within a file.Known IssuesGetting different results from other MurmurHash3-based librariesBy default, mmh3 returnssignedvalues for 32-bit and 64-bit versions andunsignedvalues forhash128, due to historical reasons. Please use the keyword argumentsignedto obtain a desired result.From version 4.0.0,mmh3returns the same value under big-endian platforms
as that under little-endian ones, while the original C++ library is endian-sensitive. If you need to obtain the original-compliant results under big-endian environments, please use version 3.*.For compatibility withGoogle Guava (Java), seehttps://stackoverflow.com/questions/29932956/murmur3-hash-different-result-between-python-and-java-implementation.For compatibility withmurmur3 (Go), seehttps://github.com/hajimes/mmh3/issues/46.Unexpected results when given non 32-bit seedsVersion 2.4 changed the type of seeds from signed 32-bit int to unsigned 32-bit int. The resulting values with signed seeds still remain the same as before, as long as they are 32-bit.>>>mmh3.hash("aaaa",-1756908916)# signed representation for 0x9747b28c1519878282>>>mmh3.hash("aaaa",2538058380)# unsigned representation for 0x9747b28c1519878282Be careful so that these seeds do not exceed 32-bit. Unexpected results may happen with invalid values.>>>mmh3.hash("foo",2**33)-156908512
>>>mmh3.hash("foo",2**34)-156908512Contributing GuidelinesSeeCONTRIBUTING.md.AuthorsMurmurHash3 was originally developed by Austin Appleby and distributed under public domainhttps://github.com/aappleby/smhasher.Ported and modified for Python by Hajime Senuma.See alsoTutorials (High-Performance Computing)The following textbooks and tutorials are great sources to learn how to use mmh3 (and other hash algorithms in general) for high-performance computing.Chapter 11:Using Less Ramin Micha Gorelick and Ian Ozsvald. 2014.High Performance Python: Practical Performant Programming for Humans. O'Reilly Media.ISBN: 978-1-4493-6159-4.2nd edition of the above (2020).ISBN: 978-1492055020.Max Burstein. February 2, 2013.Creating a Simple Bloom Filter.Duke University. April 14, 2016.Efficient storage of data in memory.Bugra Akyildiz. August 24, 2016.A Gentle Introduction to Bloom Filter. KDnuggets.Tutorials (Internet of Things)Shodan, the world's firstIoTsearch engine, uses MurmurHash3 hash values forfavicons(icons associated with web pages).ZoomEyefollows Shodan's convention.Calculating these values with mmh3is useful for OSINT and cybersecurity activities.Jan Kopriva. April 19, 2021.Hunting phishing websites with favicon hashes. SANS Internet Storm Center.Nikhil Panwar. May 2, 2022.Using Favicons to Discover Phishing & Brand Impersonation Websites. Bolster.Faradaysec. July 25, 2022.Understanding Spring4Shell: How used is it?. Faraday Security.Debjeet. August 2, 2022.How To Find Assets Using Favicon Hashes. Payatu.Similar librarieshttps://github.com/wc-duck/pymmh3: mmh3 in pure python (Fredrik Kihlander and Swapnil Gusani)https://github.com/escherba/python-cityhash: Python bindings for CityHash (Eugene Scherba)https://github.com/veelion/python-farmhash: Python bindigs for FarmHash (Veelion Chong)https://github.com/escherba/python-metrohash: Python bindings for MetroHash (Eugene Scherba)https://github.com/ifduyue/python-xxhash: Python bindings for xxHash (Yue Du)