hishel 0.1.5__py3-none-any.whl → 1.0.0b1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- hishel/__init__.py +59 -52
- hishel/_async_cache.py +213 -0
- hishel/_async_httpx.py +236 -0
- hishel/{beta/_core → _core}/_headers.py +11 -1
- hishel/{beta/_core → _core}/_spec.py +270 -136
- hishel/_core/_storages/_async_base.py +71 -0
- hishel/_core/_storages/_async_sqlite.py +420 -0
- hishel/_core/_storages/_packing.py +144 -0
- hishel/_core/_storages/_sync_base.py +71 -0
- hishel/_core/_storages/_sync_sqlite.py +420 -0
- hishel/{beta/_core → _core}/models.py +100 -37
- hishel/_policies.py +49 -0
- hishel/_sync_cache.py +213 -0
- hishel/_sync_httpx.py +236 -0
- hishel/_utils.py +37 -366
- hishel/asgi.py +400 -0
- hishel/fastapi.py +263 -0
- hishel/httpx.py +12 -0
- hishel/{beta/requests.py → requests.py} +31 -25
- hishel-1.0.0b1.dist-info/METADATA +509 -0
- hishel-1.0.0b1.dist-info/RECORD +24 -0
- hishel/_async/__init__.py +0 -5
- hishel/_async/_client.py +0 -30
- hishel/_async/_mock.py +0 -43
- hishel/_async/_pool.py +0 -201
- hishel/_async/_storages.py +0 -768
- hishel/_async/_transports.py +0 -282
- hishel/_controller.py +0 -581
- hishel/_exceptions.py +0 -10
- hishel/_files.py +0 -54
- hishel/_headers.py +0 -215
- hishel/_lfu_cache.py +0 -71
- hishel/_lmdb_types_.pyi +0 -53
- hishel/_s3.py +0 -122
- hishel/_serializers.py +0 -329
- hishel/_sync/__init__.py +0 -5
- hishel/_sync/_client.py +0 -30
- hishel/_sync/_mock.py +0 -43
- hishel/_sync/_pool.py +0 -201
- hishel/_sync/_storages.py +0 -768
- hishel/_sync/_transports.py +0 -282
- hishel/_synchronization.py +0 -37
- hishel/beta/__init__.py +0 -59
- hishel/beta/_async_cache.py +0 -167
- hishel/beta/_core/__init__.py +0 -0
- hishel/beta/_core/_async/_storages/_sqlite.py +0 -411
- hishel/beta/_core/_base/_storages/_base.py +0 -272
- hishel/beta/_core/_base/_storages/_packing.py +0 -165
- hishel/beta/_core/_sync/_storages/_sqlite.py +0 -411
- hishel/beta/_sync_cache.py +0 -167
- hishel/beta/httpx.py +0 -328
- hishel-0.1.5.dist-info/METADATA +0 -258
- hishel-0.1.5.dist-info/RECORD +0 -41
- {hishel-0.1.5.dist-info → hishel-1.0.0b1.dist-info}/WHEEL +0 -0
- {hishel-0.1.5.dist-info → hishel-1.0.0b1.dist-info}/licenses/LICENSE +0 -0
|
@@ -5,12 +5,12 @@ from typing import Any, Iterator, Mapping, Optional, overload
|
|
|
5
5
|
|
|
6
6
|
from typing_extensions import assert_never
|
|
7
7
|
|
|
8
|
+
from hishel import Headers, Request, Response as Response
|
|
9
|
+
from hishel._core._storages._sync_base import SyncBaseStorage
|
|
10
|
+
from hishel._core.models import extract_metadata_from_headers
|
|
11
|
+
from hishel._policies import CachePolicy
|
|
12
|
+
from hishel._sync_cache import SyncCacheProxy
|
|
8
13
|
from hishel._utils import snake_to_header
|
|
9
|
-
from hishel.beta import Headers, Request, Response as Response
|
|
10
|
-
from hishel.beta._core._base._storages._base import SyncBaseStorage
|
|
11
|
-
from hishel.beta._core._spec import CacheOptions
|
|
12
|
-
from hishel.beta._core.models import extract_metadata_from_headers
|
|
13
|
-
from hishel.beta._sync_cache import SyncCacheProxy
|
|
14
14
|
|
|
15
15
|
try:
|
|
16
16
|
import requests
|
|
@@ -27,7 +27,7 @@ except ImportError: # pragma: no cover
|
|
|
27
27
|
CHUNK_SIZE = 131072
|
|
28
28
|
|
|
29
29
|
|
|
30
|
-
class
|
|
30
|
+
class _IteratorStream(RawIOBase):
|
|
31
31
|
def __init__(self, iterator: Iterator[bytes]):
|
|
32
32
|
self.iterator = iterator
|
|
33
33
|
self.leftover = b""
|
|
@@ -61,18 +61,18 @@ class IteratorStream(RawIOBase):
|
|
|
61
61
|
|
|
62
62
|
|
|
63
63
|
@overload
|
|
64
|
-
def
|
|
64
|
+
def _requests_to_internal(
|
|
65
65
|
model: requests.models.PreparedRequest,
|
|
66
66
|
) -> Request: ...
|
|
67
67
|
|
|
68
68
|
|
|
69
69
|
@overload
|
|
70
|
-
def
|
|
70
|
+
def _requests_to_internal(
|
|
71
71
|
model: requests.models.Response,
|
|
72
72
|
) -> Response: ...
|
|
73
73
|
|
|
74
74
|
|
|
75
|
-
def
|
|
75
|
+
def _requests_to_internal(
|
|
76
76
|
model: requests.models.PreparedRequest | requests.models.Response,
|
|
77
77
|
) -> Request | Response:
|
|
78
78
|
if isinstance(model, requests.models.PreparedRequest):
|
|
@@ -108,19 +108,24 @@ def requests_to_internal(
|
|
|
108
108
|
|
|
109
109
|
|
|
110
110
|
@overload
|
|
111
|
-
def
|
|
111
|
+
def _internal_to_requests(model: Request) -> requests.models.PreparedRequest: ...
|
|
112
112
|
@overload
|
|
113
|
-
def
|
|
114
|
-
def
|
|
113
|
+
def _internal_to_requests(model: Response) -> requests.models.Response: ...
|
|
114
|
+
def _internal_to_requests(
|
|
115
|
+
model: Request | Response,
|
|
116
|
+
) -> requests.models.Response | requests.models.PreparedRequest:
|
|
115
117
|
if isinstance(model, Response):
|
|
116
118
|
response = requests.models.Response()
|
|
117
119
|
|
|
118
120
|
assert isinstance(model.stream, Iterator)
|
|
119
|
-
stream =
|
|
121
|
+
stream = _IteratorStream(model.stream)
|
|
120
122
|
|
|
121
123
|
urllib_response = HTTPResponse(
|
|
122
124
|
body=stream,
|
|
123
|
-
headers={
|
|
125
|
+
headers={
|
|
126
|
+
**model.headers,
|
|
127
|
+
**{snake_to_header(k): str(v) for k, v in model.metadata.items()},
|
|
128
|
+
},
|
|
124
129
|
status=model.status_code,
|
|
125
130
|
preload_content=False,
|
|
126
131
|
decode_content=False,
|
|
@@ -158,15 +163,13 @@ class CacheAdapter(HTTPAdapter):
|
|
|
158
163
|
max_retries: int = 0,
|
|
159
164
|
pool_block: bool = False,
|
|
160
165
|
storage: SyncBaseStorage | None = None,
|
|
161
|
-
|
|
162
|
-
ignore_specification: bool = False,
|
|
166
|
+
policy: CachePolicy | None = None,
|
|
163
167
|
):
|
|
164
168
|
super().__init__(pool_connections, pool_maxsize, max_retries, pool_block)
|
|
165
169
|
self._cache_proxy = SyncCacheProxy(
|
|
166
|
-
|
|
170
|
+
request_sender=self._send_request,
|
|
167
171
|
storage=storage,
|
|
168
|
-
|
|
169
|
-
ignore_specification=ignore_specification,
|
|
172
|
+
policy=policy,
|
|
170
173
|
)
|
|
171
174
|
self.storage = self._cache_proxy.storage
|
|
172
175
|
|
|
@@ -179,9 +182,9 @@ class CacheAdapter(HTTPAdapter):
|
|
|
179
182
|
cert: None | bytes | str | tuple[bytes | str, bytes | str] = None,
|
|
180
183
|
proxies: Mapping[str, str] | None = None,
|
|
181
184
|
) -> requests.models.Response:
|
|
182
|
-
internal_request =
|
|
185
|
+
internal_request = _requests_to_internal(request)
|
|
183
186
|
internal_response = self._cache_proxy.handle_request(internal_request)
|
|
184
|
-
response =
|
|
187
|
+
response = _internal_to_requests(internal_response)
|
|
185
188
|
|
|
186
189
|
# Set the original request on the response
|
|
187
190
|
response.request = request
|
|
@@ -189,10 +192,13 @@ class CacheAdapter(HTTPAdapter):
|
|
|
189
192
|
|
|
190
193
|
return response
|
|
191
194
|
|
|
192
|
-
def
|
|
193
|
-
requests_request =
|
|
194
|
-
response = super().send(
|
|
195
|
-
|
|
195
|
+
def _send_request(self, request: Request) -> Response:
|
|
196
|
+
requests_request = _internal_to_requests(request)
|
|
197
|
+
response = super().send(
|
|
198
|
+
requests_request,
|
|
199
|
+
stream=True,
|
|
200
|
+
)
|
|
201
|
+
return _requests_to_internal(response)
|
|
196
202
|
|
|
197
203
|
def close(self) -> Any:
|
|
198
204
|
self.storage.close()
|
|
@@ -0,0 +1,509 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: hishel
|
|
3
|
+
Version: 1.0.0b1
|
|
4
|
+
Summary: Elegant HTTP Caching for Python
|
|
5
|
+
Project-URL: Homepage, https://hishel.com
|
|
6
|
+
Project-URL: Source, https://github.com/karpetrosyan/hishel
|
|
7
|
+
Author-email: Kar Petrosyan <kar.petrosyanpy@gmail.com>
|
|
8
|
+
License-Expression: BSD-3-Clause
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Environment :: Web Environment
|
|
12
|
+
Classifier: Framework :: AsyncIO
|
|
13
|
+
Classifier: Framework :: Trio
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: License :: OSI Approved :: BSD License
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
25
|
+
Classifier: Topic :: Internet :: WWW/HTTP
|
|
26
|
+
Requires-Python: >=3.9
|
|
27
|
+
Requires-Dist: msgpack>=1.1.2
|
|
28
|
+
Requires-Dist: typing-extensions>=4.14.1
|
|
29
|
+
Provides-Extra: async
|
|
30
|
+
Requires-Dist: anyio>=4.9.0; extra == 'async'
|
|
31
|
+
Requires-Dist: anysqlite>=0.0.5; extra == 'async'
|
|
32
|
+
Provides-Extra: fastapi
|
|
33
|
+
Requires-Dist: fastapi>=0.119.1; extra == 'fastapi'
|
|
34
|
+
Provides-Extra: httpx
|
|
35
|
+
Requires-Dist: anyio>=4.9.0; extra == 'httpx'
|
|
36
|
+
Requires-Dist: anysqlite>=0.0.5; extra == 'httpx'
|
|
37
|
+
Requires-Dist: httpx>=0.28.1; extra == 'httpx'
|
|
38
|
+
Provides-Extra: requests
|
|
39
|
+
Requires-Dist: requests>=2.32.5; extra == 'requests'
|
|
40
|
+
Description-Content-Type: text/markdown
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
<p align="center">
|
|
44
|
+
<img alt="Hishel Logo" width="350" src="https://raw.githubusercontent.com/karpetrosyan/hishel/master/docs/static/Shelkopryad_350x250_yellow.png#gh-dark-mode-only">
|
|
45
|
+
<img alt="Hishel Logo" width="350" src="https://raw.githubusercontent.com/karpetrosyan/hishel/master/docs/static/Shelkopryad_350x250_black.png#gh-light-mode-only">
|
|
46
|
+
</p>
|
|
47
|
+
|
|
48
|
+
<h1 align="center">Hishel</h1>
|
|
49
|
+
|
|
50
|
+
<p align="center">
|
|
51
|
+
<strong>Elegant HTTP Caching for Python</strong>
|
|
52
|
+
</p>
|
|
53
|
+
|
|
54
|
+
<p align="center">
|
|
55
|
+
<a href="https://pypi.org/project/hishel">
|
|
56
|
+
<img src="https://img.shields.io/pypi/v/hishel.svg" alt="PyPI version">
|
|
57
|
+
</a>
|
|
58
|
+
<a href="https://pypi.org/project/hishel">
|
|
59
|
+
<img src="https://img.shields.io/pypi/pyversions/hishel.svg" alt="Python versions">
|
|
60
|
+
</a>
|
|
61
|
+
<a href="https://github.com/karpetrosyan/hishel/blob/master/LICENSE">
|
|
62
|
+
<img src="https://img.shields.io/pypi/l/hishel" alt="License">
|
|
63
|
+
</a>
|
|
64
|
+
<a href="https://coveralls.io/github/karpetrosyan/hishel">
|
|
65
|
+
<img src="https://img.shields.io/coverallsCoverage/github/karpetrosyan/hishel" alt="Coverage">
|
|
66
|
+
</a>
|
|
67
|
+
<a href="https://static.pepy.tech/badge/hishel/month">
|
|
68
|
+
<img src="https://static.pepy.tech/badge/hishel/month" alt="Downloads">
|
|
69
|
+
</a>
|
|
70
|
+
</p>
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
**Hishel** (հիշել, *to remember* in Armenian) is a modern HTTP caching library for Python that implements [RFC 9111](https://www.rfc-editor.org/rfc/rfc9111.html) specifications. It provides seamless caching integration for popular HTTP clients with minimal code changes.
|
|
75
|
+
|
|
76
|
+
## ✨ Features
|
|
77
|
+
|
|
78
|
+
- 🎯 **RFC 9111 Compliant** - Fully compliant with the latest HTTP caching specification
|
|
79
|
+
- 🔌 **Easy Integration** - Drop-in support for HTTPX, Requests, ASGI, FastAPI, and BlackSheep
|
|
80
|
+
- 💾 **Flexible Storage** - SQLite backend with more coming soon
|
|
81
|
+
- ⚡ **High Performance** - Efficient caching with minimal overhead
|
|
82
|
+
- 🔄 **Async & Sync** - Full support for both synchronous and asynchronous workflows
|
|
83
|
+
- 🎨 **Type Safe** - Fully typed with comprehensive type hints
|
|
84
|
+
- 🧪 **Well Tested** - Extensive test coverage and battle-tested
|
|
85
|
+
- 🎛️ **Configurable** - Fine-grained control over caching behavior with flexible policies
|
|
86
|
+
- 💨 **Memory Efficient** - Streaming support prevents loading large payloads into memory
|
|
87
|
+
- 🌐 **Universal** - Works with any ASGI application (Starlette, Litestar, BlackSheep, etc.)
|
|
88
|
+
- 🎯 **GraphQL Support** - Cache GraphQL queries with body-sensitive content caching
|
|
89
|
+
|
|
90
|
+
## 📦 Installation
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
pip install hishel
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### Optional Dependencies
|
|
97
|
+
|
|
98
|
+
Install with specific integration support:
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
pip install hishel[httpx] # For HTTPX support
|
|
102
|
+
pip install hishel[requests] # For Requests support
|
|
103
|
+
pip install hishel[fastapi] # For FastAPI support (includes ASGI)
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Or install multiple:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
pip install hishel[httpx,requests,fastapi]
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
> [!NOTE]
|
|
113
|
+
> ASGI middleware has no extra dependencies - it's included in the base installation.
|
|
114
|
+
|
|
115
|
+
## 🚀 Quick Start
|
|
116
|
+
|
|
117
|
+
### With HTTPX
|
|
118
|
+
|
|
119
|
+
**Synchronous:**
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
from hishel.httpx import SyncCacheClient
|
|
123
|
+
|
|
124
|
+
client = SyncCacheClient()
|
|
125
|
+
|
|
126
|
+
# First request - fetches from origin
|
|
127
|
+
response = client.get("https://api.example.com/data")
|
|
128
|
+
print(response.extensions["hishel_from_cache"]) # False
|
|
129
|
+
|
|
130
|
+
# Second request - served from cache
|
|
131
|
+
response = client.get("https://api.example.com/data")
|
|
132
|
+
print(response.extensions["hishel_from_cache"]) # True
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
**Asynchronous:**
|
|
136
|
+
|
|
137
|
+
```python
|
|
138
|
+
from hishel.httpx import AsyncCacheClient
|
|
139
|
+
|
|
140
|
+
async with AsyncCacheClient() as client:
|
|
141
|
+
# First request - fetches from origin
|
|
142
|
+
response = await client.get("https://api.example.com/data")
|
|
143
|
+
print(response.extensions["hishel_from_cache"]) # False
|
|
144
|
+
|
|
145
|
+
# Second request - served from cache
|
|
146
|
+
response = await client.get("https://api.example.com/data")
|
|
147
|
+
print(response.extensions["hishel_from_cache"]) # True
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### With Requests
|
|
151
|
+
|
|
152
|
+
```python
|
|
153
|
+
import requests
|
|
154
|
+
from hishel.requests import CacheAdapter
|
|
155
|
+
|
|
156
|
+
session = requests.Session()
|
|
157
|
+
session.mount("https://", CacheAdapter())
|
|
158
|
+
session.mount("http://", CacheAdapter())
|
|
159
|
+
|
|
160
|
+
# First request - fetches from origin
|
|
161
|
+
response = session.get("https://api.example.com/data")
|
|
162
|
+
|
|
163
|
+
# Second request - served from cache
|
|
164
|
+
response = session.get("https://api.example.com/data")
|
|
165
|
+
print(response.headers.get("X-Hishel-From-Cache")) # "True"
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### With ASGI Applications
|
|
169
|
+
|
|
170
|
+
Add caching middleware to any ASGI application:
|
|
171
|
+
|
|
172
|
+
```python
|
|
173
|
+
from hishel.asgi import ASGICacheMiddleware
|
|
174
|
+
|
|
175
|
+
# Wrap your ASGI app
|
|
176
|
+
app = ASGICacheMiddleware(app)
|
|
177
|
+
|
|
178
|
+
# Or configure with options
|
|
179
|
+
from hishel import AsyncSqliteStorage, CacheOptions, SpecificationPolicy
|
|
180
|
+
|
|
181
|
+
app = ASGICacheMiddleware(
|
|
182
|
+
app,
|
|
183
|
+
storage=AsyncSqliteStorage(),
|
|
184
|
+
policy=SpecificationPolicy(
|
|
185
|
+
cache_options=CacheOptions(shared=True)
|
|
186
|
+
),
|
|
187
|
+
)
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
### With FastAPI
|
|
191
|
+
|
|
192
|
+
Add Cache-Control headers using the `cache()` dependency:
|
|
193
|
+
|
|
194
|
+
```python
|
|
195
|
+
from fastapi import FastAPI
|
|
196
|
+
from hishel.fastapi import cache
|
|
197
|
+
|
|
198
|
+
app = FastAPI()
|
|
199
|
+
|
|
200
|
+
@app.get("/api/data", dependencies=[cache(max_age=300, public=True)])
|
|
201
|
+
async def get_data():
|
|
202
|
+
# Cache-Control: public, max-age=300
|
|
203
|
+
return {"data": "cached for 5 minutes"}
|
|
204
|
+
|
|
205
|
+
# Optionally wrap with ASGI middleware for local caching according to specified rules
|
|
206
|
+
from hishel.asgi import ASGICacheMiddleware
|
|
207
|
+
from hishel import AsyncSqliteStorage
|
|
208
|
+
|
|
209
|
+
app = ASGICacheMiddleware(app, storage=AsyncSqliteStorage())
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
### With BlackSheep
|
|
213
|
+
|
|
214
|
+
Use BlackSheep's native `cache_control` decorator with Hishel's ASGI middleware:
|
|
215
|
+
|
|
216
|
+
```python
|
|
217
|
+
from blacksheep import Application, get
|
|
218
|
+
from blacksheep.server.headers.cache import cache_control
|
|
219
|
+
|
|
220
|
+
app = Application()
|
|
221
|
+
|
|
222
|
+
@get("/api/data")
|
|
223
|
+
@cache_control(max_age=300, public=True)
|
|
224
|
+
async def get_data():
|
|
225
|
+
# Cache-Control: public, max-age=300
|
|
226
|
+
return {"data": "cached for 5 minutes"}
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
## 🎛️ Advanced Configuration
|
|
230
|
+
|
|
231
|
+
### Caching Policies
|
|
232
|
+
|
|
233
|
+
Hishel supports two types of caching policies:
|
|
234
|
+
|
|
235
|
+
**SpecificationPolicy** - RFC 9111 compliant HTTP caching (default):
|
|
236
|
+
|
|
237
|
+
```python
|
|
238
|
+
from hishel import CacheOptions, SpecificationPolicy
|
|
239
|
+
from hishel.httpx import SyncCacheClient
|
|
240
|
+
|
|
241
|
+
client = SyncCacheClient(
|
|
242
|
+
policy=SpecificationPolicy(
|
|
243
|
+
cache_options=CacheOptions(
|
|
244
|
+
shared=False, # Use as private cache (browser-like)
|
|
245
|
+
supported_methods=["GET", "HEAD", "POST"], # Cache GET, HEAD, and POST
|
|
246
|
+
allow_stale=True # Allow serving stale responses
|
|
247
|
+
)
|
|
248
|
+
)
|
|
249
|
+
)
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
**FilterPolicy** - Custom filtering logic for fine-grained control:
|
|
253
|
+
|
|
254
|
+
```python
|
|
255
|
+
from hishel import FilterPolicy, BaseFilter, Request
|
|
256
|
+
from hishel.httpx import AsyncCacheClient
|
|
257
|
+
|
|
258
|
+
class CacheOnlyAPIRequests(BaseFilter[Request]):
|
|
259
|
+
def needs_body(self) -> bool:
|
|
260
|
+
return False
|
|
261
|
+
|
|
262
|
+
def apply(self, item: Request, body: bytes | None) -> bool:
|
|
263
|
+
return "/api/" in str(item.url)
|
|
264
|
+
|
|
265
|
+
client = AsyncCacheClient(
|
|
266
|
+
policy=FilterPolicy(
|
|
267
|
+
request_filters=[CacheOnlyAPIRequests()]
|
|
268
|
+
)
|
|
269
|
+
)
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
[Learn more about policies →](https://hishel.com/dev/policies/)
|
|
273
|
+
|
|
274
|
+
### Custom Storage Backend
|
|
275
|
+
|
|
276
|
+
```python
|
|
277
|
+
from hishel import SyncSqliteStorage
|
|
278
|
+
from hishel.httpx import SyncCacheClient
|
|
279
|
+
|
|
280
|
+
storage = SyncSqliteStorage(
|
|
281
|
+
database_path="my_cache.db",
|
|
282
|
+
default_ttl=7200.0, # Cache entries expire after 2 hours
|
|
283
|
+
refresh_ttl_on_access=True # Reset TTL when accessing cached entries
|
|
284
|
+
)
|
|
285
|
+
|
|
286
|
+
client = SyncCacheClient(storage=storage)
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
### GraphQL and Body-Sensitive Caching
|
|
290
|
+
|
|
291
|
+
Cache GraphQL queries and other POST requests by including the request body in the cache key.
|
|
292
|
+
|
|
293
|
+
**Using per-request header:**
|
|
294
|
+
|
|
295
|
+
```python
|
|
296
|
+
from hishel import FilterPolicy
|
|
297
|
+
from hishel.httpx import SyncCacheClient
|
|
298
|
+
|
|
299
|
+
client = SyncCacheClient(
|
|
300
|
+
policy=FilterPolicy()
|
|
301
|
+
)
|
|
302
|
+
|
|
303
|
+
# Cache GraphQL queries - different queries get different cache entries
|
|
304
|
+
graphql_query = """
|
|
305
|
+
query GetUser($id: ID!) {
|
|
306
|
+
user(id: $id) {
|
|
307
|
+
name
|
|
308
|
+
email
|
|
309
|
+
}
|
|
310
|
+
}
|
|
311
|
+
"""
|
|
312
|
+
|
|
313
|
+
response = client.post(
|
|
314
|
+
"https://api.example.com/graphql",
|
|
315
|
+
json={"query": graphql_query, "variables": {"id": "123"}},
|
|
316
|
+
headers={"X-Hishel-Body-Key": "true"} # Enable body-based caching
|
|
317
|
+
)
|
|
318
|
+
|
|
319
|
+
# Different query will be cached separately
|
|
320
|
+
response = client.post(
|
|
321
|
+
"https://api.example.com/graphql",
|
|
322
|
+
json={"query": graphql_query, "variables": {"id": "456"}},
|
|
323
|
+
headers={"X-Hishel-Body-Key": "true"}
|
|
324
|
+
)
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
**Using global configuration:**
|
|
328
|
+
|
|
329
|
+
```python
|
|
330
|
+
from hishel.httpx import SyncCacheClient
|
|
331
|
+
from hishel import FilterPolicy
|
|
332
|
+
|
|
333
|
+
# Enable body-based caching for all requests
|
|
334
|
+
client = SyncCacheClient(policy=FilterPolicy(use_body_key=True))
|
|
335
|
+
|
|
336
|
+
# All POST requests automatically include body in cache key
|
|
337
|
+
response = client.post(
|
|
338
|
+
"https://api.example.com/graphql",
|
|
339
|
+
json={"query": graphql_query, "variables": {"id": "123"}}
|
|
340
|
+
)
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
## 🏗️ Architecture
|
|
344
|
+
|
|
345
|
+
Hishel uses a **sans-I/O state machine** architecture that separates HTTP caching logic from I/O operations:
|
|
346
|
+
|
|
347
|
+
- ✅ **Correct** - Fully RFC 9111 compliant
|
|
348
|
+
- ✅ **Testable** - Easy to test without network dependencies
|
|
349
|
+
- ✅ **Flexible** - Works with any HTTP client or server
|
|
350
|
+
- ✅ **Type Safe** - Clear state transitions with full type hints
|
|
351
|
+
|
|
352
|
+
## 🔮 Roadmap
|
|
353
|
+
|
|
354
|
+
We're actively working on:
|
|
355
|
+
|
|
356
|
+
- 🎯 Performance optimizations
|
|
357
|
+
- 🎯 More integrations
|
|
358
|
+
- 🎯 Partial responses support
|
|
359
|
+
|
|
360
|
+
## 📚 Documentation
|
|
361
|
+
|
|
362
|
+
Comprehensive documentation is available at [https://hishel.com/dev](https://hishel.com/dev)
|
|
363
|
+
|
|
364
|
+
- [Getting Started](https://hishel.com)
|
|
365
|
+
- [HTTPX Integration](https://hishel.com/dev/integrations/httpx)
|
|
366
|
+
- [Requests Integration](https://hishel.com/dev/integrations/requests)
|
|
367
|
+
- [ASGI Integration](https://hishel.com/dev/asgi)
|
|
368
|
+
- [FastAPI Integration](https://hishel.com/dev/fastapi)
|
|
369
|
+
- [BlackSheep Integration](https://hishel.com/dev/integrations/blacksheep)
|
|
370
|
+
- [GraphQL Integration](https://hishel.com/dev/integrations/graphql)
|
|
371
|
+
- [Storage Backends](https://hishel.com/dev/storages)
|
|
372
|
+
- [Request/Response Metadata](https://hishel.com/dev/metadata)
|
|
373
|
+
- [RFC 9111 Specification](https://hishel.com/dev/specification)
|
|
374
|
+
|
|
375
|
+
## 🤝 Contributing
|
|
376
|
+
|
|
377
|
+
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
|
|
378
|
+
|
|
379
|
+
See our [Contributing Guide](https://hishel.com/dev/contributing) for more details.
|
|
380
|
+
|
|
381
|
+
## 📄 License
|
|
382
|
+
|
|
383
|
+
This project is licensed under the BSD-3-Clause License - see the [LICENSE](LICENSE) file for details.
|
|
384
|
+
|
|
385
|
+
## 💖 Support
|
|
386
|
+
|
|
387
|
+
If you find Hishel useful, please consider:
|
|
388
|
+
|
|
389
|
+
- ⭐ Starring the repository
|
|
390
|
+
- 🐛 Reporting bugs and issues
|
|
391
|
+
- 💡 Suggesting new features
|
|
392
|
+
- 📖 Improving documentation
|
|
393
|
+
- ☕ [Buying me a coffee](https://buymeacoffee.com/karpetrosyan)
|
|
394
|
+
|
|
395
|
+
## 🙏 Acknowledgments
|
|
396
|
+
|
|
397
|
+
Hishel is inspired by and builds upon the excellent work in the Python HTTP ecosystem, particularly:
|
|
398
|
+
|
|
399
|
+
- [HTTPX](https://github.com/encode/httpx) - A next-generation HTTP client for Python
|
|
400
|
+
- [Requests](https://github.com/psf/requests) - The classic HTTP library for Python
|
|
401
|
+
- [RFC 9111](https://www.rfc-editor.org/rfc/rfc9111.html) - HTTP Caching specification
|
|
402
|
+
|
|
403
|
+
---
|
|
404
|
+
|
|
405
|
+
<p align="center">
|
|
406
|
+
<strong>Made with ❤️ by <a href="https://github.com/karpetrosyan">Kar Petrosyan</a></strong>
|
|
407
|
+
</p>
|
|
408
|
+
|
|
409
|
+
# Changelog
|
|
410
|
+
|
|
411
|
+
All notable changes to this project will be documented in this file.
|
|
412
|
+
|
|
413
|
+
## 1.0.0b1 - 2025-10-28
|
|
414
|
+
### ♻️ Refactoring
|
|
415
|
+
- Add policies
|
|
416
|
+
|
|
417
|
+
### ⚙️ Miscellaneous Tasks
|
|
418
|
+
- Improve sans-io diagram colors
|
|
419
|
+
- Add graphql docs
|
|
420
|
+
|
|
421
|
+
### 🐛 Bug Fixes
|
|
422
|
+
- Body-sensitive responses caching
|
|
423
|
+
- Filter out `Transfer-Encoding` header for asgi responses
|
|
424
|
+
|
|
425
|
+
### 🚀 Features
|
|
426
|
+
- Add global `use_body_key` setting
|
|
427
|
+
|
|
428
|
+
## 1.0.0.dev3 - 2025-10-26
|
|
429
|
+
### ♻️ Refactoring
|
|
430
|
+
- Replace pairs with entries, simplify storage API
|
|
431
|
+
- Automatically generate httpx sync integration from async
|
|
432
|
+
|
|
433
|
+
### ⚙️ Miscellaneous Tasks
|
|
434
|
+
- Simplify metadata docs
|
|
435
|
+
- Add custom integrations docs
|
|
436
|
+
- More robust compressed response caching
|
|
437
|
+
|
|
438
|
+
### 🐛 Bug Fixes
|
|
439
|
+
- Add missing permissions into `publish.yml`
|
|
440
|
+
- Raise on consumed httpx streams, which we can't store as is (it's already decoded)
|
|
441
|
+
- Fix compressed data caching for requests
|
|
442
|
+
- Handle httpx iterable usage instead of iterator correctly
|
|
443
|
+
- Add date header for proper age calculation
|
|
444
|
+
|
|
445
|
+
### 🚀 Features
|
|
446
|
+
- Add integrations with fastapi and asgi
|
|
447
|
+
- Add blacksheep integration examples
|
|
448
|
+
- Add logging for asgi
|
|
449
|
+
|
|
450
|
+
## 1.0.0.dev2 - 2025-10-21
|
|
451
|
+
### ⚙️ Miscellaneous Tasks
|
|
452
|
+
- Remove redundant utils and tests
|
|
453
|
+
- Add import without extras check in ci
|
|
454
|
+
- Fix time travel date, explicitly specify the timezone
|
|
455
|
+
|
|
456
|
+
### 🐛 Bug Fixes
|
|
457
|
+
- Fix check for storing auth requests
|
|
458
|
+
- Don't raise an error on 3xx during revalidation
|
|
459
|
+
|
|
460
|
+
### 🚀 Features
|
|
461
|
+
- Add hishel_created_at response metadata
|
|
462
|
+
|
|
463
|
+
## 1.0.0.dev1 - 2025-10-21
|
|
464
|
+
### ⚙️ Miscellaneous Tasks
|
|
465
|
+
- Remove some redundant utils methods
|
|
466
|
+
|
|
467
|
+
### 📦 Dependencies
|
|
468
|
+
- Make httpx and async libs optional dependencies
|
|
469
|
+
- Make `anysqlite` optional dependency
|
|
470
|
+
- Install async extra with httpx
|
|
471
|
+
- Improve git-cliff
|
|
472
|
+
|
|
473
|
+
## 1.0.0.dev0 - 2025-10-19
|
|
474
|
+
### ⚙️ Miscellaneous Tasks
|
|
475
|
+
- Use mike powered versioning
|
|
476
|
+
- Improve docs versioning, deploy dev doc on ci
|
|
477
|
+
|
|
478
|
+
## 0.1.5 - 2025-10-18
|
|
479
|
+
### ⚙️ Miscellaneous Tasks
|
|
480
|
+
- Remove some redundant files from repo
|
|
481
|
+
|
|
482
|
+
### 🐛 Bug Fixes
|
|
483
|
+
- Fix some line breaks
|
|
484
|
+
|
|
485
|
+
### 🚀 Features
|
|
486
|
+
- Set chunk size to 128KB for httpx to reduce SQLite read/writes
|
|
487
|
+
- Better cache-control parsing
|
|
488
|
+
- Add close method to storages API (#384)
|
|
489
|
+
- Increase requests buffer size to 128KB, disable charset detection
|
|
490
|
+
|
|
491
|
+
## 0.1.4 - 2025-10-14
|
|
492
|
+
### ⚙️ Miscellaneous Tasks
|
|
493
|
+
- Improve CI (#369)
|
|
494
|
+
- Remove src folder (#373)
|
|
495
|
+
- Temporary remove python3.14 from CI
|
|
496
|
+
- Add sqlite tests for new storage
|
|
497
|
+
- Move some tests to beta
|
|
498
|
+
|
|
499
|
+
### 🐛 Bug Fixes
|
|
500
|
+
- Create an sqlite file in a cache folder
|
|
501
|
+
- Fix beta imports
|
|
502
|
+
|
|
503
|
+
### 🚀 Features
|
|
504
|
+
- Add support for a sans-IO API (#366)
|
|
505
|
+
- Allow already consumed streams with `CacheTransport` (#377)
|
|
506
|
+
- Add sqlite storage for beta storages
|
|
507
|
+
- Get rid of some locks from sqlite storage
|
|
508
|
+
- Better async implemetation for sqlite storage
|
|
509
|
+
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
hishel/__init__.py,sha256=yqBws4FNvfqKgVg3e69mbTv6iit722D9bQVPkunTBYA,1655
|
|
2
|
+
hishel/_async_cache.py,sha256=4wm6YBL9ClNOg4WbEkALTJVCIXuzQU80MVem2C3hHrQ,8785
|
|
3
|
+
hishel/_async_httpx.py,sha256=WB35o7CseRDz89dpqoWNLXYEkDxqeSo709eR3oPXP7Q,7536
|
|
4
|
+
hishel/_policies.py,sha256=1ae_rmDF7oaG91-lQyOGVaTrRX8uI2GImmu5gN6WJa4,1135
|
|
5
|
+
hishel/_sync_cache.py,sha256=k0AN0M--yR4Jc6SiAreaxPUFiwEt5Dx7wi9jqW9sy50,8510
|
|
6
|
+
hishel/_sync_httpx.py,sha256=FbnJrdoLftPDVNUzYkAtz-JOTNtiBPJ2c1ZOcU0JnmE,7368
|
|
7
|
+
hishel/_utils.py,sha256=kD5ki4PKeYsNBMh3tAjsXggF2-_oeNz6aVlARxyl0H0,3842
|
|
8
|
+
hishel/asgi.py,sha256=ocXzqrrYGazeJxlKFcz1waoKvKGOqJ7YBEAmly4Towk,14998
|
|
9
|
+
hishel/fastapi.py,sha256=CVWCyXTxBPwG_XALo-Oldekv4lqMgH2-W-PPZ9rZjXg,10826
|
|
10
|
+
hishel/httpx.py,sha256=99a8X9COPiPHSgGW61O2uMWMZB7dY93Ty9DTCJ9C18Q,467
|
|
11
|
+
hishel/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
12
|
+
hishel/requests.py,sha256=FbOBMvgNSWkH0Bh0qZdr-dhCYG6siR5Lmxcu5eMay3s,6409
|
|
13
|
+
hishel/_core/_headers.py,sha256=hGaT6o1F-gs1pm5RpdGb0IMQL3uJYDH1xpwJLy28Cys,17514
|
|
14
|
+
hishel/_core/_spec.py,sha256=8JIojgjSJV0bJp0COJLim4T8cjDPLW3XmUr4ylF9EiI,103461
|
|
15
|
+
hishel/_core/models.py,sha256=EabP2qnjYVzhPWhQer3QFmdDE6TDbqEBEqPHzv25VnA,7978
|
|
16
|
+
hishel/_core/_storages/_async_base.py,sha256=iZ6Mb30P0ho5h4UU5bgOrcsSMZ1427j9tht-tupZs68,2106
|
|
17
|
+
hishel/_core/_storages/_async_sqlite.py,sha256=QNo5oWnnHAU0rTPJJbE9d6__xG_jWrG3-atoyE2j3q0,15555
|
|
18
|
+
hishel/_core/_storages/_packing.py,sha256=mC8LMFQ5uPfFOgingKm2WKFO_DwcZ1OjTgI6xc0hfJI,3708
|
|
19
|
+
hishel/_core/_storages/_sync_base.py,sha256=qfOvcFY5qvrzSh4ztV2Trlxft-BF7An5SFsLlEb8EeE,2075
|
|
20
|
+
hishel/_core/_storages/_sync_sqlite.py,sha256=A-L6fDU1JvVDzHNzV396V3U3sFPLycrxSnD00DHrTvs,15048
|
|
21
|
+
hishel-1.0.0b1.dist-info/METADATA,sha256=4zcgADpkqXTQOhy4ktV3m057L3gklXGD0f6g2_kjPvI,15412
|
|
22
|
+
hishel-1.0.0b1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
|
|
23
|
+
hishel-1.0.0b1.dist-info/licenses/LICENSE,sha256=1qQj7pE0V2O9OIedvyOgLGLvZLaPd3nFEup3IBEOZjQ,1493
|
|
24
|
+
hishel-1.0.0b1.dist-info/RECORD,,
|
hishel/_async/__init__.py
DELETED
hishel/_async/_client.py
DELETED
|
@@ -1,30 +0,0 @@
|
|
|
1
|
-
import typing as tp
|
|
2
|
-
|
|
3
|
-
import httpx
|
|
4
|
-
|
|
5
|
-
from ._transports import AsyncCacheTransport
|
|
6
|
-
|
|
7
|
-
__all__ = ("AsyncCacheClient",)
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
class AsyncCacheClient(httpx.AsyncClient):
|
|
11
|
-
def __init__(self, *args: tp.Any, **kwargs: tp.Any):
|
|
12
|
-
self._storage = kwargs.pop("storage") if "storage" in kwargs else None
|
|
13
|
-
self._controller = kwargs.pop("controller") if "controller" in kwargs else None
|
|
14
|
-
super().__init__(*args, **kwargs)
|
|
15
|
-
|
|
16
|
-
def _init_transport(self, *args, **kwargs) -> AsyncCacheTransport: # type: ignore
|
|
17
|
-
_transport = super()._init_transport(*args, **kwargs)
|
|
18
|
-
return AsyncCacheTransport(
|
|
19
|
-
transport=_transport,
|
|
20
|
-
storage=self._storage,
|
|
21
|
-
controller=self._controller,
|
|
22
|
-
)
|
|
23
|
-
|
|
24
|
-
def _init_proxy_transport(self, *args, **kwargs) -> AsyncCacheTransport: # type: ignore
|
|
25
|
-
_transport = super()._init_proxy_transport(*args, **kwargs) # pragma: no cover
|
|
26
|
-
return AsyncCacheTransport( # pragma: no cover
|
|
27
|
-
transport=_transport,
|
|
28
|
-
storage=self._storage,
|
|
29
|
-
controller=self._controller,
|
|
30
|
-
)
|