0
# Flask-Redis
1

2
A Flask extension that integrates Redis functionality into Flask applications through a simple and elegant interface. Flask-Redis acts as a wrapper around the redis-py library, providing automatic Flask configuration management, support for custom Redis providers, and seamless integration with Flask's application factory pattern.
3

4
## Package Information
5

6
- **Package Name**: flask-redis
7
- **Language**: Python
8
- **Installation**: `pip install flask-redis`
9
- **Dependencies**: Flask>=0.8, redis>=2.7.6
10
- **Python Support**: Python 2.7, 3.5+
11

12
## Core Imports
13

14
```python
15
from flask_redis import FlaskRedis
16
```
17

18
## Basic Usage
19

20
```python
21
from flask import Flask
22
from flask_redis import FlaskRedis
23

24
# Method 1: Direct instantiation with app
25
app = Flask(__name__)
26
app.config['REDIS_URL'] = 'redis://localhost:6379/0'
27
redis_client = FlaskRedis(app)
28

29
# Method 2: Application factory pattern
30
redis_client = FlaskRedis()
31

32
def create_app():
33
    app = Flask(__name__)
34
    app.config['REDIS_URL'] = 'redis://localhost:6379/0'
35
    redis_client.init_app(app)
36
    return app
37

38
# Using Redis operations
39
@app.route('/')
40
def index():
41
    redis_client.set('key', 'value')
42
    return redis_client.get('key')
43
```
44

45
## Capabilities
46

47
### Flask Extension Class
48

49
The main FlaskRedis class that provides Redis integration for Flask applications.
50

51
```python { .api }
52
class FlaskRedis:
53
    def __init__(self, app=None, strict=True, config_prefix='REDIS', **kwargs):
54
        """
55
        Initialize FlaskRedis extension.
56
        
57
        Parameters:
58
        - app: Flask application instance (optional)
59
        - strict: Use StrictRedis (True, default) or Redis (False) client. 
60
                  In modern redis-py versions, both point to the same Redis class.
61
        - config_prefix: Prefix for Flask configuration variables (default: 'REDIS')
62
        - **kwargs: Additional arguments passed to Redis client constructor
63
        """
64
    
65
    def init_app(self, app, **kwargs):
66
        """
67
        Initialize the extension with a Flask application.
68
        
69
        Parameters:
70
        - app: Flask application instance
71
        - **kwargs: Additional arguments for Redis client
72
        """
73
    
74
    @classmethod
75
    def from_custom_provider(cls, provider, app=None, **kwargs):
76
        """
77
        Create FlaskRedis instance with custom Redis provider.
78
        
79
        Parameters:
80
        - provider: Custom Redis client class (e.g., MockRedis)
81
        - app: Flask application instance (optional)
82
        - **kwargs: Additional arguments
83
        
84
        Returns:
85
        FlaskRedis instance configured with custom provider
86
        """
87
    
88
    def __getattr__(self, name):
89
        """
90
        Delegate attribute access to the underlying Redis client.
91
        
92
        Parameters:
93
        - name: Attribute name to access
94
        
95
        Returns:
96
        Value from the underlying Redis client
97
        """
98
    
99
    def __getitem__(self, name):
100
        """
101
        Delegate item access to the underlying Redis client.
102
        
103
        Parameters:
104
        - name: Key to access
105
        
106
        Returns:
107
        Value from Redis client using item access
108
        """
109
    
110
    def __setitem__(self, name, value):
111
        """
112
        Delegate item assignment to the underlying Redis client.
113
        
114
        Parameters:
115
        - name: Key to set
116
        - value: Value to assign
117
        """
118
    
119
    def __delitem__(self, name):
120
        """
121
        Delegate item deletion to the underlying Redis client.
122
        
123
        Parameters:
124
        - name: Key to delete
125
        """
126
```
127

128
### Redis Client Access
129

130
Flask-Redis provides transparent access to all redis-py client methods through delegation. All methods from the redis-py library are available directly on the FlaskRedis instance.
131

132
```python { .api }
133
# String operations
134
redis_client.set(name, value, ex=None, px=None, nx=False, xx=False)
135
redis_client.get(name)
136
redis_client.getset(name, value)
137
redis_client.incr(name, amount=1)
138
redis_client.decr(name, amount=1)
139

140
# Key operations  
141
redis_client.delete(*names)
142
redis_client.exists(*names)
143
redis_client.expire(name, time)
144
redis_client.ttl(name)
145
redis_client.keys(pattern='*')
146

147
# Hash operations
148
redis_client.hget(name, key)
149
redis_client.hset(name, key, value)
150
redis_client.hgetall(name)
151
redis_client.hdel(name, *keys)
152
redis_client.hkeys(name)
153

154
# List operations
155
redis_client.lpush(name, *values)
156
redis_client.rpush(name, *values)
157
redis_client.lpop(name)
158
redis_client.rpop(name)
159
redis_client.llen(name)
160
redis_client.lrange(name, start, end)
161

162
# Set operations
163
redis_client.sadd(name, *values)
164
redis_client.smembers(name)
165
redis_client.srem(name, *values)
166
redis_client.scard(name)
167

168
# Pub/Sub operations
169
redis_client.publish(channel, message)
170
redis_client.pubsub()
171

172
# Transaction operations
173
redis_client.pipeline()
174
redis_client.multi()
175
redis_client.exec()
176

177
# Magic methods also support item-style access
178
redis_client['key'] = 'value'  # Uses __setitem__
179
value = redis_client['key']    # Uses __getitem__
180
del redis_client['key']        # Uses __delitem__
181
```
182

183
### Configuration
184

185
Flask-Redis uses Flask's configuration system with customizable prefixes.
186

187
```python { .api }
188
# Default configuration key
189
REDIS_URL = 'redis://localhost:6379/0'
190

191
# With custom prefix
192
app.config['CUSTOM_PREFIX_URL'] = 'redis://localhost:6379/1'
193
redis_client = FlaskRedis(app, config_prefix='CUSTOM_PREFIX')
194

195
# Unix socket connections
196
REDIS_URL = 'unix://:password@/path/to/socket.sock?db=0'
197
```
198

199
## Advanced Usage
200

201
### Multiple Redis Instances
202

203
```python
204
from flask import Flask
205
from flask_redis import FlaskRedis
206

207
app = Flask(__name__)
208
app.config['REDIS_URL'] = 'redis://localhost:6379/0'
209
app.config['CACHE_URL'] = 'redis://localhost:6379/1'
210

211
# Default instance
212
redis_store = FlaskRedis(app)
213

214
# Cache instance with custom prefix
215
redis_cache = FlaskRedis(app, config_prefix='CACHE')
216
```
217

218
### Testing with MockRedis
219

220
```python
221
from flask import Flask
222
from flask_redis import FlaskRedis
223
from mockredis import MockRedis
224

225
def create_app():
226
    app = Flask(__name__)
227
    
228
    if app.testing:
229
        redis_store = FlaskRedis.from_custom_provider(MockRedis)
230
    else:
231
        redis_store = FlaskRedis()
232
    
233
    redis_store.init_app(app)
234
    return app
235
```
236

237
### Extension Integration
238

239
Flask-Redis automatically registers itself in Flask's extensions system using the lowercase version of the config prefix as the extension key:
240

241
```python
242
# Access through app.extensions
243
app = Flask(__name__)
244
redis_client = FlaskRedis(app)
245

246
# The extension is available as app.extensions['redis'] (lowercase of 'REDIS' prefix)
247
assert app.extensions['redis'] is redis_client
248

249
# With custom prefix 'CACHE', extension key becomes 'cache'
250
redis_cache = FlaskRedis(app, config_prefix='CACHE')
251
assert app.extensions['cache'] is redis_cache
252

253
# Multiple instances with different prefixes
254
app.config['SESSION_URL'] = 'redis://localhost:6379/2'
255
session_store = FlaskRedis(app, config_prefix='SESSION')
256
assert app.extensions['session'] is session_store
257
```
258

259
## Error Handling
260

261
Flask-Redis handles missing redis-py dependency gracefully when using custom providers:
262

263
```python
264
# This works even if redis-py is not installed
265
redis_store = FlaskRedis.from_custom_provider(MockRedis, app)
266

267
# This will raise ImportError if redis-py is not installed
268
redis_store = FlaskRedis(app)  # Requires redis-py
269
```
270

271
The extension raises AssertionError if a None provider is passed to `from_custom_provider()`:
272

273
```python
274
# This will raise AssertionError
275
FlaskRedis.from_custom_provider(None, app)
276
```