0
# HTTP Cache Clients
1

2
Drop-in replacements for httpx.Client and httpx.AsyncClient that provide transparent HTTP caching. These clients automatically cache responses according to HTTP caching rules and serve cached responses for subsequent requests.
3

4
## Capabilities
5

6
### Synchronous Cache Client
7

8
A synchronous HTTP client with built-in caching capabilities, fully compatible with httpx.Client.
9

10
```python { .api }
11
class CacheClient(httpx.Client):
12
    def __init__(self, *, storage=None, controller=None, **kwargs):
13
        """
14
        Initialize a synchronous HTTP client with caching.
15
        
16
        Parameters:
17
        - storage: Storage backend for cached responses (defaults to FileStorage)
18
        - controller: Cache controller for caching logic (defaults to Controller())
19
        - **kwargs: All httpx.Client parameters (timeout, headers, auth, etc.)
20
        """
21
```
22

23
**Usage Examples:**
24

25
```python
26
import hishel
27

28
# Basic usage with default file storage
29
with hishel.CacheClient() as client:
30
    response = client.get("https://api.example.com/data")
31

32
# Custom storage backend
33
storage = hishel.RedisStorage()
34
with hishel.CacheClient(storage=storage) as client:
35
    response = client.get("https://api.example.com/data")
36

37
# Custom cache controller
38
controller = hishel.Controller(
39
    cacheable_methods=["GET", "POST"],
40
    cacheable_status_codes=[200, 204, 301]
41
)
42
with hishel.CacheClient(controller=controller) as client:
43
    response = client.get("https://api.example.com/data")
44

45
# All httpx.Client parameters work
46
with hishel.CacheClient(
47
    timeout=30.0,
48
    headers={'User-Agent': 'MyApp/1.0'},
49
    auth=('username', 'password')
50
) as client:
51
    response = client.get("https://api.example.com/data")
52
```
53

54
### Asynchronous Cache Client
55

56
An asynchronous HTTP client with built-in caching capabilities, fully compatible with httpx.AsyncClient.
57

58
```python { .api }
59
class AsyncCacheClient(httpx.AsyncClient):
60
    def __init__(self, *, storage=None, controller=None, **kwargs):
61
        """
62
        Initialize an asynchronous HTTP client with caching.
63
        
64
        Parameters:
65
        - storage: Async storage backend for cached responses (defaults to AsyncFileStorage)
66
        - controller: Cache controller for caching logic (defaults to Controller())
67
        - **kwargs: All httpx.AsyncClient parameters (timeout, headers, auth, etc.)
68
        """
69
```
70

71
**Usage Examples:**
72

73
```python
74
import hishel
75
import asyncio
76

77
async def main():
78
    # Basic usage with default async file storage
79
    async with hishel.AsyncCacheClient() as client:
80
        response = await client.get("https://api.example.com/data")
81
        
82
    # Custom async storage backend
83
    storage = hishel.AsyncRedisStorage()
84
    async with hishel.AsyncCacheClient(storage=storage) as client:
85
        response = await client.get("https://api.example.com/data")
86
        
87
    # Custom cache controller with async client
88
    controller = hishel.Controller(allow_heuristics=True)
89
    async with hishel.AsyncCacheClient(controller=controller) as client:
90
        response = await client.get("https://api.example.com/data")
91

92
asyncio.run(main())
93
```
94

95
## Request-Level Cache Control
96

97
Both clients support per-request cache control through request extensions:
98

99
```python
100
# Force cache usage for a specific request
101
response = client.get("https://api.example.com/data", 
102
                     extensions={"force_cache": True})
103

104
# Disable cache for a specific request  
105
response = client.get("https://api.example.com/data",
106
                     extensions={"force_cache": False})
107
```
108

109
## Integration with HTTPX Features
110

111
Cache clients fully support all HTTPX features:
112

113
- **Authentication**: All auth methods work with caching
114
- **Timeouts**: Request and connection timeouts are preserved
115
- **Headers**: Custom headers are included in cache key generation
116
- **Cookies**: Cookie handling works with cached responses
117
- **Redirects**: Redirect handling is cache-aware
118
- **Streaming**: Streaming responses can be cached
119
- **HTTP/2**: HTTP/2 connections work with caching
120
- **Proxies**: Proxy support is maintained with caching
121

122
## Cache Behavior
123

124
- **Automatic**: Caching happens transparently according to HTTP headers
125
- **RFC 9111 Compliant**: Follows HTTP caching specification
126
- **Smart Validation**: Automatic revalidation using ETags and Last-Modified
127
- **Vary Support**: Handles Vary headers for content negotiation
128
- **Private/Public**: Respects Cache-Control private/public directives
129
- **TTL Support**: Storage-level TTL for cache expiration