### Docker Installation with System libxxhash

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

Install xxhash in Docker, first installing the system libxxhash development files, then installing the Python binding to link against it.

```dockerfile
FROM python:3.11-slim

RUN apt-get update && apt-get install -y libxxhash-dev

RUN XXHASH_LINK_SO=1 pip install --no-cache-dir --no-binary xxhash xxhash

COPY app.py /app/
WORKDIR /app
CMD ["python", "app.py"]
```

--------------------------------

### Install xxhash with Bundled Library

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

Use this command to install xxhash when you want to use the bundled xxHash library. This is the default behavior.

```bash
XXHASH_LINK_SO=0 pip install --no-binary xxhash xxhash
```

--------------------------------

### Install xxhash from source

Source: https://github.com/ifduyue/python-xxhash/blob/master/README.rst

Install the xxhash library from source using pip. This method is useful if you need to compile the library yourself.

```bash
pip install --no-binary xxhash xxhash
```

--------------------------------

### Development Installation

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

Set up the python-xxhash project for development and testing. This involves cloning the repository, creating and activating a virtual environment, installing the package in editable mode, and installing test dependencies.

```bash
git clone https://github.com/ifduyue/python-xxhash.git
cd python-xxhash
```

```bash
python -m venv venv
source venv/bin/activate
```

```bash
pip install -e .
```

```bash
pip install pytest
```

```bash
pytest tests/
```

--------------------------------

### Install xxhash linking to libxxhash.so

Source: https://github.com/ifduyue/python-xxhash/blob/master/README.rst

Install the xxhash library while linking to an existing libxxhash.so. This is achieved by setting the XXHASH_LINK_SO environment variable.

```bash
XXHASH_LINK_SO=1 pip install --no-binary xxhash xxhash
```

--------------------------------

### Install xxhash with Bundled Library (Default)

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

This command installs xxhash using its vendored source code, which is the default behavior. No external dependencies are needed, ensuring reproducible and self-contained builds.

```bash
# Bundled xxHash (default)
pip install xxhash
```

--------------------------------

### Install xxhash from Source on Debian/Ubuntu

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

Install necessary development packages (python-dev, gcc) before building from source on Debian or Ubuntu systems.

```bash
apt-get install python-dev gcc
pip install --no-binary xxhash xxhash
```

--------------------------------

### Docker Installation with Bundled Library

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

Install xxhash within a Docker container using a slim Python image, relying on the bundled xxHash library.

```dockerfile
FROM python:3.11-slim

RUN pip install --no-cache-dir xxhash

RUN python -c "import xxhash; print(xxhash.VERSION)"

COPY app.py /app/
WORKDIR /app
CMD ["python", "app.py"]
```

--------------------------------

### Install xxhash using pip

Source: https://github.com/ifduyue/python-xxhash/blob/master/README.rst

Install the xxhash library using pip. This is the standard method for installing Python packages.

```bash
pip install xxhash
```

--------------------------------

### Verify xxhash Installation

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

Run a simple Python command to confirm that xxhash has been installed successfully and to check its version.

```bash
python -c "import xxhash; print(xxhash.VERSION)"
```

--------------------------------

### Install xxhash from Source on macOS

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

Install using Homebrew and pip. For Apple Silicon, you may need to explicitly set the CFLAGS environment variable.

```bash
# With Homebrew
brew install python
pip install --no-binary xxhash xxhash

# With Apple Silicon, may need explicit architecture
CFLAGS=-fPIC pip install --no-binary xxhash xxhash
```

--------------------------------

### Install xxhash from Source on CentOS/Fedora

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

Install required development packages (python-devel, gcc, redhat-rpm-config) before building from source on CentOS or Fedora systems.

```bash
yum install python-devel gcc redhat-rpm-config
pip install --no-binary xxhash xxhash
```

--------------------------------

### Install xxhash using conda

Source: https://github.com/ifduyue/python-xxhash/blob/master/README.rst

Install the xxhash library using conda. This is an alternative installation method, particularly useful for managing environments.

```bash
conda install -c conda-forge python-xxhash
```

--------------------------------

### Verify XXHash Installation Version

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

Confirm the installed version of the python-xxhash package and the linked XXHash C library. This is a quick check after installation.

```python
import xxhash

print(f"python-xxhash: {xxhash.VERSION}")
print(f"xxHash library: {xxhash.XXHASH_VERSION}")
```

--------------------------------

### Link xxhash against System Library on Debian/Ubuntu

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

Install the libxxhash-dev package and then install python-xxhash with the XXHASH_LINK_SO environment variable set to link against the system library.

```bash
apt-get install libxxhash-dev
XXHASH_LINK_SO=1 pip install --no-binary xxhash xxhash
```

--------------------------------

### Specify Include Directories

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

Provide custom include directories for the C compiler when installing xxhash.

```bash
CFLAGS="-I/usr/local/include" pip install --no-binary xxhash xxhash
```

--------------------------------

### Link xxhash against System Library on CentOS/Fedora

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

Install the xxhash-devel package and then install python-xxhash with the XXHASH_LINK_SO environment variable set to link against the system library.

```bash
yum install xxhash-devel
XXHASH_LINK_SO=1 pip install --no-binary xxhash xxhash
```

--------------------------------

### Link xxhash against System Library on macOS

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

Install the xxhash library using Homebrew, then install python-xxhash with the XXHASH_LINK_SO environment variable set to link against the system library.

```bash
brew install xxhash
XXHASH_LINK_SO=1 pip install --no-binary xxhash xxhash
```

--------------------------------

### One-Liner Hashing Examples

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/quick-reference.md

Demonstrates various ways to perform hashing with different algorithms, including hashing bytes, strings, files, and using seeds. Also shows how to copy and update hash objects.

```python
import xxhash

# Hash bytes
h = xxhash.xxh64(b'data').hexdigest()

# Hash string
h = xxhash.xxh64('text'.encode()).hexdigest()

# File hash
h = xxhash.xxh64(open('file.bin', 'rb').read()).hexdigest()

# Different algorithms
h32 = xxhash.xxh32(b'data').intdigest()
h64 = xxhash.xxh64(b'data').intdigest()
h128 = xxhash.xxh3_128(b'data').intdigest()

# With seed
h = xxhash.xxh64(b'data', seed=12345).hexdigest()

# Copy and modify
h1 = xxhash.xxh64(b'prefix')
h2 = h1.copy()
h1.update(b'_a')
h2.update(b'_b')
```

--------------------------------

### Run Python xxHash Tests

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/c-extension-details.md

Executes the test suite for the Python xxHash library using pytest. Ensure pytest is installed (`pip install pytest`).

```bash
python -m pytest tests/
```

--------------------------------

### xxh3_64 Output Formats

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/algorithm-comparison.md

Demonstrates how to get the hash digest in binary, hexadecimal, and integer formats after initializing the hasher with data. Ensure the data is in bytes.

```python
import xxhash

data = b'test'

# Binary (big-endian)
h = xxhash.xxh3_64(data)
digest = h.digest()
assert len(digest) == 8

# Hexadecimal (16 characters)
hex_str = h.hexdigest()
assert len(hex_str) == 16

# Integer
int_val = h.intdigest()
assert 0 <= int_val < 2**64
```

--------------------------------

### Specify Library Directories

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

Define custom library directories for the linker when installing xxhash, often used with system libraries.

```bash
LDFLAGS="-L/usr/local/lib" XXHASH_LINK_SO=1 \
  pip install --no-binary xxhash xxhash
```

--------------------------------

### Basic XXHash Usage

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/README.md

Demonstrates basic hashing operations using the xxh64 algorithm. Includes creating a hasher, getting hexadecimal, integer, and raw byte digests, and performing streaming updates. Also shows a one-shot hexdigest calculation.

```python
import xxhash

# Create hasher
h = xxhash.xxh64(b'data')

# Get result
print(h.hexdigest())   # '32dd38952c4bc720'
print(h.intdigest())   # 3705155649435444000
print(h.digest())      # b'2\xdd8\x95,K\xc7 '

# Streaming
h = xxhash.xxh64()
h.update(b'chunk1')
h.update(b'chunk2')

# One-shot
result = xxhash.xxh64_hexdigest(b'data')
```

--------------------------------

### Example Usage of xxh128 Aliases

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh3.md

Demonstrates the equivalent usage of xxh128 and xxh3_128 functions for creating hash objects and computing digests.

```python
import xxhash

# These are equivalent:
h1 = xxhash.xxh128()
h2 = xxhash.xxh3_128()

# These are equivalent:
result1 = xxhash.xxh128_digest(b'data')
result2 = xxhash.xxh3_128_digest(b'data')
```

--------------------------------

### Build Python xxHash C Extension (Bundled)

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/c-extension-details.md

Builds the C extension in-place using the bundled xxHash library. Use this for development or when a system-wide installation is not desired.

```bash
python setup.py build_ext --inplace
```

--------------------------------

### Copying and Resetting XXHash64 Hasher

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/index.md

Demonstrates how to create a copy of an existing hasher state and how to reset a hasher to its initial state. This is useful for reusing hasher objects or starting new hash calculations from an intermediate point.

```python
# Copy and reset
h2 = h.copy()
h.reset()
```

--------------------------------

### Migrate from xxh32 to xxh3_64 in Python

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/algorithm-comparison.md

Transition from xxh32 to xxh3_64 for applications that require a larger hash space. This example shows how to adapt existing 32-bit hashing logic to the 64-bit implementation, including options for larger output spaces.

```python
import xxhash

# Old 32-bit implementation
def hash_32bit(data):
    return xxhash.xxh32(data).intdigest() % 256

# New 64-bit implementation
def hash_64bit(data):
    return xxhash.xxh3_64(data).intdigest() % 256

# More buckets available if needed
def hash_64bit_large(data):
    return xxhash.xxh3_64(data).intdigest() % 65536  # Much larger space
```

--------------------------------

### Content-Addressed Storage Example

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/algorithm-comparison.md

Implements a simple content-addressed storage system using xxh3_128 for generating unique addresses from data. The storage verifies data integrity upon retrieval.

```python
import xxhash
import hashlib

def content_address(data):
    """Generate a content address using xxh3_128."""
    h = xxhash.xxh3_128(data)
    return h.hexdigest()

class ContentAddressedStorage:
    def __init__(self):
        self.store = {}
    
    def store_data(self, data):
        """Store data by content address."""
        address = content_address(data)
        self.store[address] = data
        return address
    
    def retrieve_data(self, address):
        """Retrieve data by address, verify integrity."""
        if address not in self.store:
            raise KeyError(f"No data at {address}")
        
        data = self.store[address]
        # Verify address matches content
        assert content_address(data) == address
        return data

# Usage
cas = ContentAddressedStorage()
address = cas.store_data(b'important data')
retrieved = cas.retrieve_data(address)
assert retrieved == b'important data'
```

--------------------------------

### Hash Table Bucket Mapping with xxh32

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/algorithm-comparison.md

Example of using xxh32 to map keys to buckets in a hash table implementation. Handles both string and bytes keys by encoding strings to bytes.

```python
import xxhash

def hash_to_bucket(key, num_buckets):
    """Map a key to a bucket using xxh32."""
    h = xxhash.xxh32(key if isinstance(key, bytes) else key.encode())
    return h.intdigest() % num_buckets

# Distribute 10000 items across 256 buckets
buckets = [[] for _ in range(256)]
for i in range(10000):
    bucket_id = hash_to_bucket(f"key_{i}", 256)
    buckets[bucket_id].append(i)
```

--------------------------------

### xxh3_128 Output Formats

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/algorithm-comparison.md

Demonstrates how to get the hash digest in binary, hexadecimal, and integer formats using xxh3_128. Ensure the data is bytes.

```python
import xxhash

data = b'test'

# Binary (big-endian)
h = xxhash.xxh3_128(data)
digest = h.digest()
assert len(digest) == 16

# Hexadecimal (32 characters)
hex_str = h.hexdigest()
assert len(hex_str) == 32

# Integer
int_val = h.intdigest()
assert 0 <= int_val < 2**128
```

--------------------------------

### Link xxhash against System Library

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

To link against a system-installed libxxhash, set the XXHASH_LINK_SO environment variable to 1 before installing. This requires libxxhash and its development headers to be present on the system.

```bash
# Link against system libxxhash
XXHASH_LINK_SO=1 pip install --no-binary xxhash xxhash
```

--------------------------------

### hashlib Compatibility in xxhash

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/index.md

Use xxhash as a drop-in replacement for hashlib, leveraging the same interface and properties. This example shows basic usage and accessing hashlib-like attributes.

```python
import xxhash

# Compatible with hashlib interface
h = xxhash.xxh64()
h.update(b'data')
digest = h.digest()

# Same properties as hashlib
print(h.digest_size)  # 8
print(h.block_size)   # 32
print(h.name)         # 'xxh64'
```

--------------------------------

### Implementing __buffer__() for Custom Objects

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/buffer-protocol.md

Example of a custom class `BufferedData` that implements the `__buffer__` method to expose its internal byte data as a memoryview for hashing.

```python
class BufferedData:
    def __init__(self, data: bytes):
        self._data = data
    
    def __buffer__(self, flags: int) -> memoryview:
        return memoryview(self._data).__buffer__(flags)

# Usage
obj = BufferedData(b'test')
import xxhash
h = xxhash.xxh64(obj)
```

--------------------------------

### Get python-xxhash Version

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/module-constants.md

Retrieve the semantic version string of the python-xxhash package. Use this for checking the installed package version.

```python
import xxhash
print(xxhash.VERSION)
```

--------------------------------

### Setuptools Extension Configuration

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/c-extension-details.md

Python code demonstrating how to configure the C extension module using setuptools. It specifies the source files, include directories, and libraries for compilation.

```python
ext_modules = [
    Extension(
        "_xxhash",
        source,                    # ['src/_xxhash.c', 'deps/xxhash/xxhash.c']
        include_dirs=include_dirs,  # ['deps/xxhash']
        libraries=libraries,        # [] or ['xxhash'] if linking
    )
]
```

--------------------------------

### Check Python xxhash Updates and Versions

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

Check for available versions of the xxhash package on PyPI or verify the currently installed version using pip and Python.

```bash
# Check available versions
pip index versions xxhash
```

```bash
# Check installed version
python -c "import xxhash; print(xxhash.VERSION)"
```

--------------------------------

### Troubleshoot ImportError on Linux

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

Use these commands to resolve 'ImportError: libxxhash.so not found' on Linux systems. Options include rebuilding the bundled version, installing the system library, or using a pre-built wheel.

```bash
pip install --no-cache-dir --force-reinstall xxhash
```

```bash
sudo apt-get install libxxhash-dev
```

```bash
pip install --only-binary xxhash xxhash
```

--------------------------------

### Get Generic Algorithm Information

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/usage-patterns.md

Retrieve and print information such as the name, digest size, and block size for different xxHash algorithms. This function helps in understanding the characteristics of each algorithm.

```python
import xxhash

def describe_algorithm(algorithm_name):
    """Print info about an algorithm."""
    if algorithm_name == 'xxh32':
        h = xxhash.xxh32()
    elif algorithm_name == 'xxh64':
        h = xxhash.xxh64()
    elif algorithm_name == 'xxh3_64':
        h = xxhash.xxh3_64()
    elif algorithm_name == 'xxh3_128':
        h = xxhash.xxh3_128()
    else:
        raise ValueError(f"Unknown algorithm: {algorithm_name}")
    
    print(f"Name: {h.name}")
    print(f"Digest Size: {h.digest_size} bytes")
    print(f"Block Size: {h.block_size} bytes")

describe_algorithm('xxh3_128')
```

--------------------------------

### Initialize xxh64 Hasher

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh64.md

Demonstrates various ways to initialize an xxh64 hasher, including with no data, with initial data, with a seed, or by creating an instance and updating it later.

```python
import xxhash

# Basic initialization
h = xxhash.xxh64()

# With initial data
h = xxhash.xxh64(b'hello')

# With seed
h = xxhash.xxh64(b'hello', seed=20141025)

# Create without data, add later
h = xxhash.xxh64(seed=99999999)
h.update(b'world')
```

--------------------------------

### Initialize xxh3_64 Hasher

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/algorithm-comparison.md

Import the xxhash library and create an instance of the xxh3_64 hasher. This is the first step before updating the hasher with data.

```python
import xxhash

h = xxhash.xxh3_64()
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

Steps to create and activate a Python virtual environment for isolated project dependencies.

```bash
python3.11 -m venv myproject_venv

source myproject_venv/bin/activate  # On Windows: myproject_venv\Scripts\activate
```

--------------------------------

### xxh64 Constructor and Methods

Source: https://github.com/ifduyue/python-xxhash/blob/master/README.rst

Demonstrates the usage of the xxh64 hash algorithm, including updating the digest and retrieving it in different formats.

```APIDOC
## xxh64 Hash Algorithm

### Description
Provides a 64-bit xxHash implementation compliant with the hashlib interface. Supports `update()`, `digest()`, `hexdigest()`, `intdigest()`, `copy()`, and `reset()` methods.

### Constructors
- `xxhash.xxh64()`: Initializes a new xxh64 hash object.
- `xxhash.xxh64(data)`: Initializes a new xxh64 hash object with initial data.
- `xxhash.xxh64(data, seed=0)`: Initializes a new xxh64 hash object with initial data and a seed.

### Methods
- `update(data)`: Updates the hash object with the given data (bytes).
- `digest()`: Returns the hash digest as bytes (big-endian representation).
- `hexdigest()`: Returns the hash digest as a hexadecimal string.
- `intdigest()`: Returns the hash digest as an integer.
- `copy()`: Returns a copy of the current hash object.
- `reset()`: Resets the hash object's state.

### Example
```python
import xxhash

# Initialize with data
hash_obj = xxhash.xxh64(b'xxhash')
print(hash_obj.hexdigest())

# Update with more data
hash_obj.update(b' more data')
print(hash_obj.digest())
print(hash_obj.intdigest())

# Initialize without data and update later
new_hash_obj = xxhash.xxh64()
new_hash_obj.update(b'some data')
print(new_hash_obj.hexdigest())
```

### Seed Usage
An optional seed (default is 0) can be used to alter the result predictably. The seed should be an unsigned 64-bit integer.

```python
import xxhash

# With default seed (0)
print(xxhash.xxh64(b'test').hexdigest())

# With a specific seed
print(xxhash.xxh64(b'test', seed=20141025).hexdigest())

# Seed wraps around 2**64
print(xxhash.xxh64(b'test', seed=2**64 + 1).hexdigest())
```
```

--------------------------------

### Initialize xxh32 Hasher

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh32.md

Demonstrates different ways to initialize an xxh32 hasher, including with and without initial data, and with a custom seed. The hasher can also be initialized empty and updated later.

```python
import xxhash

# Basic initialization
h = xxhash.xxh32()

# With initial data
h = xxhash.xxh32(b'hello')

# With seed
h = xxhash.xxh32(b'hello', seed=1234)

# Create without data, add later
h = xxhash.xxh32(seed=999)
h.update(b'world')
```

--------------------------------

### Initialize xxh3_64 Hasher

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh3.md

Demonstrates different ways to initialize the xxh3_64 hasher, including with and without initial data, and with a custom seed. The hasher can also be initialized empty and updated later.

```python
import xxhash

# Basic initialization
h = xxhash.xxh3_64()

# With initial data
h = xxhash.xxh3_64(b'hello')

# With seed
h = xxhash.xxh3_64(b'hello', seed=12345)

# Create without data, add later
h = xxhash.xxh3_64(seed=999)
h.update(b'world')
```

--------------------------------

### xxh32 Constructor and Methods

Source: https://github.com/ifduyue/python-xxhash/blob/master/README.rst

Demonstrates the usage of the xxh32 hash algorithm, including updating the digest and retrieving it in different formats.

```APIDOC
## xxh32 Hash Algorithm

### Description
Provides a 32-bit xxHash implementation compliant with the hashlib interface. Supports `update()`, `digest()`, `hexdigest()`, `intdigest()`, `copy()`, and `reset()` methods.

### Constructors
- `xxhash.xxh32()`: Initializes a new xxh32 hash object.
- `xxhash.xxh32(data)`: Initializes a new xxh32 hash object with initial data.
- `xxhash.xxh32(data, seed=0)`: Initializes a new xxh32 hash object with initial data and a seed.

### Methods
- `update(data)`: Updates the hash object with the given data (bytes).
- `digest()`: Returns the hash digest as bytes (big-endian representation).
- `hexdigest()`: Returns the hash digest as a hexadecimal string.
- `intdigest()`: Returns the hash digest as an integer.
- `copy()`: Returns a copy of the current hash object.
- `reset()`: Resets the hash object's state.

### Example
```python
import xxhash

# Initialize with data
hash_obj = xxhash.xxh32(b'Nobody inspects the spammish repetition')
print(hash_obj.hexdigest())

# Update with more data
hash_obj.update(b' more data')
print(hash_obj.digest())
print(hash_obj.intdigest())

# Initialize without data and update later
new_hash_obj = xxhash.xxh32()
new_hash_obj.update(b'some data')
print(new_hash_obj.hexdigest())
```

### Seed Usage
An optional seed (default is 0) can be used to alter the result predictably. The seed should be an unsigned 32-bit integer.

```python
import xxhash

# With default seed (0)
print(xxhash.xxh32(b'test').hexdigest())

# With a specific seed
print(xxhash.xxh32(b'test', seed=12345).hexdigest())

# Seed wraps around 2**32
print(xxhash.xxh32(b'test', seed=2**32 + 1).hexdigest())
```
```

--------------------------------

### Initialize xxh3_128 Hasher

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/algorithm-comparison.md

Import the xxhash library and create an instance of the xxh3_128 hasher.

```python
import xxhash

h = xxhash.xxh3_128()
```

--------------------------------

### Hash with Different Algorithms and Options

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/index.md

Demonstrates creating xxHash objects for different algorithms (xxh32, xxh64, xxh3_128), using a seed for hashing, and performing a one-shot digest calculation.

```python
import xxhash

# Different algorithms
h32 = xxhash.xxh32(b'data')
h64 = xxhash.xxh64(b'data')
h128 = xxhash.xxh3_128(b'data')

# With seed
h_seeded = xxhash.xxh64(b'data', seed=12345)

# One-shot (no object allocation)
digest = xxhash.xxh64_digest(b'data')
```

--------------------------------

### Get xxh32 Name

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh32.md

Retrieve the name of the hashing algorithm, which is 'xxh32' for this instance.

```python
import xxhash
h = xxhash.xxh32()
assert h.name == 'xxh32'
```

--------------------------------

### Get XXH64 Name

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh64.md

Retrieve the name of the hashing algorithm, which is 'xxh64' for this instance.

```python
import xxhash
h = xxhash.xxh64()
assert h.name == 'xxh64'
```

--------------------------------

### Initialize xxh3_128 Hasher

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh3.md

Demonstrates various ways to initialize the xxh3_128 hasher, with or without initial data and with a custom seed.

```python
import xxhash

# Basic initialization
h = xxhash.xxh3_128()

# With initial data
h = xxhash.xxh3_128(b'hello')

# With seed
h = xxhash.xxh3_128(b'hello', seed=12345)

# Create without data, add later
h = xxhash.xxh3_128(seed=999)
h.update(b'world')
```

--------------------------------

### Hash Object Properties

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/quick-reference.md

Access properties of the hash object to get information about its configuration and state.

```python
h.digest_size                   # Digest size: 4, 8, or 16
```

```python
h.digestsize                    # Alias for digest_size
```

```python
h.block_size                    # Block size: 16, 32, or 64
```

```python
h.name                          # Algorithm name: 'xxh32', 'xxh64', etc.
```

```python
h.seed                          # Seed value used at construction
```

--------------------------------

### Initialize xxh64 Hash Object

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/algorithm-comparison.md

Import the xxhash library and create an instance of the xxh64 hash object. This is the first step before hashing any data.

```python
import xxhash

h = xxhash.xxh64()
```

--------------------------------

### Get xxh32 Block Size

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh32.md

Retrieve the internal block size in bytes for the xxh32 hash algorithm.

```python
import xxhash
h = xxhash.xxh32()
assert h.block_size == 16
```

--------------------------------

### Get XXH64 Block Size

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh64.md

Retrieve the internal block size in bytes for the XXH64 hash algorithm.

```python
import xxhash
h = xxhash.xxh64()
assert h.block_size == 32
```

--------------------------------

### Performance Tips for XXHash

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/quick-reference.md

Illustrates performance optimizations for XXHash, including one-shot hashing for small data, streaming for large data, and efficient slicing using memoryview.

```python
# For small data: one-shot
result = xxhash.xxh64_digest(b'small')

# For large data: streaming
h = xxhash.xxh64()
h.update(large_data_1)
h.update(large_data_2)

# GIL released for updates >= 65536 bytes (thread-safe)
h.update(b'x' * 100000)  # GIL released during this

# Efficient slicing with memoryview
data = b'large_data'
mv = memoryview(data)
h = xxhash.xxh64(mv[0:1000])  # No copy
```

--------------------------------

### Specify C Compiler Flags

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

Set custom C compiler flags, such as optimization levels, during the installation of xxhash.

```bash
CFLAGS="-O3 -march=native" pip install --no-binary xxhash xxhash
```

--------------------------------

### Get xxh3_128 Hash as Integer

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh3.md

Convert the 128-bit hash into a single unsigned integer using the intdigest() method.

```python
h = xxhash.xxh3_128(b'a')
result = h.intdigest()
# Output: 225219434562328483135862406050043285023
```

--------------------------------

### Initialize xxh32 Hash

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/algorithm-comparison.md

Instantiate the xxh32 hash object. This is the first step before hashing any data.

```python
import xxhash

h = xxhash.xxh32()
```

--------------------------------

### Get xxh3_128 Hash as Hex String

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh3.md

Obtain the 128-bit hash as a 32-character hexadecimal string using the hexdigest() method.

```python
h = xxhash.xxh3_128(b'test')
hex_str = h.hexdigest()
# Output: 32-character hex string
```

--------------------------------

### Build Python xxHash C Extension (System)

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/c-extension-details.md

Builds the C extension in-place, linking against a system-installed xxHash library. Set XXHASH_LINK_SO=1 to ensure dynamic linking.

```bash
XXHASH_LINK_SO=1 python setup.py build_ext --inplace
```

--------------------------------

### Get xxh3_64 Hash as Integer

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh3.md

Returns the computed hash value as an unsigned 64-bit integer. The integer will be in the range [0, 2^64-1].

```python
h = xxhash.xxh3_64(b'a')
result = h.intdigest()
# Output: 16629034431890738719
```

--------------------------------

### Get Hexadecimal String Digest from xxh32

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh32.md

The hexdigest() method returns the computed 32-bit hash as an 8-character lowercase hexadecimal string.

```python
h = xxhash.xxh32(b'test')
hex_str = h.hexdigest()
# Output: '1426945110' as 8-character hex
```

--------------------------------

### Basic XXHash64 Hashing and Streaming

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/index.md

Demonstrates creating a hasher object, obtaining results in binary, hex, and integer formats, and performing streaming updates. Use this for general-purpose hashing where the data can be processed in chunks.

```python
import xxhash

# Create a hasher
h = xxhash.xxh64(b'data')

# Get results in different formats
binary = h.digest()        # bytes (big-endian)
hex_str = h.hexdigest()    # str (hex digits)
int_val = h.intdigest()    # int (unsigned)

# Streaming updates
h = xxhash.xxh64()
h.update(b'chunk1')
h.update(b'chunk2')
result = h.digest()
```

--------------------------------

### Get xxh64 Hash as Integer

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh64.md

Returns the computed hash value as an unsigned 64-bit integer. The integer will be in the range [0, 2^64-1].

```python
h = xxhash.xxh64(b'a')
result = h.intdigest()
# Output: 15154266338359012955
```

--------------------------------

### Demonstrate xxhash32 Seed Wrapping

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/types.md

Shows how xxhash32 hashes produce identical results when seeds wrap around the 2^32 bit width. This applies to both zero and non-zero initial seeds.

```python
import xxhash

# These produce identical hashes (seed wraps at 2^32)
h1 = xxhash.xxh32(b'data', seed=0)
h2 = xxhash.xxh32(b'data', seed=2**32)
assert h1.intdigest() == h2.intdigest()

# These also produce identical hashes
h3 = xxhash.xxh32(b'data', seed=1)
h4 = xxhash.xxh32(b'data', seed=2**32 + 1)
assert h3.intdigest() == h4.intdigest()
```

--------------------------------

### Get xxh3_128 Hash as Bytes

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh3.md

Retrieve the computed 128-bit hash as a 16-byte bytes object in big-endian format using the digest() method.

```python
h = xxhash.xxh3_128(b'test')
raw = h.digest()
# Output: bytes of length 16
```

--------------------------------

### Troubleshoot Apple Silicon Issues

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

For build failures on Apple Silicon (M1/M2), use pre-built native wheels or compile with specific flags for Apple Silicon support.

```bash
pip install xxhash
```

```bash
CFLAGS="-arch arm64" pip install --no-binary xxhash xxhash
```

--------------------------------

### Get xxh3_64 Hash as Hex String

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh3.md

Returns the hash value as a lowercase hexadecimal string. This is a common format for representing hash digests.

```python
h = xxhash.xxh3_64(b'test')
hex_str = h.hexdigest()
# Output: 16-character hex string
```

--------------------------------

### Migrate from xxh64 to xxh3_64 in Python

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/algorithm-comparison.md

Use this snippet to transition from the older xxh64 algorithm to the xxh3_64 algorithm. The new code is compatible and offers better quality. The interface remains identical.

```python
import xxhash

# Old code
def old_hash(data):
    return xxhash.xxh64(data).hexdigest()

# New code (compatible, better quality)
def new_hash(data):
    return xxhash.xxh3_64(data).hexdigest()

# Drop-in replacement (same interface)
# Output format changed (different hash values), but interface is identical
```

--------------------------------

### Get Integer Digest from xxh32

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh32.md

The intdigest() method returns the computed 32-bit hash as an unsigned integer within the range [0, 2^32-1].

```python
h = xxhash.xxh32(b'a')
result = h.intdigest()
# Output: 1426945110
```

--------------------------------

### Get Raw Bytes Digest from xxh32

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh32.md

The digest() method returns the computed 32-bit hash as a 4-byte bytes object in big-endian format.

```python
h = xxhash.xxh32(b'test')
raw = h.digest()
# Output: bytes of length 4, e.g., b'\xe2);/'
```

--------------------------------

### XXHash64 Hashing with a Seed

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/index.md

Illustrates how to initialize an XXHash64 hasher with a specific seed value for reproducible hashing results. Useful when you need consistent hashes across different runs or systems.

```python
# With seed
h = xxhash.xxh64(b'data', seed=12345)
```

--------------------------------

### Get Guaranteed Hash Algorithm Names

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/module-constants.md

Retrieve a set of hash algorithm names guaranteed to be available. For xxhash, this is always identical to `algorithms_available`.

```python
import xxhash
print(xxhash.algorithms_guaranteed)
```

--------------------------------

### Get Available Hash Algorithm Names

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/module-constants.md

Retrieve a set of all available hash algorithm names supported by the xxhash module. This is identical to `algorithms_guaranteed`.

```python
import xxhash
print(xxhash.algorithms_available)
```

--------------------------------

### Get xxh32 Digest Size

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh32.md

Retrieve the fixed digest size in bytes for the 32-bit hash. Both `digest_size` and `digestsize` properties are equivalent, with `digest_size` being preferred.

```python
import xxhash
h = xxhash.xxh32()
assert h.digest_size == 4
assert h.digestsize == 4
```

--------------------------------

### Get XXH64 Digest Size

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh64.md

Retrieve the fixed digest size in bytes for the XXH64 hash. Both `digest_size` and `digestsize` properties are available, with `digest_size` being preferred.

```python
import xxhash
h = xxhash.xxh64()
assert h.digest_size == 8
assert h.digestsize == 8
```

--------------------------------

### Get xxh64 Hash as Hex String

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh64.md

Returns the computed hash value as a lowercase hexadecimal string. The output is always 16 characters long.

```python
h = xxhash.xxh64(b'test')
hex_str = h.hexdigest()
# Output: 16-character hex string, e.g., 'ef46db3751d8e999'
```

--------------------------------

### Handling Common Gotchas

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/quick-reference.md

Illustrates correct and incorrect ways to hash strings, use seeds, and hash mutable objects. Highlights that different encodings result in different hashes.

```python
# ❌ Wrong: String directly
h = xxhash.xxh64("string")  # TypeError!

# ✅ Right: Encode string
h = xxhash.xxh64("string".encode())

# ❌ Wrong: Negative seed
h = xxhash.xxh64(seed=-1)  # OverflowError!

# ✅ Right: Non-negative seed
h = xxhash.xxh64(seed=0)

# ❌ Wrong: Hash mutable object without buffer protocol
h = xxhash.xxh64([1, 2, 3])  # TypeError!

# ✅ Right: Convert to bytes
h = xxhash.xxh64(bytes([1, 2, 3]))

# ✅ Note: Different encodings = different hashes
h1 = xxhash.xxh64('text'.encode('utf-8'))
h2 = xxhash.xxh64('text'.encode('utf-16'))
# h1.digest() != h2.digest()
```

--------------------------------

### One-Shot vs Streaming Hashing

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/usage-patterns.md

Illustrates the difference between one-shot hashing for small, complete data and streaming for chunked data using xxhash.

```python
import xxhash

# For small, complete data: use one-shot
small_hash = xxhash.xxh64_digest(b'small')

# For streaming/chunked data: use class
h = xxhash.xxh64()
h.update(chunk_1)
h.update(chunk_2)
result = h.digest()
```

--------------------------------

### Import xxhash Library

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/quick-reference.md

Import the xxhash library to use its hashing functionalities.

```python
import xxhash
```

--------------------------------

### Upgrade Python xxhash

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/installation-and-configuration.md

Use pip to upgrade your existing installation of the xxhash library to the latest version. You can also force a reinstallation or upgrade to a specific version.

```bash
# Upgrade existing installation
pip install --upgrade xxhash
```

```bash
# Force reinstall (useful if installation is broken)
pip install --force-reinstall --no-cache-dir xxhash
```

```bash
# Upgrade to specific version
pip install xxhash==3.8.0
```

--------------------------------

### Display Version Information

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/quick-reference.md

Prints the versions of Python, python-xxhash, the xxHash C library, and lists available algorithms.

```python
import xxhash
import sys

print(f"Python: {sys.version}")
print(f"python-xxhash: {xxhash.VERSION}")
print(f"xxHash C library: {xxhash.XXHASH_VERSION}")
print(f"Available algorithms: {xxhash.algorithms_available}")
```

--------------------------------

### Get XXH64 Seed

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh64.md

Retrieve the unsigned 64-bit seed used during the construction of the XXH64 hash object. Seeds exceeding the 2^64 range wrap around.

```python
import xxhash
h1 = xxhash.xxh64(seed=0)
assert h1.seed == 0

h2 = xxhash.xxh64(seed=2**64)
assert h2.seed == 0  # wraps

h3 = xxhash.xxh64(seed=2**64 + 1)
assert h3.seed == 1  # wraps
```

--------------------------------

### Get xxh64 Hash as Bytes

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/api-reference-xxh64.md

Retrieves the computed hash value as a raw bytes object in big-endian representation. The digest size is always 8 bytes.

```python
h = xxhash.xxh64(b'test')
raw = h.digest()
# Output: bytes of length 8, e.g., b'\xefF\xdb7Q\xd8\xe9\x99'
```

--------------------------------

### Instance Methods (All Hashers)

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/README.md

Common methods available on all hasher instances for incremental hashing operations.

```APIDOC
## Instance Methods (All Hashers)

### `update(data)`

- **Description**: Appends data to the hasher's internal state.
- **Parameters**:
  - `data` (_Buffer_): The data to append.

### `digest()`

- **Description**: Returns the computed hash as a binary digest (big-endian).
- **Returns**: bytes - The binary hash.

### `hexdigest()`

- **Description**: Returns the computed hash as a hexadecimal string.
- **Returns**: str - The hexadecimal hash string.

### `intdigest()`

- **Description**: Returns the computed hash as an integer.
- **Returns**: int - The integer hash.

### `copy()`

- **Description**: Creates a copy of the hasher's current state.
- **Returns**: Hasher - A new hasher instance with the same state.

### `reset()`

- **Description**: Resets the hasher to its initial empty state.
```

--------------------------------

### Get xxhash and XXHASH library versions

Source: https://github.com/ifduyue/python-xxhash/blob/master/README.rst

Retrieve the version of the xxhash Python module and the version of the backend xxHash C library using module properties.

```python
import xxhash
xxhash.VERSION
xxhash.XXHASH_VERSION
```

--------------------------------

### xxh32 Output Formats

Source: https://github.com/ifduyue/python-xxhash/blob/master/_autodocs/algorithm-comparison.md

Demonstrates how to obtain the hash digest in binary, hexadecimal, and integer formats using xxh32. Ensure data is in bytes.

```python
import xxhash

data = b'test'

# Binary (big-endian)
h = xxhash.xxh32(data)
digest = h.digest()
assert len(digest) == 4

# Hexadecimal (8 characters)
hex_str = h.hexdigest()
assert len(hex_str) == 8

# Integer
int_val = h.intdigest()
assert 0 <= int_val < 2**32
```