hishel 1.0.0.dev2__tar.gz → 1.0.0.dev3__tar.gz

{hishel-1.0.0.dev2 → hishel-1.0.0.dev3}/CHANGELOG.md

@@ -2,10 +2,33 @@
 
 All notable changes to this project will be documented in this file.
 
+## 1.0.0.dev3 - 2025-10-26
+### ♻️ Refactoring
+- Replace pairs with entries, simplify storage API
+- Automatically generate httpx sync integration from async
+
+### ⚙️ Miscellaneous Tasks
+- Simplify metadata docs
+- Add custom integrations docs
+- More robust compressed response caching
+
+### 🐛 Bug Fixes
+- Add missing permissions into `publish.yml`
+- Raise on consumed httpx streams, which we can't store as is (it's already decoded)
+- Fix compressed data caching for requests
+- Handle httpx iterable usage instead of iterator correctly
+- Add date header for proper age calculation
+
+### 🚀 Features
+- Add integrations with fastapi and asgi
+- Add blacksheep integration examples
+- Add logging for asgi
+
 ## 1.0.0.dev2 - 2025-10-21
 ### ⚙️ Miscellaneous Tasks
 - Remove redundant utils and tests
 - Add import without extras check in ci
+- Fix time travel date, explicitly specify the timezone
 
 ### 🐛 Bug Fixes
 - Fix check for storing auth requests

{hishel-1.0.0.dev2 → hishel-1.0.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hishel
-Version: 1.0.0.dev2
+Version: 1.0.0.dev3
 Summary:  Elegant HTTP Caching for Python
 Project-URL: Homepage, https://hishel.com
 Project-URL: Source, https://github.com/karpetrosyan/hishel
@@ -29,6 +29,8 @@ Requires-Dist: typing-extensions>=4.14.1
 Provides-Extra: async
 Requires-Dist: anyio>=4.9.0; extra == 'async'
 Requires-Dist: anysqlite>=0.0.5; extra == 'async'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.119.1; extra == 'fastapi'
 Provides-Extra: httpx
 Requires-Dist: anyio>=4.9.0; extra == 'httpx'
 Requires-Dist: anysqlite>=0.0.5; extra == 'httpx'
@@ -37,6 +39,7 @@ Provides-Extra: requests
 Requires-Dist: requests>=2.32.5; extra == 'requests'
 Description-Content-Type: text/markdown
 
+
 <p align="center">
   <img alt="Hishel Logo" width="350" src="https://raw.githubusercontent.com/karpetrosyan/hishel/master/docs/static/Shelkopryad_350x250_yellow.png#gh-dark-mode-only">
   <img alt="Hishel Logo" width="350" src="https://raw.githubusercontent.com/karpetrosyan/hishel/master/docs/static/Shelkopryad_350x250_black.png#gh-light-mode-only">
@@ -73,14 +76,15 @@ Description-Content-Type: text/markdown
 ## ✨ Features
 
 - 🎯 **RFC 9111 Compliant** - Fully compliant with the latest HTTP caching specification
-- 🔌 **Easy Integration** - Drop-in support for HTTPX and Requests
+- 🔌 **Easy Integration** - Drop-in support for HTTPX, Requests, ASGI, FastAPI, and BlackSheep
 - 💾 **Flexible Storage** - SQLite backend with more coming soon
 - ⚡ **High Performance** - Efficient caching with minimal overhead
 - 🔄 **Async & Sync** - Full support for both synchronous and asynchronous workflows
 - 🎨 **Type Safe** - Fully typed with comprehensive type hints
 - 🧪 **Well Tested** - Extensive test coverage and battle-tested
 - 🎛️ **Configurable** - Fine-grained control over caching behavior
-- 🌐 **Future Ready** - Designed for easy integration with any HTTP client/server
+- � **Memory Efficient** - Streaming support prevents loading large payloads into memory
+- 🌐 **Universal** - Works with any ASGI application (Starlette, Litestar, BlackSheep, etc.)
 
 ## 📦 Installation
 
@@ -90,19 +94,23 @@ pip install hishel
 
 ### Optional Dependencies
 
-Install with specific HTTP client support:
+Install with specific integration support:
 
 ```bash
 pip install hishel[httpx]      # For HTTPX support
 pip install hishel[requests]   # For Requests support
+pip install hishel[fastapi]    # For FastAPI support (includes ASGI)
 ```
 
-Or install both:
+Or install multiple:
 
 ```bash
-pip install hishel[httpx,requests]
+pip install hishel[httpx,requests,fastapi]
 ```
 
+> [!NOTE]
+> ASGI middleware has no extra dependencies - it's included in the base installation.
+ 
 ## 🚀 Quick Start
 
 ### With HTTPX
@@ -156,6 +164,65 @@ response = session.get("https://api.example.com/data")
 print(response.headers.get("X-Hishel-From-Cache"))  # "True"
 ```
 
+### With ASGI Applications
+
+Add caching middleware to any ASGI application:
+
+```python
+from hishel.asgi import ASGICacheMiddleware
+
+# Wrap your ASGI app
+app = ASGICacheMiddleware(app)
+
+# Or configure with options
+from hishel import AsyncSqliteStorage, CacheOptions
+
+app = ASGICacheMiddleware(
+    app,
+    storage=AsyncSqliteStorage(),
+    cache_options=CacheOptions(shared=True)
+)
+```
+
+### With FastAPI
+
+Add Cache-Control headers using the `cache()` dependency:
+
+```python
+from fastapi import FastAPI
+from hishel.fastapi import cache
+
+app = FastAPI()
+
+@app.get("/api/data", dependencies=[cache(max_age=300, public=True)])
+async def get_data():
+    # Cache-Control: public, max-age=300
+    return {"data": "cached for 5 minutes"}
+  
+# Optionally wrap with ASGI middleware for local caching according to specified rules
+from hishel.asgi import ASGICacheMiddleware
+from hishel import AsyncSqliteStorage
+
+app = ASGICacheMiddleware(app, storage=AsyncSqliteStorage())
+```
+
+### With BlackSheep
+
+Use BlackSheep's native `cache_control` decorator with Hishel's ASGI middleware:
+
+```python
+from blacksheep import Application, get
+from blacksheep.server.headers.cache import cache_control
+
+app = Application()
+
+@get("/api/data")
+@cache_control(max_age=300, public=True)
+async def get_data():
+    # Cache-Control: public, max-age=300
+    return {"data": "cached for 5 minutes"}
+```
+
 ## 🎛️ Advanced Configuration
 
 ### Custom Cache Options
@@ -214,7 +281,11 @@ Comprehensive documentation is available at [https://hishel.com/dev](https://his
 - [Getting Started](https://hishel.com)
 - [HTTPX Integration](https://hishel.com/dev/integrations/httpx)
 - [Requests Integration](https://hishel.com/dev/integrations/requests)
+- [ASGI Integration](https://hishel.com/dev/asgi)
+- [FastAPI Integration](https://hishel.com/dev/fastapi)
+- [BlackSheep Integration](https://hishel.com/dev/integrations/blacksheep)
 - [Storage Backends](https://hishel.com/dev/storages)
+- [Request/Response Metadata](https://hishel.com/dev/metadata)
 - [RFC 9111 Specification](https://hishel.com/dev/specification)
 
 ## 🤝 Contributing
@@ -255,10 +326,33 @@ Hishel is inspired by and builds upon the excellent work in the Python HTTP ecos
 
 All notable changes to this project will be documented in this file.
 
+## 1.0.0.dev3 - 2025-10-26
+### ♻️ Refactoring
+- Replace pairs with entries, simplify storage API
+- Automatically generate httpx sync integration from async
+
+### ⚙️ Miscellaneous Tasks
+- Simplify metadata docs
+- Add custom integrations docs
+- More robust compressed response caching
+
+### 🐛 Bug Fixes
+- Add missing permissions into `publish.yml`
+- Raise on consumed httpx streams, which we can't store as is (it's already decoded)
+- Fix compressed data caching for requests
+- Handle httpx iterable usage instead of iterator correctly
+- Add date header for proper age calculation
+
+### 🚀 Features
+- Add integrations with fastapi and asgi
+- Add blacksheep integration examples
+- Add logging for asgi
+
 ## 1.0.0.dev2 - 2025-10-21
 ### ⚙️ Miscellaneous Tasks
 - Remove redundant utils and tests
 - Add import without extras check in ci
+- Fix time travel date, explicitly specify the timezone
 
 ### 🐛 Bug Fixes
 - Fix check for storing auth requests

{hishel-1.0.0.dev2 → hishel-1.0.0.dev3}/README.md

@@ -1,3 +1,4 @@
+
 <p align="center">
   <img alt="Hishel Logo" width="350" src="https://raw.githubusercontent.com/karpetrosyan/hishel/master/docs/static/Shelkopryad_350x250_yellow.png#gh-dark-mode-only">
   <img alt="Hishel Logo" width="350" src="https://raw.githubusercontent.com/karpetrosyan/hishel/master/docs/static/Shelkopryad_350x250_black.png#gh-light-mode-only">
@@ -34,14 +35,15 @@
 ## ✨ Features
 
 - 🎯 **RFC 9111 Compliant** - Fully compliant with the latest HTTP caching specification
-- 🔌 **Easy Integration** - Drop-in support for HTTPX and Requests
+- 🔌 **Easy Integration** - Drop-in support for HTTPX, Requests, ASGI, FastAPI, and BlackSheep
 - 💾 **Flexible Storage** - SQLite backend with more coming soon
 - ⚡ **High Performance** - Efficient caching with minimal overhead
 - 🔄 **Async & Sync** - Full support for both synchronous and asynchronous workflows
 - 🎨 **Type Safe** - Fully typed with comprehensive type hints
 - 🧪 **Well Tested** - Extensive test coverage and battle-tested
 - 🎛️ **Configurable** - Fine-grained control over caching behavior
-- 🌐 **Future Ready** - Designed for easy integration with any HTTP client/server
+- � **Memory Efficient** - Streaming support prevents loading large payloads into memory
+- 🌐 **Universal** - Works with any ASGI application (Starlette, Litestar, BlackSheep, etc.)
 
 ## 📦 Installation
 
@@ -51,19 +53,23 @@ pip install hishel
 
 ### Optional Dependencies
 
-Install with specific HTTP client support:
+Install with specific integration support:
 
 ```bash
 pip install hishel[httpx]      # For HTTPX support
 pip install hishel[requests]   # For Requests support
+pip install hishel[fastapi]    # For FastAPI support (includes ASGI)
 ```
 
-Or install both:
+Or install multiple:
 
 ```bash
-pip install hishel[httpx,requests]
+pip install hishel[httpx,requests,fastapi]
 ```
 
+> [!NOTE]
+> ASGI middleware has no extra dependencies - it's included in the base installation.
+ 
 ## 🚀 Quick Start
 
 ### With HTTPX
@@ -117,6 +123,65 @@ response = session.get("https://api.example.com/data")
 print(response.headers.get("X-Hishel-From-Cache"))  # "True"
 ```
 
+### With ASGI Applications
+
+Add caching middleware to any ASGI application:
+
+```python
+from hishel.asgi import ASGICacheMiddleware
+
+# Wrap your ASGI app
+app = ASGICacheMiddleware(app)
+
+# Or configure with options
+from hishel import AsyncSqliteStorage, CacheOptions
+
+app = ASGICacheMiddleware(
+    app,
+    storage=AsyncSqliteStorage(),
+    cache_options=CacheOptions(shared=True)
+)
+```
+
+### With FastAPI
+
+Add Cache-Control headers using the `cache()` dependency:
+
+```python
+from fastapi import FastAPI
+from hishel.fastapi import cache
+
+app = FastAPI()
+
+@app.get("/api/data", dependencies=[cache(max_age=300, public=True)])
+async def get_data():
+    # Cache-Control: public, max-age=300
+    return {"data": "cached for 5 minutes"}
+  
+# Optionally wrap with ASGI middleware for local caching according to specified rules
+from hishel.asgi import ASGICacheMiddleware
+from hishel import AsyncSqliteStorage
+
+app = ASGICacheMiddleware(app, storage=AsyncSqliteStorage())
+```
+
+### With BlackSheep
+
+Use BlackSheep's native `cache_control` decorator with Hishel's ASGI middleware:
+
+```python
+from blacksheep import Application, get
+from blacksheep.server.headers.cache import cache_control
+
+app = Application()
+
+@get("/api/data")
+@cache_control(max_age=300, public=True)
+async def get_data():
+    # Cache-Control: public, max-age=300
+    return {"data": "cached for 5 minutes"}
+```
+
 ## 🎛️ Advanced Configuration
 
 ### Custom Cache Options
@@ -175,7 +240,11 @@ Comprehensive documentation is available at [https://hishel.com/dev](https://his
 - [Getting Started](https://hishel.com)
 - [HTTPX Integration](https://hishel.com/dev/integrations/httpx)
 - [Requests Integration](https://hishel.com/dev/integrations/requests)
+- [ASGI Integration](https://hishel.com/dev/asgi)
+- [FastAPI Integration](https://hishel.com/dev/fastapi)
+- [BlackSheep Integration](https://hishel.com/dev/integrations/blacksheep)
 - [Storage Backends](https://hishel.com/dev/storages)
+- [Request/Response Metadata](https://hishel.com/dev/metadata)
 - [RFC 9111 Specification](https://hishel.com/dev/specification)
 
 ## 🤝 Contributing

{hishel-1.0.0.dev2 → hishel-1.0.0.dev3}/hishel/__init__.py

@@ -1,8 +1,7 @@
-from hishel._core._async._storages._sqlite import AsyncSqliteStorage
-from hishel._core._base._storages._base import (
-    AsyncBaseStorage as AsyncBaseStorage,
-    SyncBaseStorage as SyncBaseStorage,
-)
+from hishel._core._storages._async_sqlite import AsyncSqliteStorage
+from hishel._core._storages._async_base import AsyncBaseStorage
+from hishel._core._storages._sync_sqlite import SyncSqliteStorage
+from hishel._core._storages._sync_base import SyncBaseStorage
 from hishel._core._headers import Headers as Headers
 from hishel._core._spec import (
     AnyState as AnyState,
@@ -11,21 +10,21 @@ from hishel._core._spec import (
     CouldNotBeStored as CouldNotBeStored,
     FromCache as FromCache,
     IdleClient as IdleClient,
+    InvalidateEntries,
     NeedRevalidation as NeedRevalidation,
     NeedToBeUpdated as NeedToBeUpdated,
     State as State,
     StoreAndUse as StoreAndUse,
     create_idle_state as create_idle_state,
 )
-from hishel._core._sync._storages._sqlite import SyncSqliteStorage
 from hishel._core.models import (
-    CompletePair as CompletePair,
-    IncompletePair as IncompletePair,
-    Pair as Pair,
-    PairMeta as PairMeta,
+    Entry as Entry,
+    EntryMeta as EntryMeta,
     Request as Request,
     Response,
 )
+from hishel._async_cache import AsyncCacheProxy as AsyncCacheProxy
+from hishel._sync_cache import SyncCacheProxy as SyncCacheProxy
 
 __all__ = (
     # New API
@@ -41,14 +40,13 @@ __all__ = (
     "State",
     "StoreAndUse",
     "CouldNotBeStored",
+    "InvalidateEntries",
     "create_idle_state",
     ## Models
     "Request",
     "Response",
-    "Pair",
-    "IncompletePair",
-    "CompletePair",
-    "PairMeta",
+    "Entry",
+    "EntryMeta",
     ## Headers
     "Headers",
     ## Storages
@@ -56,4 +54,7 @@ __all__ = (
     "AsyncBaseStorage",
     "SyncSqliteStorage",
     "AsyncSqliteStorage",
+    # Proxy
+    "AsyncCacheProxy",
+    "SyncCacheProxy",
 )

{hishel-1.0.0.dev2 → hishel-1.0.0.dev3}/hishel/_async_cache.py

@@ -4,7 +4,7 @@ import hashlib
 import logging
 import time
 from dataclasses import replace
-from typing import AsyncIterator, Awaitable, Callable
+from typing import AsyncIterable, AsyncIterator, Awaitable, Callable
 
 from typing_extensions import assert_never
 
@@ -24,8 +24,9 @@ from hishel import (
     StoreAndUse,
     create_idle_state,
 )
-from hishel._core._spec import InvalidatePairs, vary_headers_match
-from hishel._core.models import CompletePair, ResponseMetadata
+from hishel._core._spec import InvalidateEntries, vary_headers_match
+from hishel._core.models import Entry, ResponseMetadata
+from hishel._utils import make_async_iterator
 
 logger = logging.getLogger("hishel.integrations.clients")
 
@@ -42,12 +43,12 @@ class AsyncCacheProxy:
 
     def __init__(
         self,
-        send_request: Callable[[Request], Awaitable[Response]],
+        request_sender: Callable[[Request], Awaitable[Response]],
         storage: AsyncBaseStorage | None = None,
         cache_options: CacheOptions | None = None,
         ignore_specification: bool = False,
     ) -> None:
-        self.send_request = send_request
+        self.send_request = request_sender
         self.storage = storage if storage is not None else AsyncSqliteStorage()
         self.cache_options = cache_options if cache_options is not None else CacheOptions()
         self.ignore_specification = ignore_specification
@@ -59,26 +60,30 @@ class AsyncCacheProxy:
 
     async def _get_key_for_request(self, request: Request) -> str:
         if request.metadata.get("hishel_body_key"):
-            assert isinstance(request.stream, AsyncIterator)
+            assert isinstance(request.stream, (AsyncIterator, AsyncIterable))
             collected = b"".join([chunk async for chunk in request.stream])
             hash_ = hashlib.sha256(collected).hexdigest()
+            request.stream = make_async_iterator([collected])
             return f"{str(request.url)}-{hash_}"
-        return str(request.url)
+        return hashlib.sha256(str(request.url).encode("utf-8")).hexdigest()
 
-    async def _maybe_refresh_pair_ttl(self, pair: CompletePair) -> None:
+    async def _maybe_refresh_pair_ttl(self, pair: Entry) -> None:
         if pair.request.metadata.get("hishel_refresh_ttl_on_access"):
-            await self.storage.update_pair(
+            await self.storage.update_entry(
                 pair.id,
-                lambda complete_pair: replace(complete_pair, meta=replace(complete_pair.meta, created_at=time.time())),
+                lambda complete_pair: replace(
+                    complete_pair,
+                    meta=replace(complete_pair.meta, created_at=time.time()),
+                ),
             )
 
     async def _handle_request_ignoring_spec(self, request: Request) -> Response:
         logger.debug("Trying to get cached response ignoring specification")
-        pairs = await self.storage.get_pairs(await self._get_key_for_request(request))
+        entries = await self.storage.get_entries(await self._get_key_for_request(request))
 
-        logger.debug(f"Found {len(pairs)} cached pairs for the request")
+        logger.debug(f"Found {len(entries)} cached entries for the request")
 
-        for pair in pairs:
+        for pair in entries:
             if (
                 str(pair.request.url) == str(request.url)
                 and pair.request.method == request.method
@@ -101,16 +106,15 @@ class AsyncCacheProxy:
                 await self._maybe_refresh_pair_ttl(pair)
                 return pair.response
 
-        incomplete_pair = await self.storage.create_pair(
-            request,
-        )
-        response = await self.send_request(incomplete_pair.request)
+        response = await self.send_request(request)
 
         logger.debug("Storing response in cache ignoring specification")
-        complete_pair = await self.storage.add_response(
-            incomplete_pair.id, response, await self._get_key_for_request(request)
+        entry = await self.storage.create_entry(
+            request,
+            response,
+            await self._get_key_for_request(request),
         )
-        return complete_pair.response
+        return entry.response
 
     async def _handle_request_respecting_spec(self, request: Request) -> Response:
         state: AnyState = create_idle_state("client", self.cache_options)
@@ -132,25 +136,26 @@ class AsyncCacheProxy:
                 return state.pair.response
             elif isinstance(state, NeedToBeUpdated):
                 state = await self._handle_update(state)
-            elif isinstance(state, InvalidatePairs):
-                state = await self._handle_invalidate_pairs(state)
+            elif isinstance(state, InvalidateEntries):
+                state = await self._handle_invalidate_entries(state)
             else:
                 assert_never(state)
 
         raise RuntimeError("Unreachable")
 
     async def _handle_idle_state(self, state: IdleClient, request: Request) -> AnyState:
-        stored_pairs = await self.storage.get_pairs(await self._get_key_for_request(request))
-        return state.next(request, stored_pairs)
+        stored_entries = await self.storage.get_entries(await self._get_key_for_request(request))
+        return state.next(request, stored_entries)
 
     async def _handle_cache_miss(self, state: CacheMiss) -> AnyState:
-        incomplete_pair = await self.storage.create_pair(state.request)
-        response = await self.send_request(incomplete_pair.request)
-        return state.next(response, incomplete_pair.id)
+        response = await self.send_request(state.request)
+        return state.next(response)
 
     async def _handle_store_and_use(self, state: StoreAndUse, request: Request) -> Response:
-        complete_pair = await self.storage.add_response(
-            state.pair_id, state.response, await self._get_key_for_request(request)
+        complete_pair = await self.storage.create_entry(
+            request,
+            state.response,
+            await self._get_key_for_request(request),
         )
         return complete_pair.response
 
@@ -159,16 +164,17 @@ class AsyncCacheProxy:
         return state.next(revalidation_response)
 
     async def _handle_update(self, state: NeedToBeUpdated) -> AnyState:
-        for pair in state.updating_pairs:
-            await self.storage.update_pair(
-                pair.id,
+        for entry in state.updating_entries:
+            await self.storage.update_entry(
+                entry.id,
                 lambda complete_pair: replace(
-                    complete_pair, response=replace(pair.response, headers=pair.response.headers)
+                    complete_pair,
+                    response=replace(entry.response, headers=entry.response.headers),
                 ),
             )
         return state.next()
 
-    async def _handle_invalidate_pairs(self, state: InvalidatePairs) -> AnyState:
-        for pair_id in state.pair_ids:
-            await self.storage.remove(pair_id)
+    async def _handle_invalidate_entries(self, state: InvalidateEntries) -> AnyState:
+        for entry_id in state.entry_ids:
+            await self.storage.remove_entry(entry_id)
         return state.next()