hishel 0.1.4__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/_core/_headers.py +646 -0
- 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} +41 -30
- 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 -260
- hishel/beta/_core/_base/_storages/_packing.py +0 -165
- hishel/beta/_core/_headers.py +0 -301
- hishel/beta/_core/_sync/_storages/_sqlite.py +0 -411
- hishel/beta/_sync_cache.py +0 -167
- hishel/beta/httpx.py +0 -317
- hishel-0.1.4.dist-info/METADATA +0 -404
- hishel-0.1.4.dist-info/RECORD +0 -41
- {hishel-0.1.4.dist-info → hishel-1.0.0b1.dist-info}/WHEEL +0 -0
- {hishel-0.1.4.dist-info → hishel-1.0.0b1.dist-info}/licenses/LICENSE +0 -0
|
@@ -1,16 +1,16 @@
|
|
|
1
1
|
from __future__ import annotations
|
|
2
2
|
|
|
3
3
|
from io import RawIOBase
|
|
4
|
-
from typing import Iterator, Mapping, Optional, overload
|
|
4
|
+
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
|
|
@@ -23,8 +23,11 @@ except ImportError: # pragma: no cover
|
|
|
23
23
|
"Install hishel with 'pip install hishel[requests]'."
|
|
24
24
|
)
|
|
25
25
|
|
|
26
|
+
# 128 KB
|
|
27
|
+
CHUNK_SIZE = 131072
|
|
26
28
|
|
|
27
|
-
|
|
29
|
+
|
|
30
|
+
class _IteratorStream(RawIOBase):
|
|
28
31
|
def __init__(self, iterator: Iterator[bytes]):
|
|
29
32
|
self.iterator = iterator
|
|
30
33
|
self.leftover = b""
|
|
@@ -58,18 +61,18 @@ class IteratorStream(RawIOBase):
|
|
|
58
61
|
|
|
59
62
|
|
|
60
63
|
@overload
|
|
61
|
-
def
|
|
64
|
+
def _requests_to_internal(
|
|
62
65
|
model: requests.models.PreparedRequest,
|
|
63
66
|
) -> Request: ...
|
|
64
67
|
|
|
65
68
|
|
|
66
69
|
@overload
|
|
67
|
-
def
|
|
70
|
+
def _requests_to_internal(
|
|
68
71
|
model: requests.models.Response,
|
|
69
72
|
) -> Response: ...
|
|
70
73
|
|
|
71
74
|
|
|
72
|
-
def
|
|
75
|
+
def _requests_to_internal(
|
|
73
76
|
model: requests.models.PreparedRequest | requests.models.Response,
|
|
74
77
|
) -> Request | Response:
|
|
75
78
|
if isinstance(model, requests.models.PreparedRequest):
|
|
@@ -90,7 +93,7 @@ def requests_to_internal(
|
|
|
90
93
|
)
|
|
91
94
|
elif isinstance(model, requests.models.Response):
|
|
92
95
|
try:
|
|
93
|
-
stream = model.raw.stream(amt=
|
|
96
|
+
stream = model.raw.stream(amt=CHUNK_SIZE, decode_content=None)
|
|
94
97
|
except requests.exceptions.StreamConsumedError:
|
|
95
98
|
stream = iter([model.content])
|
|
96
99
|
|
|
@@ -105,23 +108,27 @@ def requests_to_internal(
|
|
|
105
108
|
|
|
106
109
|
|
|
107
110
|
@overload
|
|
108
|
-
def
|
|
111
|
+
def _internal_to_requests(model: Request) -> requests.models.PreparedRequest: ...
|
|
109
112
|
@overload
|
|
110
|
-
def
|
|
111
|
-
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:
|
|
112
117
|
if isinstance(model, Response):
|
|
113
118
|
response = requests.models.Response()
|
|
114
119
|
|
|
115
120
|
assert isinstance(model.stream, Iterator)
|
|
116
|
-
|
|
117
|
-
stream = IteratorStream(model.stream)
|
|
121
|
+
stream = _IteratorStream(model.stream)
|
|
118
122
|
|
|
119
123
|
urllib_response = HTTPResponse(
|
|
120
124
|
body=stream,
|
|
121
|
-
headers={
|
|
125
|
+
headers={
|
|
126
|
+
**model.headers,
|
|
127
|
+
**{snake_to_header(k): str(v) for k, v in model.metadata.items()},
|
|
128
|
+
},
|
|
122
129
|
status=model.status_code,
|
|
123
130
|
preload_content=False,
|
|
124
|
-
decode_content=
|
|
131
|
+
decode_content=False,
|
|
125
132
|
)
|
|
126
133
|
|
|
127
134
|
# Set up the response object
|
|
@@ -130,7 +137,6 @@ def internal_to_requests(model: Request | Response) -> requests.models.Response
|
|
|
130
137
|
response.headers.update(model.headers)
|
|
131
138
|
response.headers.update({snake_to_header(k): str(v) for k, v in model.metadata.items()})
|
|
132
139
|
response.url = "" # Will be set by requests
|
|
133
|
-
response.encoding = response.apparent_encoding
|
|
134
140
|
|
|
135
141
|
return response
|
|
136
142
|
else:
|
|
@@ -157,16 +163,15 @@ class CacheAdapter(HTTPAdapter):
|
|
|
157
163
|
max_retries: int = 0,
|
|
158
164
|
pool_block: bool = False,
|
|
159
165
|
storage: SyncBaseStorage | None = None,
|
|
160
|
-
|
|
161
|
-
ignore_specification: bool = False,
|
|
166
|
+
policy: CachePolicy | None = None,
|
|
162
167
|
):
|
|
163
168
|
super().__init__(pool_connections, pool_maxsize, max_retries, pool_block)
|
|
164
169
|
self._cache_proxy = SyncCacheProxy(
|
|
165
|
-
|
|
170
|
+
request_sender=self._send_request,
|
|
166
171
|
storage=storage,
|
|
167
|
-
|
|
168
|
-
ignore_specification=ignore_specification,
|
|
172
|
+
policy=policy,
|
|
169
173
|
)
|
|
174
|
+
self.storage = self._cache_proxy.storage
|
|
170
175
|
|
|
171
176
|
def send(
|
|
172
177
|
self,
|
|
@@ -177,9 +182,9 @@ class CacheAdapter(HTTPAdapter):
|
|
|
177
182
|
cert: None | bytes | str | tuple[bytes | str, bytes | str] = None,
|
|
178
183
|
proxies: Mapping[str, str] | None = None,
|
|
179
184
|
) -> requests.models.Response:
|
|
180
|
-
internal_request =
|
|
185
|
+
internal_request = _requests_to_internal(request)
|
|
181
186
|
internal_response = self._cache_proxy.handle_request(internal_request)
|
|
182
|
-
response =
|
|
187
|
+
response = _internal_to_requests(internal_response)
|
|
183
188
|
|
|
184
189
|
# Set the original request on the response
|
|
185
190
|
response.request = request
|
|
@@ -187,7 +192,13 @@ class CacheAdapter(HTTPAdapter):
|
|
|
187
192
|
|
|
188
193
|
return response
|
|
189
194
|
|
|
190
|
-
def
|
|
191
|
-
requests_request =
|
|
192
|
-
response = super().send(
|
|
193
|
-
|
|
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)
|
|
202
|
+
|
|
203
|
+
def close(self) -> Any:
|
|
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,,
|