0
# Storage Backends
1

2
Pluggable storage implementations for persisting cached HTTP responses. Hishel provides multiple storage backends for different use cases, from local file storage to distributed Redis and cloud-based S3 storage.
3

4
## Capabilities
5

6
### Base Storage Classes
7

8
Abstract base classes defining the storage interface for both synchronous and asynchronous operations.
9

10
```python { .api }
11
class BaseStorage:
12
    def __init__(self, *, serializer=None, ttl=None):
13
        """
14
        Initialize synchronous storage backend.
15
        
16
        Parameters:
17
        - serializer: Serializer for request/response data (defaults to JSONSerializer)
18
        - ttl: Time-to-live in seconds for cached responses
19
        """
20
    
21
    def store(self, key: str, response: Response, request: Request, metadata=None) -> None: ...
22
    def retrieve(self, key: str) -> tuple[Response, Request, Metadata] | None: ...
23
    def remove(self, key: str | Response) -> None: ...
24
    def update_metadata(self, key: str, response: Response, request: Request, metadata: Metadata) -> None: ...
25
    def close(self) -> None: ...
26

27
class AsyncBaseStorage:
28
    def __init__(self, *, serializer=None, ttl=None):
29
        """
30
        Initialize asynchronous storage backend.
31
        
32
        Parameters:
33
        - serializer: Serializer for request/response data (defaults to JSONSerializer)
34
        - ttl: Time-to-live in seconds for cached responses
35
        """
36
    
37
    async def store(self, key: str, response: Response, request: Request, metadata=None) -> None: ...
38
    async def retrieve(self, key: str) -> tuple[Response, Request, Metadata] | None: ...
39
    async def remove(self, key: str | Response) -> None: ...
40
    async def update_metadata(self, key: str, response: Response, request: Request, metadata: Metadata) -> None: ...
41
    async def aclose(self) -> None: ...
42
```
43

44
### File Storage
45

46
File-based storage that persists cached responses to the local filesystem.
47

48
```python { .api }
49
class FileStorage(BaseStorage):
50
    def __init__(self, *, serializer=None, base_path=None, ttl=None, check_ttl_every=60):
51
        """
52
        File-based storage backend.
53
        
54
        Parameters:
55
        - serializer: Serializer for data (defaults to JSONSerializer)
56
        - base_path: Directory path for cache files (defaults to .hishel_cache)
57
        - ttl: Time-to-live in seconds
58
        - check_ttl_every: Interval in seconds to check for expired files
59
        """
60

61
class AsyncFileStorage(AsyncBaseStorage):
62
    def __init__(self, *, serializer=None, base_path=None, ttl=None, check_ttl_every=60):
63
        """
64
        Async file-based storage backend.
65
        
66
        Parameters:
67
        - serializer: Serializer for data (defaults to JSONSerializer)
68
        - base_path: Directory path for cache files (defaults to .hishel_cache)
69
        - ttl: Time-to-live in seconds
70
        - check_ttl_every: Interval in seconds to check for expired files
71
        """
72
```
73

74
**Usage Examples:**
75

76
```python
77
from pathlib import Path
78
import hishel
79

80
# Default file storage
81
storage = hishel.FileStorage()
82

83
# Custom path and TTL
84
storage = hishel.FileStorage(
85
    base_path=Path("/tmp/my_cache"),
86
    ttl=3600,  # 1 hour
87
    check_ttl_every=300  # Check every 5 minutes
88
)
89

90
# Custom serializer
91
storage = hishel.FileStorage(
92
    serializer=hishel.PickleSerializer(),
93
    base_path=Path("./cache")
94
)
95

96
with hishel.CacheClient(storage=storage) as client:
97
    response = client.get("https://api.example.com/data")
98
```
99

100
### Redis Storage
101

102
Redis-based storage for distributed caching across multiple application instances.
103

104
```python { .api }
105
class RedisStorage(BaseStorage):
106
    def __init__(self, *, client=None, serializer=None, ttl=None, namespace="hishel"):
107
        """
108
        Redis-based storage backend.
109
        
110
        Parameters:
111
        - client: Redis client instance (creates default if None)
112
        - serializer: Serializer for data (defaults to JSONSerializer)
113
        - ttl: Time-to-live in seconds
114
        - namespace: Redis key namespace prefix
115
        """
116

117
class AsyncRedisStorage(AsyncBaseStorage):
118
    def __init__(self, *, client=None, serializer=None, ttl=None, namespace="hishel"):
119
        """
120
        Async Redis-based storage backend.
121
        
122
        Parameters:
123
        - client: Async Redis client instance (creates default if None)
124
        - serializer: Serializer for data (defaults to JSONSerializer)
125
        - ttl: Time-to-live in seconds
126
        - namespace: Redis key namespace prefix
127
        """
128
```
129

130
**Usage Examples:**
131

132
```python
133
import redis
134
import hishel
135

136
# Default Redis storage (connects to localhost:6379)
137
storage = hishel.RedisStorage()
138

139
# Custom Redis client
140
redis_client = redis.Redis(
141
    host='cache.example.com',
142
    port=6380,
143
    password='secret',
144
    db=1
145
)
146
storage = hishel.RedisStorage(
147
    client=redis_client,
148
    ttl=7200,  # 2 hours
149
    namespace="myapp_cache"
150
)
151

152
with hishel.CacheClient(storage=storage) as client:
153
    response = client.get("https://api.example.com/data")
154
```
155

156
### SQLite Storage
157

158
SQLite-based storage for persistent local caching with SQL query capabilities.
159

160
```python { .api }
161
class SQLiteStorage(BaseStorage):
162
    def __init__(self, *, connection=None, serializer=None, ttl=None, 
163
                 table_name="cache", create_table=True):
164
        """
165
        SQLite-based storage backend.
166
        
167
        Parameters:
168
        - connection: SQLite connection (creates in-memory if None)
169
        - serializer: Serializer for data (defaults to JSONSerializer)
170
        - ttl: Time-to-live in seconds
171
        - table_name: Database table name for cache
172
        - create_table: Whether to create table if it doesn't exist
173
        """
174

175
class AsyncSQLiteStorage(AsyncBaseStorage):
176
    def __init__(self, *, connection=None, serializer=None, ttl=None,
177
                 table_name="cache", create_table=True):
178
        """
179
        Async SQLite-based storage backend.
180
        
181
        Parameters:
182
        - connection: Async SQLite connection (creates in-memory if None)
183
        - serializer: Serializer for data (defaults to JSONSerializer)
184
        - ttl: Time-to-live in seconds
185
        - table_name: Database table name for cache
186
        - create_table: Whether to create table if it doesn't exist
187
        """
188
```
189

190
**Usage Examples:**
191

192
```python
193
import sqlite3
194
import hishel
195

196
# Default SQLite storage (in-memory)
197
storage = hishel.SQLiteStorage()
198

199
# File-based SQLite
200
import sqlite3
201
conn = sqlite3.connect("cache.db")
202
storage = hishel.SQLiteStorage(
203
    connection=conn,
204
    table_name="http_cache",
205
    ttl=86400  # 24 hours
206
)
207

208
with hishel.CacheClient(storage=storage) as client:
209
    response = client.get("https://api.example.com/data")
210
```
211

212
### In-Memory Storage
213

214
Fast in-memory storage with LRU eviction for high-performance caching within a single process.
215

216
```python { .api }
217
class InMemoryStorage(BaseStorage):
218
    def __init__(self, *, capacity=128, serializer=None, ttl=None):
219
        """
220
        In-memory storage backend with LRU eviction.
221
        
222
        Parameters:
223
        - capacity: Maximum number of cached responses
224
        - serializer: Serializer for data (defaults to JSONSerializer)
225
        - ttl: Time-to-live in seconds
226
        """
227

228
class AsyncInMemoryStorage(AsyncBaseStorage):
229
    def __init__(self, *, capacity=128, serializer=None, ttl=None):
230
        """
231
        Async in-memory storage backend with LRU eviction.
232
        
233
        Parameters:
234
        - capacity: Maximum number of cached responses
235
        - serializer: Serializer for data (defaults to JSONSerializer)
236
        - ttl: Time-to-live in seconds
237
        """
238
```
239

240
**Usage Examples:**
241

242
```python
243
import hishel
244

245
# Default in-memory storage
246
storage = hishel.InMemoryStorage()
247

248
# Custom capacity and TTL
249
storage = hishel.InMemoryStorage(
250
    capacity=1000,
251
    ttl=1800  # 30 minutes
252
)
253

254
with hishel.CacheClient(storage=storage) as client:
255
    response = client.get("https://api.example.com/data")
256
```
257

258
### S3 Storage
259

260
AWS S3-based storage for distributed cloud caching across regions and environments.
261

262
```python { .api }
263
class S3Storage(BaseStorage):
264
    def __init__(self, *, bucket_name, client=None, serializer=None, ttl=None,
265
                 key_prefix="hishel/"):
266
        """
267
        AWS S3-based storage backend.
268
        
269
        Parameters:
270
        - bucket_name: S3 bucket name for cache storage
271
        - client: Boto3 S3 client (creates default if None)
272
        - serializer: Serializer for data (defaults to JSONSerializer)
273
        - ttl: Time-to-live in seconds
274
        - key_prefix: S3 key prefix for cache objects
275
        """
276

277
class AsyncS3Storage(AsyncBaseStorage):
278
    def __init__(self, *, bucket_name, client=None, serializer=None, ttl=None,
279
                 key_prefix="hishel/"):
280
        """
281
        Async AWS S3-based storage backend.
282
        
283
        Parameters:
284
        - bucket_name: S3 bucket name for cache storage
285
        - client: Async Boto3 S3 client (creates default if None)
286
        - serializer: Serializer for data (defaults to JSONSerializer)
287
        - ttl: Time-to-live in seconds
288
        - key_prefix: S3 key prefix for cache objects
289
        """
290
```
291

292
**Usage Examples:**
293

294
```python
295
import boto3
296
import hishel
297

298
# Default S3 storage
299
storage = hishel.S3Storage(bucket_name="my-cache-bucket")
300

301
# Custom S3 client and configuration
302
s3_client = boto3.client(
303
    's3',
304
    region_name='us-west-2',
305
    aws_access_key_id='...',
306
    aws_secret_access_key='...'
307
)
308
storage = hishel.S3Storage(
309
    bucket_name="my-cache-bucket",
310
    client=s3_client,
311
    key_prefix="production/cache/",
312
    ttl=14400  # 4 hours
313
)
314

315
with hishel.CacheClient(storage=storage) as client:
316
    response = client.get("https://api.example.com/data")
317
```
318

319
## Installation Requirements
320

321
Different storage backends have optional dependencies:
322

323
```bash
324
# Redis storage
325
pip install hishel[redis]
326

327
# SQLite storage
328
pip install hishel[sqlite]
329

330
# S3 storage
331
pip install hishel[s3]
332

333
# YAML serializer
334
pip install hishel[yaml]
335

336
# All optional dependencies
337
pip install hishel[redis,sqlite,s3,yaml]
338
```