0
# Core Redis Clients
1

2
Main client classes that provide drop-in replacements for redis-py clients with full Redis command compatibility and server emulation. These clients support all Redis operations while maintaining complete API compatibility with the redis-py library.
3

4
## Capabilities
5

6
### Synchronous Redis Client
7

8
The primary Redis client class that inherits from `redis.Redis` and provides a complete fake Redis implementation.
9

10
```python { .api }
11
class FakeRedis(redis.Redis):
12
    def __init__(
13
        self,
14
        host: str = "localhost",
15
        port: int = 6379,
16
        db: int = 0,
17
        password: Optional[str] = None,
18
        socket_timeout: Optional[float] = None,
19
        socket_connect_timeout: Optional[float] = None,
20
        socket_keepalive: bool = False,
21
        socket_keepalive_options: Optional[Dict[str, Any]] = None,
22
        connection_pool: Optional[ConnectionPool] = None,
23
        unix_domain_socket_path: Optional[str] = None,
24
        encoding: str = "utf-8",
25
        encoding_errors: str = "strict",
26
        charset: Optional[str] = None,
27
        errors: Optional[str] = None,
28
        decode_responses: bool = False,
29
        retry_on_timeout: bool = False,
30
        retry_on_error: Optional[List[Exception]] = None,
31
        ssl: bool = False,
32
        ssl_keyfile: Optional[str] = None,
33
        ssl_certfile: Optional[str] = None,
34
        ssl_cert_reqs: Optional[str] = None,
35
        ssl_ca_certs: Optional[str] = None,
36
        ssl_ca_data: Optional[str] = None,
37
        ssl_check_hostname: bool = False,
38
        max_connections: Optional[int] = None,
39
        single_connection_client: bool = False,
40
        health_check_interval: int = 0,
41
        client_name: Optional[str] = None,
42
        username: Optional[str] = None,
43
        retry: Optional[Retry] = None,
44
        redis_connect_func: Optional[Callable] = None,
45
        credential_provider: Optional[CredentialProvider] = None,
46
        protocol: int = 2,
47
        # FakeRedis-specific parameters
48
        server: Optional[FakeServer] = None,
49
        version: VersionType = (7,),
50
        server_type: ServerType = "redis",
51
        lua_modules: Optional[Dict[str, Any]] = None,
52
        **kwargs
53
    ): ...
54
    
55
    @classmethod
56
    def from_url(
57
        cls,
58
        url: str,
59
        encoding: str = "utf-8",
60
        encoding_errors: str = "strict",
61
        decode_responses: bool = False,
62
        **kwargs
63
    ) -> Self: ...
64
```
65

66
### Asynchronous Redis Client
67

68
The async Redis client class that inherits from `redis.asyncio.Redis` and provides full async/await support for all Redis operations.
69

70
```python { .api }
71
class FakeAsyncRedis(redis.asyncio.Redis):
72
    def __init__(
73
        self,
74
        host: str = "localhost", 
75
        port: int = 6379,
76
        db: int = 0,
77
        password: Optional[str] = None,
78
        socket_timeout: Optional[float] = None,
79
        socket_connect_timeout: Optional[float] = None,
80
        socket_keepalive: bool = False,
81
        socket_keepalive_options: Optional[Dict[str, Any]] = None,
82
        connection_pool: Optional[ConnectionPool] = None,
83
        unix_domain_socket_path: Optional[str] = None,
84
        encoding: str = "utf-8",
85
        encoding_errors: str = "strict",
86
        charset: Optional[str] = None,
87
        errors: Optional[str] = None,
88
        decode_responses: bool = False,
89
        retry_on_timeout: bool = False,
90
        retry_on_error: Optional[List[Exception]] = None,
91
        ssl: bool = False,
92
        ssl_keyfile: Optional[str] = None,
93
        ssl_certfile: Optional[str] = None,
94
        ssl_cert_reqs: Optional[str] = None,
95
        ssl_ca_certs: Optional[str] = None,
96
        ssl_ca_data: Optional[str] = None,
97
        ssl_check_hostname: bool = False,
98
        max_connections: Optional[int] = None,
99
        single_connection_client: bool = False,
100
        health_check_interval: int = 0,
101
        client_name: Optional[str] = None,
102
        username: Optional[str] = None,
103
        retry: Optional[Retry] = None,
104
        redis_connect_func: Optional[Callable] = None,
105
        credential_provider: Optional[CredentialProvider] = None,
106
        protocol: int = 2,
107
        # FakeAsyncRedis-specific parameters
108
        server: Optional[FakeServer] = None,
109
        version: VersionType = (7,),
110
        server_type: ServerType = "redis",
111
        lua_modules: Optional[Dict[str, Any]] = None,
112
        **kwargs
113
    ): ...
114
    
115
    @classmethod
116
    def from_url(
117
        cls,
118
        url: str,
119
        encoding: str = "utf-8",
120
        encoding_errors: str = "strict",
121
        decode_responses: bool = False,
122
        **kwargs
123
    ) -> Self: ...
124
```
125

126
### Strict Redis Client
127

128
Backward-compatible Redis client that provides stricter Redis protocol adherence.
129

130
```python { .api }
131
class FakeStrictRedis(redis.StrictRedis):
132
    def __init__(
133
        self,
134
        server: Optional[FakeServer] = None,
135
        version: VersionType = (7,),
136
        server_type: ServerType = "redis",
137
        lua_modules: Optional[Dict[str, Any]] = None,
138
        **kwargs
139
    ): ...
140
    
141
    @classmethod
142
    def from_url(
143
        cls,
144
        url: str,
145
        encoding: str = "utf-8",
146
        encoding_errors: str = "strict",
147
        decode_responses: bool = False,
148
        **kwargs
149
    ) -> Self: ...
150
```
151

152
### Connection Classes
153

154
Low-level connection classes that handle the Redis protocol communication.
155

156
```python { .api }
157
class FakeConnection(redis.Connection):
158
    def __init__(
159
        self,
160
        host: str = "localhost",
161
        port: int = 6379,
162
        db: int = 0,
163
        password: Optional[str] = None,
164
        socket_timeout: Optional[float] = None,
165
        socket_connect_timeout: Optional[float] = None,
166
        socket_keepalive: bool = False,
167
        socket_keepalive_options: Optional[Dict[str, Any]] = None,
168
        socket_type: int = 0,
169
        redis_connect_func: Optional[Callable] = None,
170
        encoder: Optional[Encoder] = None,
171
        # FakeConnection-specific parameters
172
        server: Optional[FakeServer] = None,
173
        **kwargs
174
    ): ...
175
    
176
    def connect(self) -> None: ...
177
    def disconnect(self) -> None: ...
178
    def can_read(self, timeout: Optional[float] = 0) -> bool: ...
179
    def read_response(self, **kwargs: Any) -> Any: ...
180
    def send_command(self, *args: Any) -> None: ...
181
    def send_packed_command(self, command: bytes) -> None: ...
182

183
class FakeAsyncConnection(redis.asyncio.Connection):
184
    def __init__(
185
        self,
186
        host: str = "localhost",
187
        port: int = 6379,
188
        db: int = 0,
189
        password: Optional[str] = None,
190
        socket_timeout: Optional[float] = None,
191
        socket_connect_timeout: Optional[float] = None,
192
        socket_keepalive: bool = False,
193
        socket_keepalive_options: Optional[Dict[str, Any]] = None,
194
        socket_type: int = 0,
195
        redis_connect_func: Optional[Callable] = None,
196
        encoder: Optional[Encoder] = None,
197
        # FakeAsyncConnection-specific parameters
198
        server: Optional[FakeServer] = None,
199
        **kwargs
200
    ): ...
201
    
202
    async def connect(self) -> None: ...
203
    async def disconnect(self) -> None: ...
204
    async def can_read(self, timeout: Optional[float] = 0) -> bool: ...
205
    async def read_response(self, **kwargs: Any) -> Any: ...
206
    async def send_command(self, *args: Any) -> None: ...
207
    async def send_packed_command(self, command: bytes) -> None: ...
208
```
209

210
## Usage Examples
211

212
### Basic Client Usage
213

214
```python
215
import fakeredis
216

217
# Create a basic FakeRedis client
218
client = fakeredis.FakeRedis()
219

220
# Perform operations
221
client.set('key', 'value')
222
result = client.get('key')
223
print(result.decode())  # 'value'
224
```
225

226
### Shared Server Instance
227

228
```python
229
import fakeredis
230

231
# Create a shared server
232
server = fakeredis.FakeServer()
233

234
# Create multiple clients sharing the same server
235
client1 = fakeredis.FakeRedis(server=server)
236
client2 = fakeredis.FakeRedis(server=server)
237

238
# Operations from both clients affect the same data
239
client1.set('shared_key', 'value')
240
result = client2.get('shared_key')  # Same server, same data
241
```
242

243
### Async Client Usage
244

245
```python
246
import asyncio
247
import fakeredis
248

249
async def async_operations():
250
    # Create async client
251
    client = fakeredis.FakeAsyncRedis()
252
    
253
    # Perform async operations
254
    await client.set('async_key', 'async_value')
255
    result = await client.get('async_key')
256
    print(result.decode())  # 'async_value'
257
    
258
    # Use with context manager
259
    async with client.pipeline() as pipe:
260
        pipe.set('key1', 'value1')
261
        pipe.set('key2', 'value2')
262
        results = await pipe.execute()
263

264
# Run the async function
265
asyncio.run(async_operations())
266
```
267

268
### URL-based Configuration
269

270
```python
271
import fakeredis
272

273
# Create client from URL (works with both sync and async)
274
client = fakeredis.FakeRedis.from_url(
275
    'redis://localhost:6379/0',
276
    decode_responses=True
277
)
278

279
# Redis URL with authentication  
280
authenticated_client = fakeredis.FakeRedis.from_url(
281
    'redis://username:password@localhost:6379/1'
282
)
283
```
284

285
### Version and Server Type Configuration
286

287
```python
288
import fakeredis
289

290
# Configure for specific Redis version
291
redis_6_client = fakeredis.FakeRedis(version=(6, 2))
292
redis_7_client = fakeredis.FakeRedis(version=(7, 0))
293

294
# Configure for different server types
295
dragonfly_client = fakeredis.FakeRedis(server_type="dragonfly")
296
valkey_client = fakeredis.FakeRedis(server_type="valkey")  # If valkey support available
297
```
298

299
### Custom Lua Modules
300

301
```python
302
import fakeredis
303

304
# Load custom Lua modules
305
lua_modules = {
306
    'mymodule': '''
307
        local function my_function(key, value)
308
            redis.call("SET", key, value)
309
            return "OK"
310
        end
311
        return {my_function = my_function}
312
    '''
313
}
314

315
client = fakeredis.FakeRedis(lua_modules=lua_modules)
316
```