Hashring

1.5.1 · maintenance · verified Sat Apr 11

Hashring is a Python library that implements consistent hashing, primarily using MD5 as its hashing function. It's designed for distributed systems and caches to minimize the remapping of keys when nodes are added or removed from a ring. The current version is 1.5.1, but the project has a very low release cadence, with the last update in 2015.

Warnings

breaking The library internally uses MD5 as its hashing function. MD5 is cryptographically broken and is unsuitable for security-sensitive applications like password storage or digital signatures due to known collision vulnerabilities.
Fix: Avoid using this library for any security-critical hashing. For secure hashing, use Python's `hashlib` module with algorithms like SHA-256 or SHA3. Consider alternative consistent hashing libraries that allow custom, stronger hash functions.
deprecated The library's last release (1.5.1) was in April 2015. This indicates that the project is not actively maintained, which may lead to compatibility issues with newer Python versions and a lack of updates for performance or security enhancements.
Fix: For new projects or if active maintenance is crucial, consider using more current and actively maintained consistent hashing libraries such as `uhashring`.
gotcha This library (`hashring`) should not be confused with `uhashring`, another popular and more actively maintained consistent hashing library. While both provide similar functionality, they are distinct projects with different import paths and maintenance statuses.
Fix: Ensure you are installing and importing the correct library (`pip install hashring` for this library, `pip install uhashring` for the alternative). The import for this library is `from hash_ring import HashRing`, while for `uhashring` it's `from uhashring import HashRing`.
gotcha Python's built-in `hash()` function is non-deterministic across different interpreter runs for strings and other types due to hash randomization (a security feature). This makes it unsuitable for consistent hashing across processes or restarts. `hashring` uses MD5 for its consistent hashing, which is deterministic.
Fix: Do not attempt to replace `hashring`'s internal hashing with Python's built-in `hash()` if cross-process consistency is required. For deterministic (but not necessarily cryptographically secure) hashing, use functions from the `hashlib` module directly if you need a custom hashing strategy.

Install

pip install hashring Install with pip

Imports

HashRing
```
from hash_ring import HashRing
```

Quickstart

This quickstart demonstrates how to initialize a HashRing with a list of nodes and retrieve the assigned node for a given key. It also shows how to apply weights to nodes for uneven distribution.

from hash_ring import HashRing

# Define a list of nodes (e.g., server addresses)
nodes = ['server1.example.com', 'server2.example.com', 'server3.example.com']

# Create a consistent hash ring
ring = HashRing(nodes)

# Get the node responsible for a specific key
key = "user:12345:data"
assigned_node = ring.get_node(key)

print(f"Key '{key}' is assigned to node: {assigned_node}")

# Example with weights
weighted_nodes = {
    'server1.example.com': 1,
    'server2.example.com': 2, # server2 gets twice the weight
    'server3.example.com': 1
}
weighted_ring = HashRing(weighted_nodes)
assigned_node_weighted = weighted_ring.get_node(key)
print(f"Key '{key}' is assigned to weighted node: {assigned_node_weighted}")

view raw JSON →