0
# Redis-py-cluster
1

2
A Python client library for Redis Cluster that provides cluster-aware implementations of Redis commands with automatic slot management, node discovery, failover support, and connection pooling. Built on top of the redis-py library, it extends standard Redis functionality to work seamlessly with Redis Cluster's distributed architecture.
3

4
## Package Information
5

6
- **Package Name**: redis-py-cluster
7
- **Language**: Python
8
- **Installation**: `pip install redis-py-cluster`
9

10
## Core Imports
11

12
```python
13
from rediscluster import RedisCluster
14
```
15

16
All public components:
17

18
```python
19
from rediscluster import (
20
    RedisCluster,
21
    ClusterConnection,
22
    ClusterConnectionPool,
23
    ClusterBlockingConnectionPool,
24
    ClusterPipeline,
25
    RedisClusterException,
26
    RedisClusterError,
27
    ClusterDownException,
28
    ClusterDownError,
29
    ClusterCrossSlotError,
30
    MovedError,
31
    AskError,
32
    TryAgainError,
33
    MasterDownError
34
)
35
```
36

37
## Basic Usage
38

39
```python
40
from rediscluster import RedisCluster
41

42
# Connect to Redis Cluster
43
startup_nodes = [{"host": "127.0.0.1", "port": "7000"}]
44
rc = RedisCluster(startup_nodes=startup_nodes, decode_responses=True)
45

46
# Execute standard Redis commands
47
rc.set("key", "value")
48
result = rc.get("key")
49

50
# Multi-key operations work across cluster nodes
51
rc.mset({"key1": "value1", "key2": "value2", "key3": "value3"})
52
values = rc.mget(["key1", "key2", "key3"])
53

54
# Pipeline operations
55
pipe = rc.pipeline()
56
pipe.set("pkey1", "pvalue1")
57
pipe.get("pkey1")
58
pipe.incr("counter")
59
results = pipe.execute()
60

61
# Cluster management
62
cluster_info = rc.cluster_info()
63
nodes = rc.cluster_nodes()
64
```
65

66
## Architecture
67

68
Redis-py-cluster extends redis-py with cluster-aware functionality:
69

70
- **RedisCluster**: Main client extending Redis class with cluster-specific command implementations
71
- **NodeManager**: Manages cluster topology discovery and slot-to-node mapping
72
- **Connection Pools**: Per-node connection pooling with automatic failover
73
- **Pipeline**: Cluster-aware command batching with proper node routing
74
- **Exception Handling**: Cluster-specific errors like MOVED/ASK redirections
75

76
The library automatically handles Redis Cluster's 16,384 hash slots, discovers node topology, manages failover scenarios, and routes commands to appropriate nodes while maintaining the familiar redis-py API.
77

78
## Capabilities
79

80
### Redis Cluster Client
81

82
The primary interface for interacting with Redis clusters, providing all standard Redis operations with cluster-aware implementations and additional cluster management commands.
83

84
```python { .api }
85
class RedisCluster(Redis):
86
    def __init__(self, host=None, port=None, startup_nodes=None, 
87
                 max_connections=None, max_connections_per_node=False,
88
                 init_slot_cache=True, readonly_mode=False, 
89
                 reinitialize_steps=None, skip_full_coverage_check=False,
90
                 nodemanager_follow_cluster=False, connection_class=None,
91
                 read_from_replicas=False, cluster_down_retry_attempts=3,
92
                 host_port_remap=None, **kwargs)
93
    
94
    @classmethod
95
    def from_url(cls, url, **kwargs): ...
96
    
97
    def pubsub(self, **kwargs): ...
98
    def pipeline(self, transaction=None, shard_hint=None, read_from_replicas=False): ...
99
    def execute_command(self, *args, **kwargs): ...
100
```
101

102
[Redis Cluster Client](./client.md)
103

104
### Connection Management
105

106
Connection classes and pools for managing TCP/SSL connections to cluster nodes with automatic discovery, load balancing, and failover support.
107

108
```python { .api }
109
class ClusterConnection(Connection):
110
    def __init__(self, readonly=False, **kwargs): ...
111

112
class ClusterConnectionPool(ConnectionPool):
113
    def __init__(self, startup_nodes=None, init_slot_cache=True,
114
                 connection_class=None, max_connections=None,
115
                 max_connections_per_node=False, **kwargs): ...
116
    
117
    def get_connection_by_node(self, node): ...
118
    def get_connection_by_slot(self, slot): ...
119
```
120

121
[Connection Management](./connections.md)
122

123
### Cluster Pipeline
124

125
Cluster-aware pipeline for batching commands with automatic routing to appropriate nodes while respecting Redis Cluster constraints.
126

127
```python { .api }
128
class ClusterPipeline(RedisCluster):
129
    def __init__(self, connection_pool, result_callbacks=None,
130
                 response_callbacks=None, startup_nodes=None,
131
                 read_from_replicas=False, cluster_down_retry_attempts=3): ...
132
    
133
    def execute_command(self, *args, **kwargs): ...
134
    def execute(self, raise_on_error=True): ...
135
    def reset(self): ...
136
```
137

138
[Cluster Pipeline](./pipeline.md)
139

140
### Exception Handling
141

142
Comprehensive exception classes for handling cluster-specific errors, redirections, and failure scenarios.
143

144
```python { .api }
145
class RedisClusterException(Exception): ...
146
class ClusterDownError(ClusterError, ResponseError): ...
147
class MovedError(AskError): ...
148
class AskError(ResponseError):
149
    def __init__(self, resp): ...
150
    # Properties: slot_id, host, port, node_addr, message
151
```
152

153
[Exception Handling](./exceptions.md)
154

155
### Cluster Pub/Sub
156

157
Cluster-aware publish/subscribe functionality for message broadcasting and real-time communication across cluster nodes.
158

159
```python { .api }
160
class ClusterPubSub(PubSub):
161
    def __init__(self, connection_pool, shard_hint=None, ignore_subscribe_messages=False): ...
162
    def execute_command(self, *args, **kwargs): ...
163
    def subscribe(self, *args, **kwargs): ...
164
    def psubscribe(self, *args, **kwargs): ...
165
    def get_message(self, timeout=0, ignore_subscribe_messages=False): ...
166
    def listen(self): ...
167
```
168

169
[Cluster Pub/Sub](./pubsub.md)
170

171
## Types
172

173
```python { .api }
174
# Startup node specification
175
StartupNode = TypedDict('StartupNode', {
176
    'host': str,
177
    'port': Union[str, int]
178
})
179

180
# Host/port remapping configuration  
181
HostPortRemap = Dict[Tuple[str, int], Tuple[str, int]]
182

183
# Node information from cluster
184
NodeInfo = Dict[str, Union[str, int, List[int]]]
185

186
# Cluster slots mapping
187
SlotsMapping = List[List[Union[int, List[Union[str, int]]]]]
188
```