CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-xxhash

Python binding for xxHash library providing fast non-cryptographic hash algorithms

Overall
score

80%

Evaluation — 80%

↑ 1.03x

Agent success when using this tile

Overview
Eval results
Files

index.mddocs/

xxhash

Python binding for the xxHash library providing fast non-cryptographic hash algorithms. xxhash offers hashlib-compliant interfaces for xxh32, xxh64, and xxh3 hash functions with both streaming and oneshot APIs, designed for applications requiring fast checksums, data integrity verification, hash tables, and general-purpose hashing where cryptographic security is not required.

Package Information

  • Package Name: xxhash
  • Language: Python
  • Installation: pip install xxhash or conda install -c conda-forge python-xxhash

Core Imports

import xxhash

For specific algorithms:

from xxhash import xxh32, xxh64, xxh3_64, xxh3_128

Basic Usage

import xxhash

# Using streaming interface (hashlib-compliant)
hasher = xxhash.xxh64()
hasher.update(b'Hello')
hasher.update(b' World')
print(hasher.hexdigest())  # '32dd38952c4bc720'

# Using oneshot functions (more efficient)
hash_value = xxhash.xxh64_hexdigest(b'Hello World')
print(hash_value)  # '32dd38952c4bc720'

# With seed for different hash values
hash_with_seed = xxhash.xxh64_hexdigest(b'Hello World', seed=42)
print(hash_with_seed)  # 'different hash value'

# Different output formats
print(xxhash.xxh64_digest(b'test'))     # b'\xd4\x12...` (bytes)
print(xxhash.xxh64_hexdigest(b'test'))  # 'd412...' (hex string)  
print(xxhash.xxh64_intdigest(b'test'))  # 15266911421115075350 (integer)

Capabilities

Streaming Hash Classes

Hashlib-compliant streaming hash interfaces that allow incremental data processing.

from typing_extensions import final

@final
class xxh32:
    """32-bit xxHash streaming hasher."""
    def __init__(self, input: InputType = None, seed: int = 0) -> None: ...
    def update(self, input: InputType) -> None: ...
    def digest(self) -> bytes: ...
    def hexdigest(self) -> str: ...
    def intdigest(self) -> int: ...
    def copy(self) -> xxh32: ...
    def reset(self) -> None: ...
    
    @property
    def digest_size(self) -> int: ...  # Returns 4
    @property 
    def digestsize(self) -> int: ...   # Alias for digest_size
    @property
    def block_size(self) -> int: ...   # Returns 16
    @property
    def name(self) -> str: ...         # Returns "xxh32"
    @property
    def seed(self) -> int: ...         # Seed value used

@final
class xxh3_64:
    """64-bit XXH3 streaming hasher."""
    def __init__(self, input: InputType = None, seed: int = 0) -> None: ...
    def update(self, input: InputType) -> None: ...
    def digest(self) -> bytes: ...
    def hexdigest(self) -> str: ...
    def intdigest(self) -> int: ...
    def copy(self) -> xxh3_64: ...
    def reset(self) -> None: ...
    
    @property
    def digest_size(self) -> int: ...  # Returns 8
    @property
    def digestsize(self) -> int: ...   # Alias for digest_size  
    @property
    def block_size(self) -> int: ...   # Returns 16
    @property
    def name(self) -> str: ...         # Returns "xxh3_64"
    @property
    def seed(self) -> int: ...         # Seed value used

@final
class xxh3_128:
    """128-bit XXH3 streaming hasher."""
    def __init__(self, input: InputType = None, seed: int = 0) -> None: ...
    def update(self, input: InputType) -> None: ...
    def digest(self) -> bytes: ...
    def hexdigest(self) -> str: ...
    def intdigest(self) -> int: ...
    def copy(self) -> xxh3_64: ...
    def reset(self) -> None: ...
    
    @property
    def digest_size(self) -> int: ...  # Returns 8
    @property
    def digestsize(self) -> int: ...   # Alias for digest_size
    @property
    def block_size(self) -> int: ...   # Returns 16  
    @property
    def name(self) -> str: ...         # Returns "xxh3_64"
    @property
    def seed(self) -> int: ...         # Seed value used

class xxh3_128:
    """128-bit XXH3 streaming hasher."""
    def __init__(self, input: InputType = None, seed: int = 0) -> None: ...
    def update(self, input: InputType) -> None: ...
    def digest(self) -> bytes: ...
    def hexdigest(self) -> str: ...
    def intdigest(self) -> int: ...
    def copy(self) -> xxh3_128: ...
    def reset(self) -> None: ...
    
    @property
    def digest_size(self) -> int: ...  # Returns 16
    @property
    def digestsize(self) -> int: ...   # Alias for digest_size
    @property
    def block_size(self) -> int: ...   # Returns 16
    @property
    def name(self) -> str: ...         # Returns "xxh3_128"
    @property
    def seed(self) -> int: ...         # Seed value used

# Aliases pointing to the main classes
xxh64 = xxh3_64   # xxh64 is an alias for xxh3_64
xxh128 = xxh3_128 # xxh128 is an alias for xxh3_128

Oneshot Hash Functions

Fast oneshot functions that avoid heap allocation, optimized for single-use hashing.

# xxh32 oneshot functions
def xxh32_digest(args: InputType, seed: int = 0) -> bytes:
    """Return xxh32 hash as bytes (big-endian)."""

def xxh32_hexdigest(args: InputType, seed: int = 0) -> str:
    """Return xxh32 hash as lowercase hex string."""

def xxh32_intdigest(args: InputType, seed: int = 0) -> int:
    """Return xxh32 hash as integer."""

# xxh64 oneshot functions (aliases for xxh3_64)
def xxh64_digest(args: InputType, seed: int = 0) -> bytes:
    """Return xxh64 hash as bytes (big-endian)."""

def xxh64_hexdigest(args: InputType, seed: int = 0) -> str:
    """Return xxh64 hash as lowercase hex string."""

def xxh64_intdigest(args: InputType, seed: int = 0) -> int:
    """Return xxh64 hash as integer."""

# xxh3_64 oneshot functions  
def xxh3_64_digest(args: InputType, seed: int = 0) -> bytes:
    """Return xxh3_64 hash as bytes (big-endian)."""

def xxh3_64_hexdigest(args: InputType, seed: int = 0) -> str:
    """Return xxh3_64 hash as lowercase hex string."""

def xxh3_64_intdigest(args: InputType, seed: int = 0) -> int:
    """Return xxh3_64 hash as integer."""

# xxh3_128 oneshot functions
def xxh3_128_digest(args: InputType, seed: int = 0) -> bytes:
    """Return xxh3_128 hash as bytes (big-endian)."""

def xxh3_128_hexdigest(args: InputType, seed: int = 0) -> str:
    """Return xxh3_128 hash as lowercase hex string."""

def xxh3_128_intdigest(args: InputType, seed: int = 0) -> int:
    """Return xxh3_128 hash as integer."""

# xxh128 oneshot functions (aliases for xxh3_128)
def xxh128_digest(args: InputType, seed: int = 0) -> bytes:
    """Return xxh128 hash as bytes (big-endian)."""

def xxh128_hexdigest(args: InputType, seed: int = 0) -> str:
    """Return xxh128 hash as lowercase hex string."""

def xxh128_intdigest(args: InputType, seed: int = 0) -> int:
    """Return xxh128 hash as integer."""

Package Metadata

Version information and available algorithms.

VERSION: str  # Package version (e.g., "3.5.0")
VERSION_TUPLE: tuple[int, ...]  # Version as tuple (e.g., (3, 5, 0))
XXHASH_VERSION: str  # Underlying xxHash library version
algorithms_available: set[str]  # {"xxh32", "xxh64", "xxh3_64", "xxh128", "xxh3_128"}

Types

from typing import Union
import array

# Input types accepted by all hash functions
InputType = Union[str, bytes, bytearray, memoryview, array.ArrayType[int]]

Usage Examples

Streaming vs Oneshot Performance

import xxhash

# Streaming interface - use when data comes in chunks
hasher = xxhash.xxh64()
with open('large_file.dat', 'rb') as f:
    for chunk in iter(lambda: f.read(8192), b""):
        hasher.update(chunk)
result = hasher.hexdigest()

# Oneshot interface - faster for single operations
result = xxhash.xxh64_hexdigest(open('small_file.dat', 'rb').read())

Different Hash Algorithms

import xxhash

data = b"test data"

# 32-bit hash (4 bytes output)
hash32 = xxhash.xxh32_hexdigest(data)

# 64-bit hash (8 bytes output) - recommended for general use
hash64 = xxhash.xxh64_hexdigest(data)

# 128-bit hash (16 bytes output) - for applications needing lower collision rate
hash128 = xxhash.xxh128_hexdigest(data)

Seed Usage for Different Hash Families

import xxhash

data = b"same input data"

# Different seeds produce different hashes
hash_a = xxhash.xxh64_hexdigest(data, seed=0)
hash_b = xxhash.xxh64_hexdigest(data, seed=42)
hash_c = xxhash.xxh64_hexdigest(data, seed=12345)

# All three hashes will be different despite same input

Output Format Comparison

import xxhash

data = b"example"
hasher = xxhash.xxh64(data)

# Three output formats for the same hash
bytes_result = hasher.digest()      # b'\xd4\x12...' (8 bytes for xxh64)
hex_result = hasher.hexdigest()     # 'd412...' (16 hex chars for xxh64)
int_result = hasher.intdigest()     # 15266911421115075350 (integer)

# Verify they represent the same value
assert int_result.to_bytes(8, 'big') == bytes_result
assert format(int_result, '016x') == hex_result

Important Notes

Seed Constraints

  • xxh32: Accepts unsigned 32-bit integers (0 to 2^32-1)
  • xxh64/xxh3_64: Accepts unsigned 64-bit integers (0 to 2^64-1)
  • xxh3_128: Accepts unsigned 64-bit integers (0 to 2^64-1)

Output Format

All digest() methods return big-endian byte representation (changed from little-endian in version 0.3.0).

Performance

Oneshot functions (xxh64_hexdigest, etc.) are faster than streaming equivalents for single-use hashing as they avoid heap allocation.

Non-Cryptographic

xxhash algorithms are not cryptographically secure and should not be used for security purposes, password hashing, or HMAC applications.

Install with Tessl CLI

npx tessl i tessl/pypi-xxhash

docs

index.md

tile.json