hishel 1.0.0.dev3__tar.gz → 1.1.0__tar.gz

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

@@ -2,6 +2,35 @@
 
 All notable changes to this project will be documented in this file.
 
+## 1.1.0 - 2025-10-31
+### ⚙️ Miscellaneous Tasks
+- Add in memory example
+
+### 🐛 Bug Fixes
+- Pass any response with non-expected status code on revalidation to client
+
+### 🚀 Features
+- Allow setting storage base with via `database_path` for sqlite storage
+
+## 1.0.0 - 2025-10-28
+### ⚙️ Miscellaneous Tasks
+- Add examples, improve docs
+
+## 1.0.0b1 - 2025-10-28
+### ♻️ Refactoring
+- Add policies
+
+### ⚙️ Miscellaneous Tasks
+- Improve sans-io diagram colors
+- Add graphql docs
+
+### 🐛 Bug Fixes
+- Body-sensitive responses caching
+- Filter out `Transfer-Encoding` header for asgi responses
+
+### 🚀 Features
+- Add global `use_body_key` setting
+
 ## 1.0.0.dev3 - 2025-10-26
 ### ♻️ Refactoring
 - Replace pairs with entries, simplify storage API

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hishel
-Version: 1.0.0.dev3
+Version: 1.1.0
 Summary:  Elegant HTTP Caching for Python
 Project-URL: Homepage, https://hishel.com
 Project-URL: Source, https://github.com/karpetrosyan/hishel
@@ -82,9 +82,10 @@ Description-Content-Type: text/markdown
 - 🔄 **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
-- � **Memory Efficient** - Streaming support prevents loading large payloads into memory
+- 🎛️ **Configurable** - Fine-grained control over caching behavior with flexible policies
+- 💨 **Memory Efficient** - Streaming support prevents loading large payloads into memory
 - 🌐 **Universal** - Works with any ASGI application (Starlette, Litestar, BlackSheep, etc.)
+- 🎯 **GraphQL Support** - Cache GraphQL queries with body-sensitive content caching
 
 ## 📦 Installation
 
@@ -175,12 +176,14 @@ from hishel.asgi import ASGICacheMiddleware
 app = ASGICacheMiddleware(app)
 
 # Or configure with options
-from hishel import AsyncSqliteStorage, CacheOptions
+from hishel import AsyncSqliteStorage, CacheOptions, SpecificationPolicy
 
 app = ASGICacheMiddleware(
     app,
     storage=AsyncSqliteStorage(),
-    cache_options=CacheOptions(shared=True)
+    policy=SpecificationPolicy(
+      cache_options=CacheOptions(shared=True)
+    ),
 )
 ```
 
@@ -225,21 +228,49 @@ async def get_data():
 
 ## 🎛️ Advanced Configuration
 
-### Custom Cache Options
+### Caching Policies
+
+Hishel supports two types of caching policies:
+
+**SpecificationPolicy** - RFC 9111 compliant HTTP caching (default):
 
 ```python
-from hishel import CacheOptions
+from hishel import CacheOptions, SpecificationPolicy
 from hishel.httpx import SyncCacheClient
 
 client = SyncCacheClient(
-    cache_options=CacheOptions(
-        shared=False,                              # Use as private cache (browser-like)
-        supported_methods=["GET", "HEAD", "POST"], # Cache GET, HEAD, and POST
-        allow_stale=True                           # Allow serving stale responses
+    policy=SpecificationPolicy(
+        cache_options=CacheOptions(
+            shared=False,                              # Use as private cache (browser-like)
+            supported_methods=["GET", "HEAD", "POST"], # Cache GET, HEAD, and POST
+            allow_stale=True                           # Allow serving stale responses
+        )
     )
 )
 ```
 
+**FilterPolicy** - Custom filtering logic for fine-grained control:
+
+```python
+from hishel import FilterPolicy, BaseFilter, Request
+from hishel.httpx import AsyncCacheClient
+
+class CacheOnlyAPIRequests(BaseFilter[Request]):
+    def needs_body(self) -> bool:
+        return False
+    
+    def apply(self, item: Request, body: bytes | None) -> bool:
+        return "/api/" in str(item.url)
+
+client = AsyncCacheClient(
+    policy=FilterPolicy(
+        request_filters=[CacheOnlyAPIRequests()]
+    )
+)
+```
+
+[Learn more about policies →](https://hishel.com/dev/policies/)
+
 ### Custom Storage Backend
 
 ```python
@@ -255,6 +286,60 @@ storage = SyncSqliteStorage(
 client = SyncCacheClient(storage=storage)
 ```
 
+### GraphQL and Body-Sensitive Caching
+
+Cache GraphQL queries and other POST requests by including the request body in the cache key.
+
+**Using per-request header:**
+
+```python
+from hishel import FilterPolicy
+from hishel.httpx import SyncCacheClient
+
+client = SyncCacheClient(
+    policy=FilterPolicy()
+)
+
+# Cache GraphQL queries - different queries get different cache entries
+graphql_query = """
+    query GetUser($id: ID!) {
+        user(id: $id) {
+            name
+            email
+        }
+    }
+"""
+
+response = client.post(
+    "https://api.example.com/graphql",
+    json={"query": graphql_query, "variables": {"id": "123"}},
+    headers={"X-Hishel-Body-Key": "true"}  # Enable body-based caching
+)
+
+# Different query will be cached separately
+response = client.post(
+    "https://api.example.com/graphql",
+    json={"query": graphql_query, "variables": {"id": "456"}},
+    headers={"X-Hishel-Body-Key": "true"}
+)
+```
+
+**Using global configuration:**
+
+```python
+from hishel.httpx import SyncCacheClient
+from hishel import FilterPolicy
+
+# Enable body-based caching for all requests
+client = SyncCacheClient(policy=FilterPolicy(use_body_key=True))
+
+# All POST requests automatically include body in cache key
+response = client.post(
+    "https://api.example.com/graphql",
+    json={"query": graphql_query, "variables": {"id": "123"}}
+)
+```
+
 ## 🏗️ Architecture
 
 Hishel uses a **sans-I/O state machine** architecture that separates HTTP caching logic from I/O operations:
@@ -266,13 +351,11 @@ Hishel uses a **sans-I/O state machine** architecture that separates HTTP cachin
 
 ## 🔮 Roadmap
 
-While Hishel currently supports HTTPX and Requests, we're actively working on:
+We're actively working on:
 
-- 🎯 Additional HTTP client integrations
-- 🎯 Server-side caching support
-- 🎯 More storage backends
-- 🎯 Advanced caching strategies
 - 🎯 Performance optimizations
+- 🎯 More integrations
+- 🎯 Partial responses support
 
 ## 📚 Documentation
 
@@ -284,6 +367,7 @@ Comprehensive documentation is available at [https://hishel.com/dev](https://his
 - [ASGI Integration](https://hishel.com/dev/asgi)
 - [FastAPI Integration](https://hishel.com/dev/fastapi)
 - [BlackSheep Integration](https://hishel.com/dev/integrations/blacksheep)
+- [GraphQL Integration](https://hishel.com/dev/integrations/graphql)
 - [Storage Backends](https://hishel.com/dev/storages)
 - [Request/Response Metadata](https://hishel.com/dev/metadata)
 - [RFC 9111 Specification](https://hishel.com/dev/specification)
@@ -326,6 +410,35 @@ 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.1.0 - 2025-10-31
+### ⚙️ Miscellaneous Tasks
+- Add in memory example
+
+### 🐛 Bug Fixes
+- Pass any response with non-expected status code on revalidation to client
+
+### 🚀 Features
+- Allow setting storage base with via `database_path` for sqlite storage
+
+## 1.0.0 - 2025-10-28
+### ⚙️ Miscellaneous Tasks
+- Add examples, improve docs
+
+## 1.0.0b1 - 2025-10-28
+### ♻️ Refactoring
+- Add policies
+
+### ⚙️ Miscellaneous Tasks
+- Improve sans-io diagram colors
+- Add graphql docs
+
+### 🐛 Bug Fixes
+- Body-sensitive responses caching
+- Filter out `Transfer-Encoding` header for asgi responses
+
+### 🚀 Features
+- Add global `use_body_key` setting
+
 ## 1.0.0.dev3 - 2025-10-26
 ### ♻️ Refactoring
 - Replace pairs with entries, simplify storage API

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

@@ -41,9 +41,10 @@
 - 🔄 **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
-- � **Memory Efficient** - Streaming support prevents loading large payloads into memory
+- 🎛️ **Configurable** - Fine-grained control over caching behavior with flexible policies
+- 💨 **Memory Efficient** - Streaming support prevents loading large payloads into memory
 - 🌐 **Universal** - Works with any ASGI application (Starlette, Litestar, BlackSheep, etc.)
+- 🎯 **GraphQL Support** - Cache GraphQL queries with body-sensitive content caching
 
 ## 📦 Installation
 
@@ -134,12 +135,14 @@ from hishel.asgi import ASGICacheMiddleware
 app = ASGICacheMiddleware(app)
 
 # Or configure with options
-from hishel import AsyncSqliteStorage, CacheOptions
+from hishel import AsyncSqliteStorage, CacheOptions, SpecificationPolicy
 
 app = ASGICacheMiddleware(
     app,
     storage=AsyncSqliteStorage(),
-    cache_options=CacheOptions(shared=True)
+    policy=SpecificationPolicy(
+      cache_options=CacheOptions(shared=True)
+    ),
 )
 ```
 
@@ -184,21 +187,49 @@ async def get_data():
 
 ## 🎛️ Advanced Configuration
 
-### Custom Cache Options
+### Caching Policies
+
+Hishel supports two types of caching policies:
+
+**SpecificationPolicy** - RFC 9111 compliant HTTP caching (default):
 
 ```python
-from hishel import CacheOptions
+from hishel import CacheOptions, SpecificationPolicy
 from hishel.httpx import SyncCacheClient
 
 client = SyncCacheClient(
-    cache_options=CacheOptions(
-        shared=False,                              # Use as private cache (browser-like)
-        supported_methods=["GET", "HEAD", "POST"], # Cache GET, HEAD, and POST
-        allow_stale=True                           # Allow serving stale responses
+    policy=SpecificationPolicy(
+        cache_options=CacheOptions(
+            shared=False,                              # Use as private cache (browser-like)
+            supported_methods=["GET", "HEAD", "POST"], # Cache GET, HEAD, and POST
+            allow_stale=True                           # Allow serving stale responses
+        )
+    )
+)
+```
+
+**FilterPolicy** - Custom filtering logic for fine-grained control:
+
+```python
+from hishel import FilterPolicy, BaseFilter, Request
+from hishel.httpx import AsyncCacheClient
+
+class CacheOnlyAPIRequests(BaseFilter[Request]):
+    def needs_body(self) -> bool:
+        return False
+    
+    def apply(self, item: Request, body: bytes | None) -> bool:
+        return "/api/" in str(item.url)
+
+client = AsyncCacheClient(
+    policy=FilterPolicy(
+        request_filters=[CacheOnlyAPIRequests()]
     )
 )
 ```
 
+[Learn more about policies →](https://hishel.com/dev/policies/)
+
 ### Custom Storage Backend
 
 ```python
@@ -214,6 +245,60 @@ storage = SyncSqliteStorage(
 client = SyncCacheClient(storage=storage)
 ```
 
+### GraphQL and Body-Sensitive Caching
+
+Cache GraphQL queries and other POST requests by including the request body in the cache key.
+
+**Using per-request header:**
+
+```python
+from hishel import FilterPolicy
+from hishel.httpx import SyncCacheClient
+
+client = SyncCacheClient(
+    policy=FilterPolicy()
+)
+
+# Cache GraphQL queries - different queries get different cache entries
+graphql_query = """
+    query GetUser($id: ID!) {
+        user(id: $id) {
+            name
+            email
+        }
+    }
+"""
+
+response = client.post(
+    "https://api.example.com/graphql",
+    json={"query": graphql_query, "variables": {"id": "123"}},
+    headers={"X-Hishel-Body-Key": "true"}  # Enable body-based caching
+)
+
+# Different query will be cached separately
+response = client.post(
+    "https://api.example.com/graphql",
+    json={"query": graphql_query, "variables": {"id": "456"}},
+    headers={"X-Hishel-Body-Key": "true"}
+)
+```
+
+**Using global configuration:**
+
+```python
+from hishel.httpx import SyncCacheClient
+from hishel import FilterPolicy
+
+# Enable body-based caching for all requests
+client = SyncCacheClient(policy=FilterPolicy(use_body_key=True))
+
+# All POST requests automatically include body in cache key
+response = client.post(
+    "https://api.example.com/graphql",
+    json={"query": graphql_query, "variables": {"id": "123"}}
+)
+```
+
 ## 🏗️ Architecture
 
 Hishel uses a **sans-I/O state machine** architecture that separates HTTP caching logic from I/O operations:
@@ -225,13 +310,11 @@ Hishel uses a **sans-I/O state machine** architecture that separates HTTP cachin
 
 ## 🔮 Roadmap
 
-While Hishel currently supports HTTPX and Requests, we're actively working on:
+We're actively working on:
 
-- 🎯 Additional HTTP client integrations
-- 🎯 Server-side caching support
-- 🎯 More storage backends
-- 🎯 Advanced caching strategies
 - 🎯 Performance optimizations
+- 🎯 More integrations
+- 🎯 Partial responses support
 
 ## 📚 Documentation
 
@@ -243,6 +326,7 @@ Comprehensive documentation is available at [https://hishel.com/dev](https://his
 - [ASGI Integration](https://hishel.com/dev/asgi)
 - [FastAPI Integration](https://hishel.com/dev/fastapi)
 - [BlackSheep Integration](https://hishel.com/dev/integrations/blacksheep)
+- [GraphQL Integration](https://hishel.com/dev/integrations/graphql)
 - [Storage Backends](https://hishel.com/dev/storages)
 - [Request/Response Metadata](https://hishel.com/dev/metadata)
 - [RFC 9111 Specification](https://hishel.com/dev/specification)

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

@@ -15,17 +15,20 @@ from hishel._core._spec import (
     NeedToBeUpdated as NeedToBeUpdated,
     State as State,
     StoreAndUse as StoreAndUse,
-    create_idle_state as create_idle_state,
 )
 from hishel._core.models import (
     Entry as Entry,
     EntryMeta as EntryMeta,
     Request as Request,
-    Response,
+    Response as Response,
+    ResponseMetadata as ResponseMetadata,
+    RequestMetadata as RequestMetadata,
 )
 from hishel._async_cache import AsyncCacheProxy as AsyncCacheProxy
 from hishel._sync_cache import SyncCacheProxy as SyncCacheProxy
 
+from hishel._policies import SpecificationPolicy, FilterPolicy, CachePolicy
+
 __all__ = (
     # New API
     ## States
@@ -41,12 +44,13 @@ __all__ = (
     "StoreAndUse",
     "CouldNotBeStored",
     "InvalidateEntries",
-    "create_idle_state",
     ## Models
     "Request",
     "Response",
     "Entry",
     "EntryMeta",
+    "RequestMetadata",
+    "ResponseMetadata",
     ## Headers
     "Headers",
     ## Storages
@@ -57,4 +61,8 @@ __all__ = (
     # Proxy
     "AsyncCacheProxy",
     "SyncCacheProxy",
+    # Policies
+    "CachePolicy",
+    "SpecificationPolicy",
+    "FilterPolicy",
 )

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

@@ -13,7 +13,6 @@ from hishel import (
     AsyncBaseStorage,
     AsyncSqliteStorage,
     CacheMiss,
-    CacheOptions,
     CouldNotBeStored,
     FromCache,
     IdleClient,
@@ -22,10 +21,10 @@ from hishel import (
     Request,
     Response,
     StoreAndUse,
-    create_idle_state,
 )
 from hishel._core._spec import InvalidateEntries, vary_headers_match
 from hishel._core.models import Entry, ResponseMetadata
+from hishel._policies import CachePolicy, FilterPolicy, SpecificationPolicy
 from hishel._utils import make_async_iterator
 
 logger = logging.getLogger("hishel.integrations.clients")
@@ -37,87 +36,121 @@ class AsyncCacheProxy:
 
     This class is independent of any specific HTTP library and works only with internal models.
     It delegates request execution to a user-provided callable, making it compatible with any
-    HTTP client. Caching behavior can be configured to either fully respect HTTP
-    caching rules or bypass them entirely.
+    HTTP client. Caching behavior is determined by the policy object.
+
+    Args:
+        request_sender: Callable that sends HTTP requests and returns responses.
+        storage: Storage backend for cache entries. Defaults to AsyncSqliteStorage.
+        policy: Caching policy to use. Can be SpecificationPolicy (respects RFC 9111) or
+            FilterPolicy (user-defined filtering). Defaults to SpecificationPolicy().
     """
 
     def __init__(
         self,
         request_sender: Callable[[Request], Awaitable[Response]],
         storage: AsyncBaseStorage | None = None,
-        cache_options: CacheOptions | None = None,
-        ignore_specification: bool = False,
+        policy: CachePolicy | None = None,
     ) -> None:
         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
+        self.policy = policy if policy is not None else SpecificationPolicy()
 
     async def handle_request(self, request: Request) -> Response:
-        if self.ignore_specification or request.metadata.get("hishel_spec_ignore"):
-            return await self._handle_request_ignoring_spec(request)
+        if isinstance(self.policy, FilterPolicy):
+            return await self._handle_request_with_filters(request)
         return await self._handle_request_respecting_spec(request)
 
     async def _get_key_for_request(self, request: Request) -> str:
-        if request.metadata.get("hishel_body_key"):
+        if self.policy.use_body_key or request.metadata.get("hishel_body_key"):
             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 hash_
         return hashlib.sha256(str(request.url).encode("utf-8")).hexdigest()
 
-    async def _maybe_refresh_pair_ttl(self, pair: Entry) -> None:
-        if pair.request.metadata.get("hishel_refresh_ttl_on_access"):
+    async def _maybe_refresh_entry_ttl(self, entry: Entry) -> None:
+        if entry.request.metadata.get("hishel_refresh_ttl_on_access"):
             await self.storage.update_entry(
-                pair.id,
-                lambda complete_pair: replace(
-                    complete_pair,
-                    meta=replace(complete_pair.meta, created_at=time.time()),
+                entry.id,
+                lambda current_entry: replace(
+                    current_entry,
+                    meta=replace(current_entry.meta, created_at=time.time()),
                 ),
             )
 
-    async def _handle_request_ignoring_spec(self, request: Request) -> Response:
+    async def _handle_request_with_filters(self, request: Request) -> Response:
+        assert isinstance(self.policy, FilterPolicy)
+
+        for request_filter in self.policy.request_filters:
+            if request_filter.needs_body():
+                body = await request.aread()
+                if not request_filter.apply(request, body):
+                    logger.debug("Request filtered out by request filter")
+                    return await self.send_request(request)
+            else:
+                if not request_filter.apply(request, None):
+                    logger.debug("Request filtered out by request filter")
+                    return await self.send_request(request)
+
         logger.debug("Trying to get cached response ignoring specification")
-        entries = await self.storage.get_entries(await self._get_key_for_request(request))
+        cache_key = await self._get_key_for_request(request)
+        entries = await self.storage.get_entries(cache_key)
 
         logger.debug(f"Found {len(entries)} cached entries for the request")
 
-        for pair in entries:
+        for entry in entries:
             if (
-                str(pair.request.url) == str(request.url)
-                and pair.request.method == request.method
+                str(entry.request.url) == str(request.url)
+                and entry.request.method == request.method
                 and vary_headers_match(
                     request,
-                    pair,
+                    entry,
                 )
             ):
                 logger.debug(
                     "Found matching cached response for the request",
                 )
                 response_meta = ResponseMetadata(
-                    hishel_spec_ignored=True,
                     hishel_from_cache=True,
-                    hishel_created_at=pair.meta.created_at,
+                    hishel_created_at=entry.meta.created_at,
                     hishel_revalidated=False,
                     hishel_stored=False,
                 )
-                pair.response.metadata.update(response_meta)  # type: ignore
-                await self._maybe_refresh_pair_ttl(pair)
-                return pair.response
+                entry.response.metadata.update(response_meta)  # type: ignore
+                await self._maybe_refresh_entry_ttl(entry)
+                return entry.response
 
         response = await self.send_request(request)
+        for response_filter in self.policy.response_filters:
+            if response_filter.needs_body():
+                body = await response.aread()
+                if not response_filter.apply(response, body):
+                    logger.debug("Response filtered out by response filter")
+                    return response
+            else:
+                if not response_filter.apply(response, None):
+                    logger.debug("Response filtered out by response filter")
+                    return response
+        response_meta = ResponseMetadata(
+            hishel_from_cache=False,
+            hishel_created_at=time.time(),
+            hishel_revalidated=False,
+            hishel_stored=True,
+        )
+        response.metadata.update(response_meta)  # type: ignore
 
         logger.debug("Storing response in cache ignoring specification")
         entry = await self.storage.create_entry(
             request,
             response,
-            await self._get_key_for_request(request),
+            cache_key,
         )
         return entry.response
 
     async def _handle_request_respecting_spec(self, request: Request) -> Response:
-        state: AnyState = create_idle_state("client", self.cache_options)
+        assert isinstance(self.policy, SpecificationPolicy)
+        state: AnyState = IdleClient(options=self.policy.cache_options)
 
         while state:
             logger.debug(f"Handling state: {state.__class__.__name__}")
@@ -132,8 +165,8 @@ class AsyncCacheProxy:
             elif isinstance(state, NeedRevalidation):
                 state = await self._handle_revalidation(state)
             elif isinstance(state, FromCache):
-                await self._maybe_refresh_pair_ttl(state.pair)
-                return state.pair.response
+                await self._maybe_refresh_entry_ttl(state.entry)
+                return state.entry.response
             elif isinstance(state, NeedToBeUpdated):
                 state = await self._handle_update(state)
             elif isinstance(state, InvalidateEntries):
@@ -152,12 +185,12 @@ class AsyncCacheProxy:
         return state.next(response)
 
     async def _handle_store_and_use(self, state: StoreAndUse, request: Request) -> Response:
-        complete_pair = await self.storage.create_entry(
+        entry = await self.storage.create_entry(
             request,
             state.response,
             await self._get_key_for_request(request),
         )
-        return complete_pair.response
+        return entry.response
 
     async def _handle_revalidation(self, state: NeedRevalidation) -> AnyState:
         revalidation_response = await self.send_request(state.request)
@@ -167,8 +200,8 @@ class AsyncCacheProxy:
         for entry in state.updating_entries:
             await self.storage.update_entry(
                 entry.id,
-                lambda complete_pair: replace(
-                    complete_pair,
+                lambda entry: replace(
+                    entry,
                     response=replace(entry.response, headers=entry.response.headers),
                 ),
             )