0
# Hishel
1

2
An elegant HTTP caching library that implements RFC 9111 caching specification for HTTPX and HTTP Core libraries. Hishel provides persistent memory caching with smart cache management, understanding HTTP headers like Vary, Etag, Last-Modified, Cache-Control, and Expires for automatic response re-validation.
3

4
## Package Information
5

6
- **Package Name**: hishel
7
- **Language**: Python
8
- **Installation**: `pip install hishel`
9
- **Requirements**: Python >= 3.9, httpx >= 0.28.0
10

11
## Core Imports
12

13
```python
14
import hishel
15
```
16

17
For direct access to main components:
18

19
```python
20
from hishel import CacheClient, AsyncCacheClient, Controller, FileStorage
21
```
22

23
## Basic Usage
24

25
### Drop-in Replacement for HTTPX
26

27
```python
28
import hishel
29

30
# Replace httpx.Client with hishel.CacheClient
31
with hishel.CacheClient() as client:
32
    response = client.get("https://httpbin.org/get")
33
    print(response.status_code)  # 200, fetched from server
34
    
35
    # Second request is served from cache
36
    response = client.get("https://httpbin.org/get") 
37
    print(response.status_code)  # 200, served from cache
38

39
# Async version
40
import asyncio
41

42
async def main():
43
    async with hishel.AsyncCacheClient() as client:
44
        response = await client.get("https://httpbin.org/get")
45
        print(response.status_code)
46

47
asyncio.run(main())
48
```
49

50
### Global Installation
51

52
```python
53
import hishel
54
import httpx
55

56
# Monkey-patch httpx to use caching globally
57
hishel.install_cache()
58

59
# Now all httpx clients automatically use caching
60
with httpx.Client() as client:
61
    response = client.get("https://httpbin.org/get")
62
```
63

64
## Architecture
65

66
Hishel follows a modular architecture with four main components:
67

68
- **Cache Clients**: Drop-in replacements for httpx.Client and httpx.AsyncClient
69
- **Cache Transports**: HTTPX transport layer with caching logic
70
- **Storage Backends**: Pluggable storage implementations (File, Redis, SQLite, S3, In-Memory)
71
- **Cache Controller**: RFC 9111 compliant caching logic and validation
72

73
This design provides complete compatibility with existing HTTPX workflows while adding transparent HTTP caching capabilities.
74

75
## Capabilities
76

77
### HTTP Cache Clients
78

79
Drop-in replacements for httpx.Client and httpx.AsyncClient that provide transparent HTTP caching with configurable storage backends and caching policies.
80

81
```python { .api }
82
class CacheClient(httpx.Client):
83
    def __init__(self, *, storage=None, controller=None, **kwargs): ...
84

85
class AsyncCacheClient(httpx.AsyncClient):
86
    def __init__(self, *, storage=None, controller=None, **kwargs): ...
87
```
88

89
[HTTP Cache Clients](./cache-clients.md)
90

91
### Storage Backends
92

93
Pluggable storage implementations for persisting cached HTTP responses across various backends including file system, Redis, SQLite, AWS S3, and in-memory storage.
94

95
```python { .api }
96
class FileStorage(BaseStorage):
97
    def __init__(self, *, serializer=None, base_path=None, ttl=None, check_ttl_every=60): ...
98

99
class AsyncFileStorage(AsyncBaseStorage):
100
    def __init__(self, *, serializer=None, base_path=None, ttl=None, check_ttl_every=60): ...
101
```
102

103
[Storage Backends](./storage-backends.md)
104

105
### Cache Controller
106

107
RFC 9111 compliant cache controller that determines cacheability, validates cached responses, and handles cache directives from HTTP headers.
108

109
```python { .api }
110
class Controller:
111
    def __init__(self, *, cacheable_methods=None, cacheable_status_codes=None, 
112
                 cache_private=True, allow_heuristics=False, clock=None, 
113
                 allow_stale=False, always_revalidate=False, force_cache=False, 
114
                 key_generator=None): ...
115
    
116
    def is_cachable(self, request: Request, response: Response) -> bool: ...
117
    def construct_response_from_cache(self, request: Request, response: Response, 
118
                                    original_request: Request): ...
119
```
120

121
[Cache Controller](./cache-controller.md)
122

123
### Serializers
124

125
Serialization formats for persisting HTTP request/response pairs including Pickle, JSON, and YAML serializers with metadata support.
126

127
```python { .api }
128
class PickleSerializer(BaseSerializer):
129
    def dumps(self, response: Response, request: Request, metadata: Metadata) -> bytes: ...
130
    def loads(self, data: bytes) -> tuple[Response, Request, Metadata]: ...
131

132
class JSONSerializer(BaseSerializer):
133
    def dumps(self, response: Response, request: Request, metadata: Metadata) -> str: ...
134
    def loads(self, data: str) -> tuple[Response, Request, Metadata]: ...
135
```
136

137
[Serializers](./serializers.md)
138

139
### Cache Transports
140

141
HTTPX transport implementations that add caching layer on top of existing transports, handling cache lookups, storage, and validation.
142

143
```python { .api }
144
class CacheTransport(httpx.BaseTransport):
145
    def __init__(self, *, transport: httpx.BaseTransport, storage=None, controller=None): ...
146

147
class AsyncCacheTransport(httpx.AsyncBaseTransport):
148
    def __init__(self, *, transport: httpx.AsyncBaseTransport, storage=None, controller=None): ...
149
```
150

151
[Cache Transports](./cache-transports.md)
152

153
### HTTP Headers
154

155
Cache-Control and Vary header parsing and representation with RFC 9111 compliant validation and directive handling.
156

157
```python { .api }
158
class CacheControl:
159
    def __init__(self, *, immutable=False, max_age=None, max_stale=None, 
160
                 min_fresh=None, must_revalidate=False, must_understand=False,
161
                 no_cache=False, no_store=False, no_transform=False, 
162
                 only_if_cached=False, private=False, proxy_revalidate=False,
163
                 public=False, s_maxage=None): ...
164

165
def parse_cache_control(cache_control_values: list[str]) -> CacheControl: ...
166
```
167

168
[HTTP Headers](./http-headers.md)
169

170
### Utilities
171

172
Testing utilities including mock connection pools and transports for unit testing cached HTTP interactions.
173

174
```python { .api }
175
class MockTransport(httpx.BaseTransport):
176
    def add_responses(self, responses: list[httpx.Response]) -> None: ...
177

178
class MockAsyncTransport(httpx.AsyncBaseTransport):
179
    def add_responses(self, responses: list[httpx.Response]) -> None: ...
180
```
181

182
[Testing Utilities](./testing-utilities.md)
183

184
## Global Functions
185

186
```python { .api }
187
def install_cache() -> None:
188
    """Monkey-patch httpx to use Hishel caching globally"""
189
```
190

191
## Utility Classes
192

193
```python { .api }
194
class LFUCache:
195
    def __init__(self, capacity: int): ...
196
    def get(self, key) -> Any: ...
197
    def put(self, key, value) -> None: ...
198
    def remove_key(self, key) -> None: ...
199
```
200

201
Least Frequently Used cache implementation for internal use and advanced caching scenarios.
202

203
## Exception Handling
204

205
```python { .api }
206
class CacheControlError(Exception): ...
207
class ParseError(CacheControlError): ...
208
class ValidationError(CacheControlError): ...
209
```