Registry / database / clickhouse-cityhash

clickhouse-cityhash

library1.0.2.5pypypiunverified

clickhouse-cityhash provides Python bindings for a specific, older version of Google's CityHash algorithm (v1.0.2). This library is primarily used to ensure compatibility with ClickHouse servers, which internally use this particular CityHash version for various hashing operations, including data in its protocol. It is a fork of the broader `python-cityhash` library, specifically tailored for the ClickHouse ecosystem. The current version is 1.0.2.5, and it receives updates for compatibility and bug fixes.

database data

pip install clickhouse-cityhash

github ↗package ↗

INSTALL

IMPORT

SIG · CLICKHOUSE-CITYHAS

clickhouse-cityhash

databasepythonv1.0.2.5

Install

1.6s avg

Import

—

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.2.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 18.2MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.6s · import 0.000s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CityHash64

✓ from clickhouse_cityhash import CityHash64

✗ from clickhouse_cityhash import CityHash64

This quickstart demonstrates how to import and use the `CityHash64` and `CityHash128` functions. It highlights the crucial step of encoding Python strings to bytes before hashing, as CityHash operates on byte strings. It also shows how to hash integers consistently by converting them to a fixed-size byte representation.

from cityhash import CityHash64, CityHash128 data_string = 'hello world' data_bytes = data_string.encode('utf-8') hash64 = CityHash64(data_bytes) hash128 = CityHash128(data_bytes) print(f"CityHash64 for '{data_string}': {hash64}") print(f"CityHash128 for '{data_string}': {hash128}") # Hashing an integer (must be converted to bytes for consistent results) integer_data = 123456789 integer_bytes = integer_data.to_bytes(8, 'big') # 8 bytes for CityHash64 hash64_int = CityHash64(integer_bytes) print(f"CityHash64 for integer {integer_data}: {hash64_int}")

Debug

Known issues

breakingThis library implements CityHash v1.0.2. Modern versions of CityHash (and the general `python-cityhash` library) produce different hash values. This library is specifically for compatibility with ClickHouse's internal hashing, not for general-purpose latest CityHash usage.

fix

Always verify which CityHash version (and thus hash output) is expected by your downstream system. For general non-ClickHouse use cases, consider `python-cityhash` or `farmhash` which implement newer algorithms. Ensure consistent hashing across systems if comparing hash values.

affects: All versions

gotchaCityHash is a *non-cryptographic* hash function. It is optimized for speed and good distribution, but it is not designed to be collision-resistant against malicious input. Do NOT use it for security-sensitive applications like password storage, digital signatures, or integrity checks where adversarial input is possible.

fix

For cryptographic security requirements, use standard library `hashlib` functions (e.g., SHA256, Blake2b).

affects: All versions

gotchaCityHash functions operate strictly on byte strings (`bytes`), not Python unicode strings (`str`). Passing a `str` directly will result in a `TypeError` or incorrect results if Python implicitly attempts a conversion.

fix

Always explicitly encode strings to bytes using a consistent encoding (e.g., `my_string.encode('utf-8')`) before passing them to hashing functions.

affects: All versions

gotchaThis implementation of CityHash does not support incremental hashing. It is not suitable for hashing long data streams or data that arrives in chunks, as the entire input must be provided at once.

fix

For stream processing or incremental hashing needs, use a library that explicitly supports this feature (e.g., `MetroHash` or `xxHash`).

affects: All versions

gotchaWhen hashing integers, convert them to a fixed-size byte representation for consistent and reproducible results across different environments or Python versions. Variable-length byte representations can lead to inconsistent hashes.

fix

Convert integers to a fixed-size byte sequence: `integer_value.to_bytes(8, 'big')` (for 64-bit hash, adjust size and endianness as needed).

affects: All versions

Upgrade

Version history

1.0.2.5latest on PyPI · released Nov 7, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

39 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/xzkostyan/clickhouse-cityhash ↗

packagehttps://pypi.org/project/clickhouse-cityhash/ ↗