hishel 1.0.0.dev3__py3-none-any.whl → 1.1.1__py3-none-any.whl

hishel/_policies.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import abc
+import typing as t
+from dataclasses import dataclass, field
+from typing import Generic
+
+from hishel import Request, Response
+from hishel._core._spec import (
+    CacheOptions,
+)
+
+logger = __import__("logging").getLogger(__name__)
+
+T = t.TypeVar("T", Request, Response)
+
+
+class CachePolicy(abc.ABC):
+    use_body_key: bool = False
+    """Whether to include request body in cache key calculation."""
+
+
+class BaseFilter(abc.ABC, Generic[T]):
+    @abc.abstractmethod
+    def needs_body(self) -> bool:
+        pass
+
+    @abc.abstractmethod
+    def apply(self, item: T, body: bytes | None) -> bool:
+        pass
+
+
+@dataclass
+class SpecificationPolicy(CachePolicy):
+    """
+    Caching policy that respects HTTP caching specification.
+    """
+
+    cache_options: CacheOptions = field(default_factory=CacheOptions)
+
+
+@dataclass
+class FilterPolicy(CachePolicy):
+    """
+    Caching policy that applies user-defined filtering logic.
+    """
+
+    request_filters: list[BaseFilter[Request]] = field(default_factory=list)
+    response_filters: list[BaseFilter[Response]] = field(default_factory=list)

hishel/_sync_cache.py

@@ -13,7 +13,6 @@ from hishel import (
     SyncBaseStorage,
     SyncSqliteStorage,
     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_sync_iterator
 
 logger = logging.getLogger("hishel.integrations.clients")
@@ -37,87 +36,121 @@ class SyncCacheProxy:
 
     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 SyncSqliteStorage.
+        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], Response],
         storage: SyncBaseStorage | 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 SyncSqliteStorage()
-        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()
 
     def handle_request(self, request: Request) -> Response:
-        if self.ignore_specification or request.metadata.get("hishel_spec_ignore"):
-            return self._handle_request_ignoring_spec(request)
+        if isinstance(self.policy, FilterPolicy):
+            return self._handle_request_with_filters(request)
         return self._handle_request_respecting_spec(request)
 
     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, (Iterator, Iterable))
             collected = b"".join([chunk for chunk in request.stream])
             hash_ = hashlib.sha256(collected).hexdigest()
             request.stream = make_sync_iterator([collected])
-            return f"{str(request.url)}-{hash_}"
+            return hash_
         return hashlib.sha256(str(request.url).encode("utf-8")).hexdigest()
 
-    def _maybe_refresh_pair_ttl(self, pair: Entry) -> None:
-        if pair.request.metadata.get("hishel_refresh_ttl_on_access"):
+    def _maybe_refresh_entry_ttl(self, entry: Entry) -> None:
+        if entry.request.metadata.get("hishel_refresh_ttl_on_access"):
             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()),
                 ),
             )
 
-    def _handle_request_ignoring_spec(self, request: Request) -> Response:
+    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 = request.read()
+                if not request_filter.apply(request, body):
+                    logger.debug("Request filtered out by request filter")
+                    return self.send_request(request)
+            else:
+                if not request_filter.apply(request, None):
+                    logger.debug("Request filtered out by request filter")
+                    return self.send_request(request)
+
         logger.debug("Trying to get cached response ignoring specification")
-        entries = self.storage.get_entries(self._get_key_for_request(request))
+        cache_key = self._get_key_for_request(request)
+        entries = 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
-                self._maybe_refresh_pair_ttl(pair)
-                return pair.response
+                entry.response.metadata.update(response_meta)  # type: ignore
+                self._maybe_refresh_entry_ttl(entry)
+                return entry.response
 
         response = self.send_request(request)
+        for response_filter in self.policy.response_filters:
+            if response_filter.needs_body():
+                body = response.read()
+                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 = self.storage.create_entry(
             request,
             response,
-            self._get_key_for_request(request),
+            cache_key,
         )
         return entry.response
 
     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 SyncCacheProxy:
             elif isinstance(state, NeedRevalidation):
                 state = self._handle_revalidation(state)
             elif isinstance(state, FromCache):
-                self._maybe_refresh_pair_ttl(state.pair)
-                return state.pair.response
+                self._maybe_refresh_entry_ttl(state.entry)
+                return state.entry.response
             elif isinstance(state, NeedToBeUpdated):
                 state = self._handle_update(state)
             elif isinstance(state, InvalidateEntries):
@@ -152,12 +185,12 @@ class SyncCacheProxy:
         return state.next(response)
 
     def _handle_store_and_use(self, state: StoreAndUse, request: Request) -> Response:
-        complete_pair = self.storage.create_entry(
+        entry = self.storage.create_entry(
             request,
             state.response,
             self._get_key_for_request(request),
         )
-        return complete_pair.response
+        return entry.response
 
     def _handle_revalidation(self, state: NeedRevalidation) -> AnyState:
         revalidation_response = self.send_request(state.request)
@@ -167,8 +200,8 @@ class SyncCacheProxy:
         for entry in state.updating_entries:
             self.storage.update_entry(
                 entry.id,
-                lambda complete_pair: replace(
-                    complete_pair,
+                lambda entry: replace(
+                    entry,
                     response=replace(entry.response, headers=entry.response.headers),
                 ),
             )

hishel/_sync_httpx.py

@@ -14,11 +14,9 @@ from typing import (
 from httpx import RequestNotRead
 
 from hishel import SyncCacheProxy, Headers, Request, Response
-from hishel._core._spec import (
-    CacheOptions,
-)
 from hishel._core._storages._sync_base import SyncBaseStorage
 from hishel._core.models import RequestMetadata, extract_metadata_from_headers
+from hishel._policies import CachePolicy
 from hishel._utils import (
     filter_mapping,
     make_sync_iterator,
@@ -62,14 +60,14 @@ def _internal_to_httpx(
             method=value.method,
             url=value.url,
             headers=value.headers,
-            stream=_IteratorStream(value.iter_stream()),
+            stream=_IteratorStream(value._iter_stream()),
             extensions=value.metadata,
         )
     elif isinstance(value, Response):
         return httpx.Response(
             status_code=value.status_code,
             headers=value.headers,
-            stream=_IteratorStream(value.iter_stream()),
+            stream=_IteratorStream(value._iter_stream()),
             extensions=value.metadata,
         )
 
@@ -149,15 +147,13 @@ class SyncCacheTransport(httpx.BaseTransport):
         self,
         next_transport: httpx.BaseTransport,
         storage: SyncBaseStorage | None = None,
-        cache_options: CacheOptions | None = None,
-        ignore_specification: bool = False,
+        policy: CachePolicy | None = None,
     ) -> None:
         self.next_transport = next_transport
         self._cache_proxy: SyncCacheProxy = SyncCacheProxy(
             request_sender=self.request_sender,
             storage=storage,
-            cache_options=cache_options,
-            ignore_specification=ignore_specification,
+            policy=policy,
         )
         self.storage = self._cache_proxy.storage
 
@@ -184,8 +180,7 @@ class SyncCacheTransport(httpx.BaseTransport):
 class SyncCacheClient(httpx.Client):
     def __init__(self, *args: t.Any, **kwargs: t.Any) -> None:
         self.storage: SyncBaseStorage | None = kwargs.pop("storage", None)
-        self.cache_options: CacheOptions | None = kwargs.pop("cache_options", None)
-        self.ignore_specification: bool = kwargs.pop("ignore_specification", False)
+        self.policy: CachePolicy | None = kwargs.pop("policy", None)
         super().__init__(*args, **kwargs)
 
     def _init_transport(
@@ -212,8 +207,7 @@ class SyncCacheClient(httpx.Client):
                 limits=limits,
             ),
             storage=self.storage,
-            cache_options=self.cache_options,
-            ignore_specification=False,
+            policy=self.policy,
         )
 
     def _init_proxy_transport(
@@ -238,6 +232,5 @@ class SyncCacheClient(httpx.Client):
                 proxy=proxy,
             ),
             storage=self.storage,
-            cache_options=self.cache_options,
-            ignore_specification=self.ignore_specification,
+            policy=self.policy,
         )

hishel/_utils.py

@@ -107,8 +107,8 @@ def snake_to_header(text: str) -> str:
     return "X-" + "-".join(word.capitalize() for word in text.split("_"))
 
 
-def ensure_cache_dict(base_path: str | None = None) -> Path:
-    _base_path = Path(base_path) if base_path is not None else Path(".cache/hishel")
+def ensure_cache_dict(base_path: Path | None = None) -> Path:
+    _base_path = base_path if base_path is not None else Path(".cache/hishel")
     _gitignore_file = _base_path / ".gitignore"
 
     _base_path.mkdir(parents=True, exist_ok=True)

hishel/asgi.py

@@ -5,8 +5,10 @@ import typing as t
 from email.utils import formatdate
 from typing import AsyncIterator
 
-from hishel import AsyncBaseStorage, CacheOptions, Headers, Request, Response
+from hishel import AsyncBaseStorage, Headers, Request, Response
 from hishel._async_cache import AsyncCacheProxy
+from hishel._policies import CachePolicy
+from hishel._utils import filter_mapping
 
 # Configure logger for this module
 logger = logging.getLogger(__name__)
@@ -54,19 +56,20 @@ class ASGICacheMiddleware:
     Args:
         app: The ASGI application to wrap.
         storage: The storage backend to use for caching. Defaults to AsyncSqliteStorage.
-        cache_options: Configuration options for caching behavior.
-        ignore_specification: If True, bypasses HTTP caching rules and caches all responses.
+        policy: Caching policy to use. Can be SpecificationPolicy (respects RFC 9111) or
+            FilterPolicy (user-defined filtering). Defaults to SpecificationPolicy().
 
     Example:
         ```python
         from hishel.asgi import ASGICacheMiddleware
-        from hishel import AsyncSqliteStorage, CacheOptions
+        from hishel import AsyncSqliteStorage
+        from hishel._policies import SpecificationPolicy, CacheOptions
 
         # Wrap your ASGI app
         app = ASGICacheMiddleware(
             app=my_asgi_app,
             storage=AsyncSqliteStorage(),
-            cache_options=CacheOptions(),
+            policy=SpecificationPolicy(cache_options=CacheOptions()),
         )
         ```
     """
@@ -75,18 +78,16 @@ class ASGICacheMiddleware:
         self,
         app: _ASGIApp,
         storage: AsyncBaseStorage | None = None,
-        cache_options: CacheOptions | None = None,
-        ignore_specification: bool = False,
+        policy: CachePolicy | None = None,
     ) -> None:
         self.app = app
         self.storage = storage
-        self._cache_options = cache_options
-        self._ignore_specification = ignore_specification
+        self._policy = policy
 
         logger.info(
-            "Initialized ASGICacheMiddleware with storage=%s, ignore_specification=%s",
+            "Initialized ASGICacheMiddleware with storage=%s, policy=%s",
             type(storage).__name__ if storage else "None",
-            ignore_specification,
+            type(policy).__name__ if policy else "None",
         )
 
     async def __call__(self, scope: _Scope, receive: _Receive, send: _Send) -> None:
@@ -122,7 +123,7 @@ class ASGICacheMiddleware:
                 logger.debug("Sending request to wrapped application: url=%s", request.url)
 
                 # Create a buffered receive callable that replays the request body from the stream
-                body_iterator = request.aiter_stream()
+                body_iterator = request._aiter_stream()
                 body_exhausted = False
                 bytes_received = 0
 
@@ -209,7 +210,7 @@ class ASGICacheMiddleware:
 
                 return Response(
                     status_code=status_code,
-                    headers=Headers(headers_dict),
+                    headers=Headers(filter_mapping(headers_dict, ["Transfer-Encoding"])),
                     stream=response_stream(),
                     metadata={},
                 )
@@ -219,8 +220,7 @@ class ASGICacheMiddleware:
             cache_proxy = AsyncCacheProxy(
                 request_sender=send_request_to_app,
                 storage=self.storage,
-                cache_options=self._cache_options,
-                ignore_specification=self._ignore_specification,
+                policy=self._policy,
             )
 
             # Convert ASGI request to internal Request (using async iterator, not reading into memory)
@@ -352,7 +352,7 @@ class ASGICacheMiddleware:
             # Send response body in chunks
             bytes_sent = 0
             chunk_count = 0
-            async for chunk in response.aiter_stream():
+            async for chunk in response._aiter_stream():
                 await send(
                     {
                         "type": "http.response.body",

hishel/requests.py

@@ -6,9 +6,9 @@ from typing import Any, Iterator, Mapping, Optional, overload
 from typing_extensions import assert_never
 
 from hishel import Headers, Request, Response as Response
-from hishel._core._spec import CacheOptions
 from hishel._core._storages._sync_base import SyncBaseStorage
 from hishel._core.models import extract_metadata_from_headers
+from hishel._policies import CachePolicy
 from hishel._sync_cache import SyncCacheProxy
 from hishel._utils import snake_to_header
 
@@ -163,15 +163,13 @@ class CacheAdapter(HTTPAdapter):
         max_retries: int = 0,
         pool_block: bool = False,
         storage: SyncBaseStorage | None = None,
-        cache_options: CacheOptions | None = None,
-        ignore_specification: bool = False,
+        policy: CachePolicy | None = None,
     ):
         super().__init__(pool_connections, pool_maxsize, max_retries, pool_block)
         self._cache_proxy = SyncCacheProxy(
             request_sender=self._send_request,
             storage=storage,
-            cache_options=cache_options,
-            ignore_specification=ignore_specification,
+            policy=policy,
         )
         self.storage = self._cache_proxy.storage