clandestined

library1.1.0pypypiunverified

Clandestined is a Python library that implements rendezvous hashing, also known as highest random weight (HRW) hashing. It provides a distributed algorithm for choosing a node from a set of available nodes, ensuring that a minimal number of mappings change when nodes are added or removed. It's built upon the murmur3 hash function. The current version is 1.1.0, and the project's release cadence has been infrequent since its last update in 2016.

database http-networking devops

pip install clandestined

github ↗package ↗

INSTALL

IMPORT

SIG · CLANDESTINED

clandestined

databasepythonv1.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 10

Env Coverage0 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v? · pip install

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.95 runs

build_error

glibc

py 3.10–3.95 runs

build_error

Code

Verified usage

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

RendezvousHash

✓ from clandestined import RendezvousHash

Cluster

✓ from clandestined import Cluster

This quickstart demonstrates how to initialize `RendezvousHash` with a set of nodes, find the responsible node for a given key, and dynamically add or remove nodes while maintaining consistent hashing properties.

from clandestined import RendezvousHash # Initialize with a list of node IDs rh = RendezvousHash(['node-a', 'node-b', 'node-c']) # Find the appropriate node for a given key key_to_hash = 'user_session_123' assigned_node = rh.find_node(key_to_hash) print(f"Key '{key_to_hash}' assigned to: {assigned_node}") # Add a new node rh.add_node('node-d') new_assigned_node = rh.find_node(key_to_hash) print(f"After adding node-d, key '{key_to_hash}' assigned to: {new_assigned_node}") # Remove a node rh.remove_node('node-a') final_assigned_node = rh.find_node(key_to_hash) print(f"After removing node-a, key '{key_to_hash}' assigned to: {final_assigned_node}")

Debug

Known issues

breakingThe `murmur_seed` keyword argument for `Cluster` and `RendezvousHash` constructors was renamed to `seed`.

fix

Update constructor calls to use `seed=` instead of `murmur_seed=`.

affects: <1.0.0b

breakingCalling `Cluster.remove_zone`, `Cluster.remove_node`, or `RendezvousHash.remove_node` with a non-existent ID now raises a `ValueError` instead of silently failing.

fix

Ensure that the node or zone ID exists before attempting to remove it, or wrap calls in a `try...except ValueError` block.

affects: <1.0.0b

breakingSupport for custom hash functions (passing a callable to `__init__`) was retracted for the 1.0.0 milestone.

fix

If custom hashing is required, consider forking the project or implementing rendezvous hashing manually, as the library no longer supports this feature directly.

affects: <1.0.0b

gotchaBehavior for hash collisions was updated in 1.0.0rc1. In the event of a hash collision between node IDs, the winner is now chosen by `max(str(node_id_1), str(node_id_2))`, providing a deterministic tie-breaking mechanism.

fix

Be aware of this deterministic tie-breaking when upgrading from pre-1.0.0rc1 versions, as it might slightly alter node assignments in rare collision scenarios.

affects: <1.0.0rc1

gotchaThe library's `requires_python` field is `UNKNOWN` on PyPI, and its last significant update was in 2016. While some Python 3 compatibility was added in 1.0.1, its compatibility with very modern Python versions (e.g., Python 3.9+) or complex environments might be limited due to the age of the codebase and its C extension (`_murmur3`).

fix

Thoroughly test in your target Python environment. Consider reviewing the source code for C extension compilation issues or Python 2-isms if encountering problems.

affects: All versions on newer Python interpreters

Errors

Common errors & fixes

TypeError: __init__() got an unexpected keyword argument 'murmur_seed'

The `murmur_seed` keyword argument for `Cluster` and `RendezvousHash` constructors was renamed to `seed` in version 1.0.0.

fix

Update constructor calls to use `seed=` instead of `murmur_seed=`.

ValueError: Node with ID '<node_id>' does not exist.

Calling `Cluster.remove_zone`, `Cluster.remove_node`, or `RendezvousHash.remove_node` with a non-existent ID now raises a `ValueError` instead of silently failing since version 1.0.0.

fix

Ensure that the node or zone ID exists before attempting to remove it, or wrap the call in a `try...except ValueError` block.

TypeError: RendezvousHash.__init__() got an unexpected keyword argument 'hash_func'

Support for passing custom hash functions (as a callable to `__init__`) was retracted for the 1.0.0 milestone.

fix

The library no longer supports custom hash functions directly. Consider forking the project or implementing rendezvous hashing manually if custom hashing is required.

ModuleNotFoundError: No module named 'clandestined'

The `clandestined` library or its underlying C extension (`_murmur3`) failed to install correctly, possibly due to compatibility issues with modern Python versions (e.g., Python 3.9+) or complex environments, as the library's `requires_python` field is `UNKNOWN` on PyPI and its last significant update was in 2016.

fix

Verify that `clandestined` is installed (`pip show clandestined`). If installation issues persist, ensure your Python environment is compatible (e.g., try with slightly older Python 3.x versions if using a very new one), check compiler tools are available for the C extension, or review the source code for C extension compilation problems.

Upgrade

Version history

1.1.0latest on PyPI · released Jun 1, 2023

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/ewdurbin/clandestined-python ↗

packagehttps://pypi.org/project/clandestined/ ↗