Google FarmHash Bindings for Python

Warnings

• gotcha Many `pyfarmhash` functions, especially `fingerprint` variants, strictly require byte strings (`bytes`) as input. Passing a regular Python string (`str`) will result in a `TypeError`. Remember to encode strings (e.g., `my_string.encode('utf-8')`) before passing them to these functions.
  Fix: Always encode string inputs to bytes using `.encode('utf-8')` (or another appropriate encoding) before calling byte-specific hashing functions like `farmhash.fingerprint64()`.
• gotcha When installing `pyfarmhash` from source (not using pre-built wheels), a C++ compiler is required (`g++` on Linux/macOS, Microsoft Visual C++ Compiler on Windows). Setting up the build environment on Windows can be particularly complex.
  Fix: Prefer `pip install pyfarmhash` to leverage pre-built wheels. If building from source, ensure your C++ compiler and associated build tools are correctly installed and configured for your Python environment. For Windows, consider the detailed (and often 'hacky') instructions in the GitHub README if pre-built wheels are not an option.
• gotcha FarmHash is a non-cryptographic hash function. This means it is optimized for speed and distribution, but it is not designed to be collision-resistant and should NOT be used for security-sensitive applications like password hashing or data integrity verification where cryptographic strength is needed.
  Fix: Use cryptographic hash functions (e.g., from Python's `hashlib` module) for security-critical tasks. FarmHash is suitable for tasks like data deduplication, partitioning, and unique identifier generation in non-security contexts.
• gotcha Discrepancies can occur when comparing `pyfarmhash` output with Google BigQuery's `FARM_FINGERPRINT` function, particularly regarding the handling of unsigned 64-bit integers vs. signed integers in Python. BigQuery might return a signed representation where `pyfarmhash` returns an unsigned one.
  Fix: If matching BigQuery's `FARM_FINGERPRINT` output is critical, explicitly convert the `pyfarmhash` output to a signed 64-bit integer using `numpy.uint64(hash_value).astype('int64')`.

Install

• pip install pyfarmhash Stable release

Imports

• farmhash

  import farmhash

  The primary module containing all hashing functions.
• hash64

  import farmhash
  farmhash.hash64('input')

  One of the main 64-bit hashing functions.
• fingerprint64

  import farmhash
  farmhash.fingerprint64(b'input')

  Functions like `fingerprint64` expect byte strings as input; passing a regular Python string will raise a TypeError.

Quickstart

This quickstart demonstrates basic usage of `pyfarmhash` for 32-bit and 64-bit hashing, including using seeds and the critical distinction between string and byte string inputs for different function types.

import farmhash

# Hashing a standard string (utf-8 encoded by default for hash functions)
text_input = 'Hello, FarmHash!'
hash_value_64 = farmhash.hash64(text_input)
hash_value_32 = farmhash.hash32(text_input)
print(f"Hash64 for '{text_input}': {hash_value_64}")
print(f"Hash32 for '{text_input}': {hash_value_32}")

# Hashing a byte string (required for fingerprint functions)
bytes_input = b'Another test string'
fingerprint_64 = farmhash.fingerprint64(bytes_input)
fingerprint_32 = farmhash.fingerprint32(bytes_input)
print(f"Fingerprint64 for '{bytes_input.decode()}': {fingerprint_64}")
print(f"Fingerprint32 for '{bytes_input.decode()}': {fingerprint_32}")

# Hashing with a seed
seeded_hash = farmhash.hash64withseed(text_input, 12345)
print(f"Seeded Hash64 for '{text_input}' with seed 12345: {seeded_hash}")