0
# Requests-Cache
1

2
A persistent cache for Python requests that enables transparent HTTP response caching with multiple storage backends, flexible expiration policies, and seamless integration with existing requests-based code.
3

4
## Package Information
5

6
- **Package Name**: requests-cache
7
- **Language**: Python
8
- **Installation**: `pip install requests-cache`
9

10
## Core Imports
11

12
```python
13
import requests_cache
14
```
15

16
For drop-in session replacement:
17

18
```python
19
from requests_cache import CachedSession
20
```
21

22
For global monkey-patching:
23

24
```python
25
from requests_cache import install_cache, uninstall_cache
26
```
27

28
## Basic Usage
29

30
```python
31
import requests_cache
32

33
# Option 1: Use CachedSession as drop-in replacement for requests.Session
34
session = requests_cache.CachedSession('demo_cache')
35
response = session.get('https://httpbin.org/get')
36
print(f"From cache: {response.from_cache}")
37

38
# Option 2: Global monkey-patch for all requests functions
39
requests_cache.install_cache('demo_cache')
40
import requests
41
response = requests.get('https://httpbin.org/get')
42
print(f"From cache: {response.from_cache}")
43

44
# Configure expiration and backends
45
session = requests_cache.CachedSession(
46
    cache_name='my_cache',
47
    backend='sqlite',
48
    expire_after=300,  # 5 minutes
49
    allowable_codes=[200, 404],
50
    allowable_methods=['GET', 'POST']
51
)
52
```
53

54
## Architecture
55

56
Requests-cache implements a layered architecture:
57

58
- **Session Layer**: CachedSession and CacheMixin provide the main user interface, extending requests.Session with caching capabilities
59
- **Backend Layer**: Multiple storage backends (SQLite, Redis, MongoDB, DynamoDB, Filesystem, Memory) handle response persistence
60
- **Policy Layer**: Cache settings, expiration patterns, and HTTP header processing determine caching behavior
61
- **Serialization Layer**: Multiple serializers (pickle, JSON, YAML, BSON) handle response data conversion
62
- **Key Generation**: Normalizes requests into cache keys for consistent matching and retrieval
63

64
This design enables transparent drop-in replacement for existing requests code while providing extensive customization for advanced use cases.
65

66
## Capabilities
67

68
### Session-Based Caching
69

70
The primary interface for caching with full control over cache settings, expiration policies, and backends. Provides a drop-in replacement for `requests.Session` with transparent caching capabilities.
71

72
```python { .api }
73
class CachedSession:
74
    def __init__(
75
        self,
76
        cache_name: str = 'http_cache',
77
        backend: Optional[BackendSpecifier] = None,
78
        serializer: Optional[SerializerType] = None,
79
        expire_after: ExpirationTime = -1,
80
        **kwargs
81
    ): ...
82

83
class CacheMixin:
84
    @classmethod
85
    def wrap(cls, original_session: Session, **kwargs) -> 'CacheMixin': ...
86
    def cache_disabled(self): ...
87
```
88

89
[Session-Based Caching](./sessions.md)
90

91
### Global Monkey-Patching
92

93
Functions to globally patch the requests library, enabling caching for all requests functions without code changes. Includes context managers for temporary caching control.
94

95
```python { .api }
96
def install_cache(
97
    cache_name: str = 'http_cache',
98
    backend: Optional[BackendSpecifier] = None,
99
    **kwargs
100
): ...
101

102
def uninstall_cache(): ...
103

104
def enabled(*args, **kwargs): ...
105

106
def disabled(): ...
107

108
def get_cache() -> Optional[BaseCache]: ...
109

110
def is_installed() -> bool: ...
111

112
def clear(): ...
113

114
def delete(*args, **kwargs): ...
115
```
116

117
[Global Monkey-Patching](./patching.md)
118

119
### Cache Backends
120

121
Multiple storage backends for different use cases, from simple in-memory caching to distributed storage solutions. Each backend provides consistent interfaces while optimizing for specific storage characteristics.
122

123
```python { .api }
124
class SQLiteCache: ...
125
class RedisCache: ... 
126
class MongoCache: ...
127
class GridFSCache: ...
128
class FileCache: ...
129
class DynamoDbCache: ...
130

131
def init_backend(
132
    cache_name: str,
133
    backend: Optional[BackendSpecifier] = None,
134
    **kwargs
135
) -> BaseCache: ...
136
```
137

138
[Cache Backends](./backends.md)
139

140
### Cache Policy and Expiration
141

142
Flexible expiration policies supporting HTTP Cache-Control headers, URL-specific patterns, and custom logic. Includes support for conditional requests, stale-if-error patterns, and cache validation.
143

144
```python { .api }
145
class CacheSettings: ...
146
class CacheActions: ...
147
class CacheDirectives: ...
148

149
def get_expiration_datetime(expire_after: ExpirationTime) -> Optional[datetime]: ...
150
def get_url_expiration(url: str, urls_expire_after: ExpirationPatterns) -> ExpirationTime: ...
151

152
ExpirationTime = Union[None, int, float, str, datetime, timedelta]
153
ExpirationPatterns = Dict[ExpirationPattern, ExpirationTime]
154
```
155

156
[Cache Policy and Expiration](./expiration.md)
157

158
### Response and Request Models
159

160
Cached response and request objects that maintain compatibility with the requests library while adding cache-specific metadata and functionality.
161

162
```python { .api }
163
class CachedResponse:
164
    @property
165
    def from_cache(self) -> bool: ...
166
    @property 
167
    def is_expired(self) -> bool: ...
168
    def is_older_than(self, time: ExpirationTime) -> bool: ...
169

170
class CachedRequest: ...
171
class OriginalResponse: ...
172

173
AnyResponse = Union[OriginalResponse, CachedResponse]
174
```
175

176
[Response and Request Models](./models.md)
177

178
### Serialization
179

180
Multiple serialization options for storing response data, including secure pickle variants, JSON with binary support, YAML, and BSON formats optimized for different storage backends.
181

182
```python { .api }
183
class SerializerPipeline: ...
184
class Stage: ...
185

186
def init_serializer(
187
    serializer: Optional[SerializerType],
188
    decode_content: bool
189
) -> Optional[SerializerPipeline]: ...
190

191
# Available serializers
192
pickle_serializer: SerializerPipeline
193
json_serializer: SerializerPipeline
194
yaml_serializer: SerializerPipeline
195
bson_serializer: SerializerPipeline
196
```
197

198
[Serialization](./serialization.md)
199

200
## Types
201

202
```python { .api }
203
# Backend types
204
BackendSpecifier = Union[str, BaseCache]
205
StrOrPath = Union[Path, str]
206

207
# Expiration types  
208
ExpirationTime = Union[None, int, float, str, datetime, timedelta]
209
ExpirationPattern = Union[str, Pattern]
210
ExpirationPatterns = Dict[ExpirationPattern, ExpirationTime]
211

212
# Callback types
213
FilterCallback = Callable[[Response], bool]
214
KeyCallback = Callable[..., str]
215

216
# Serializer types
217
SerializerType = Union[str, SerializerPipeline, Stage]
218

219
# Response types
220
AnyResponse = Union[OriginalResponse, CachedResponse]
221
AnyRequest = Union[Request, PreparedRequest, CachedRequest]
222
AnyPreparedRequest = Union[PreparedRequest, CachedRequest]
223

224
# Special expiration constants
225
DO_NOT_CACHE: int
226
EXPIRE_IMMEDIATELY: int  # 0
227
NEVER_EXPIRE: int  # -1
228
```