hishel 0.0.24__tar.gz → 0.0.26__tar.gz

{hishel-0.0.24 → hishel-0.0.26}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.0.26 (12th April, 2024)
+
+- Expose `AsyncBaseStorage` and `BaseStorage`. (#220)
+- Prevent cache hits from resetting the ttl. (#215)
+
+## 0.0.25 (26th March, 2024)
+
+- Add `force_cache` property to the controller, allowing RFC9111 rules to be completely disabled. (#204)
+- Add `.gitignore` to cache directory created by `FIleStorage`. (#197)
+- Remove `stale_*` headers from the `CacheControl` class. (#199)
+
 ## 0.0.24 (14th February, 2024)
 
 - Fix `botocore is not installed` exception when using any kind of storage. (#186)

{hishel-0.0.24 → hishel-0.0.26}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: hishel
-Version: 0.0.24
+Version: 0.0.26
 Summary: Persistent cache implementation for httpx and httpcore
 Project-URL: Homepage, https://hishel.com
 Project-URL: Source, https://github.com/karpetrosyan/hishel
@@ -175,6 +175,17 @@ Help us grow and continue developing good software for you ❤️
 
 # Changelog
 
+## 0.0.26 (12th April, 2024)
+
+- Expose `AsyncBaseStorage` and `BaseStorage`. (#220)
+- Prevent cache hits from resetting the ttl. (#215)
+
+## 0.0.25 (26th March, 2024)
+
+- Add `force_cache` property to the controller, allowing RFC9111 rules to be completely disabled. (#204)
+- Add `.gitignore` to cache directory created by `FIleStorage`. (#197)
+- Remove `stale_*` headers from the `CacheControl` class. (#199)
+
 ## 0.0.24 (14th February, 2024)
 
 - Fix `botocore is not installed` exception when using any kind of storage. (#186)

{hishel-0.0.24 → hishel-0.0.26}/hishel/__init__.py

@@ -14,4 +14,4 @@ def install_cache() -> None:  # pragma: no cover
     httpx.Client = CacheClient  # type: ignore
 
 
-__version__ = "0.0.24"
+__version__ = "0.0.26"

{hishel-0.0.24 → hishel-0.0.26}/hishel/_async/_mock.py

@@ -30,8 +30,7 @@ class MockAsyncConnectionPool(AsyncRequestInterface):
         exc_type: tp.Optional[tp.Type[BaseException]] = None,
         exc_value: tp.Optional[BaseException] = None,
         traceback: tp.Optional[TracebackType] = None,
-    ) -> None:
-        ...
+    ) -> None: ...
 
 
 class MockAsyncTransport(httpx.AsyncBaseTransport):

{hishel-0.0.24 → hishel-0.0.26}/hishel/_async/_pool.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import datetime
 import types
 import typing as tp
@@ -86,6 +88,9 @@ class AsyncCacheConnectionPool(AsyncRequestInterface):
 
             stored_response, stored_request, metadata = stored_data
 
+            # Immediately read the stored response to avoid issues when trying to access the response body.
+            stored_response.read()
+
             res = self._controller.construct_response_from_cache(
                 request=request,
                 response=stored_response,
@@ -94,55 +99,66 @@ class AsyncCacheConnectionPool(AsyncRequestInterface):
 
             if isinstance(res, Response):
                 # Simply use the response if the controller determines it is ready for use.
-                metadata["number_of_uses"] += 1
-                stored_response.read()
-                await self._storage.store(
-                    key=key,
-                    request=request,
-                    response=stored_response,
-                    metadata=metadata,
+                return await self._create_hishel_response(
+                    key=key, response=stored_response, request=request, metadata=metadata, cached=True
                 )
-                res.extensions["from_cache"] = True  # type: ignore[index]
-                res.extensions["cache_metadata"] = metadata  # type: ignore[index]
-                return res
 
             if request_cache_control.only_if_cached:
                 return generate_504()
 
             if isinstance(res, Request):
-                # Re-validating the response.
+                # Controller has determined that the response needs to be re-validated.
 
                 try:
-                    response = await self._pool.handle_async_request(res)
+                    revalidation_response = await self._pool.handle_async_request(res)
                 except ConnectError:
+                    # If there is a connection error, we can use the stale response if allowed.
                     if self._controller._allow_stale and allowed_stale(response=stored_response):
-                        stored_response.extensions["from_cache"] = True  # type: ignore[index]
-                        stored_response.extensions["cache_metadata"] = metadata  # type: ignore[index]
-                        return stored_response
+                        return await self._create_hishel_response(
+                            key=key, response=stored_response, request=request, metadata=metadata, cached=True
+                        )
                     raise  # pragma: no cover
                 # Merge headers with the stale response.
-                full_response = self._controller.handle_validation_response(
-                    old_response=stored_response, new_response=response
+                final_response = self._controller.handle_validation_response(
+                    old_response=stored_response, new_response=revalidation_response
                 )
 
-                await full_response.aread()
-                metadata["number_of_uses"] += response.status == 304
-                await self._storage.store(key, response=full_response, request=request, metadata=metadata)
-                full_response.extensions["from_cache"] = response.status == 304  # type: ignore[index]
-                if full_response.extensions["from_cache"]:
-                    full_response.extensions["cache_metadata"] = metadata  # type: ignore[index]
-                return full_response
+                await final_response.aread()
+                return await self._create_hishel_response(
+                    key=key,
+                    response=final_response,
+                    request=request,
+                    metadata=metadata,
+                    cached=revalidation_response.status == 304,
+                )
 
-        response = await self._pool.handle_async_request(request)
+        regular_response = await self._pool.handle_async_request(request)
+        await regular_response.aread()
 
-        if self._controller.is_cachable(request=request, response=response):
-            await response.aread()
+        if self._controller.is_cachable(request=request, response=regular_response):
             metadata = Metadata(
                 cache_key=key, created_at=datetime.datetime.now(datetime.timezone.utc), number_of_uses=0
             )
-            await self._storage.store(key, response=response, request=request, metadata=metadata)
+            await self._storage.store(key, response=regular_response, request=request, metadata=metadata)
 
-        response.extensions["from_cache"] = False  # type: ignore[index]
+        return await self._create_hishel_response(key=key, response=regular_response, request=request, cached=False)
+
+    async def _create_hishel_response(
+        self,
+        key: str,
+        response: Response,
+        request: Request,
+        cached: bool,
+        metadata: Metadata | None = None,
+    ) -> Response:
+        if cached:
+            assert metadata
+            metadata["number_of_uses"] += 1
+            await self._storage.update_metadata(key=key, request=request, response=response, metadata=metadata)
+            response.extensions["from_cache"] = True  # type: ignore[index]
+            response.extensions["cache_metadata"] = metadata  # type: ignore[index]
+        else:
+            response.extensions["from_cache"] = False  # type: ignore[index]
         return response
 
     async def aclose(self) -> None:

{hishel-0.0.24 → hishel-0.0.26}/hishel/_async/_storages.py

@@ -1,4 +1,8 @@
+from __future__ import annotations
+
+import datetime
 import logging
+import os
 import time
 import typing as tp
 import warnings
@@ -29,7 +33,14 @@ from .._utils import float_seconds_to_int_milliseconds
 
 logger = logging.getLogger("hishel.storages")
 
-__all__ = ("AsyncFileStorage", "AsyncRedisStorage", "AsyncSQLiteStorage", "AsyncInMemoryStorage", "AsyncS3Storage")
+__all__ = (
+    "AsyncBaseStorage",
+    "AsyncFileStorage",
+    "AsyncRedisStorage",
+    "AsyncSQLiteStorage",
+    "AsyncInMemoryStorage",
+    "AsyncS3Storage",
+)
 
 StoredResponse: TypeAlias = tp.Tuple[Response, Request, Metadata]
 
@@ -48,7 +59,10 @@ class AsyncBaseStorage:
         self._serializer = serializer or JSONSerializer()
         self._ttl = ttl
 
-    async def store(self, key: str, response: Response, request: Request, metadata: Metadata) -> None:
+    async def store(self, key: str, response: Response, request: Request, metadata: Metadata | None = None) -> None:
+        raise NotImplementedError()
+
+    async def update_metadata(self, key: str, response: Response, request: Request, metadata: Metadata) -> None:
         raise NotImplementedError()
 
     async def retrieve(self, key: str) -> tp.Optional[StoredResponse]:
@@ -83,16 +97,21 @@ class AsyncFileStorage(AsyncBaseStorage):
         super().__init__(serializer, ttl)
 
         self._base_path = Path(base_path) if base_path is not None else Path(".cache/hishel")
+        self._gitignore_file = self._base_path / ".gitignore"
 
         if not self._base_path.is_dir():
             self._base_path.mkdir(parents=True)
 
+        if not self._gitignore_file.is_file():
+            with open(self._gitignore_file, "w", encoding="utf-8") as f:
+                f.write("# Automatically created by Hishel\n*")
+
         self._file_manager = AsyncFileManager(is_binary=self._serializer.is_binary)
         self._lock = AsyncLock()
         self._check_ttl_every = check_ttl_every
         self._last_cleaned = time.monotonic()
 
-    async def store(self, key: str, response: Response, request: Request, metadata: Metadata) -> None:
+    async def store(self, key: str, response: Response, request: Request, metadata: Metadata | None = None) -> None:
         """
         Stores the response in the cache.
 
@@ -103,8 +122,12 @@ class AsyncFileStorage(AsyncBaseStorage):
         :param request: An HTTP request
         :type request: httpcore.Request
         :param metadata: Additional information about the stored response
-        :type metadata: Metadata
+        :type metadata: Optional[Metadata]
         """
+
+        metadata = metadata or Metadata(
+            cache_key=key, created_at=datetime.datetime.now(datetime.timezone.utc), number_of_uses=0
+        )
         response_path = self._base_path / key
 
         async with self._lock:
@@ -114,6 +137,36 @@ class AsyncFileStorage(AsyncBaseStorage):
             )
         await self._remove_expired_caches(response_path)
 
+    async def update_metadata(self, key: str, response: Response, request: Request, metadata: Metadata) -> None:
+        """
+        Updates the metadata of the stored response.
+
+        :param key: Hashed value of concatenated HTTP method and URI
+        :type key: str
+        :param response: An HTTP response
+        :type response: httpcore.Response
+        :param request: An HTTP request
+        :type request: httpcore.Request
+        :param metadata: Additional information about the stored response
+        :type metadata: Metadata
+        """
+        response_path = self._base_path / key
+
+        async with self._lock:
+            if response_path.exists():
+                atime = response_path.stat().st_atime
+                old_mtime = response_path.stat().st_mtime
+                await self._file_manager.write_to(
+                    str(response_path),
+                    self._serializer.dumps(response=response, request=request, metadata=metadata),
+                )
+
+                # Restore the old atime and mtime (we use mtime to check the cache expiration time)
+                os.utime(response_path, (atime, old_mtime))
+                return
+
+        return await self.store(key, response, request, metadata)  # pragma: no cover
+
     async def retrieve(self, key: str) -> tp.Optional[StoredResponse]:
         """
         Retreives the response from the cache using his key.
@@ -201,7 +254,7 @@ class AsyncSQLiteStorage(AsyncBaseStorage):
                 await self._connection.commit()
                 self._setup_completed = True
 
-    async def store(self, key: str, response: Response, request: Request, metadata: Metadata) -> None:
+    async def store(self, key: str, response: Response, request: Request, metadata: Metadata | None = None) -> None:
         """
         Stores the response in the cache.
 
@@ -212,12 +265,16 @@ class AsyncSQLiteStorage(AsyncBaseStorage):
         :param request: An HTTP request
         :type request: httpcore.Request
         :param metadata: Additioal information about the stored response
-        :type metadata: Metadata
+        :type metadata: Optional[Metadata]
         """
 
         await self._setup()
         assert self._connection
 
+        metadata = metadata or Metadata(
+            cache_key=key, created_at=datetime.datetime.now(datetime.timezone.utc), number_of_uses=0
+        )
+
         async with self._lock:
             await self._connection.execute("DELETE FROM cache WHERE key = ?", [key])
             serialized_response = self._serializer.dumps(response=response, request=request, metadata=metadata)
@@ -227,6 +284,33 @@ class AsyncSQLiteStorage(AsyncBaseStorage):
             await self._connection.commit()
         await self._remove_expired_caches()
 
+    async def update_metadata(self, key: str, response: Response, request: Request, metadata: Metadata) -> None:
+        """
+        Updates the metadata of the stored response.
+
+        :param key: Hashed value of concatenated HTTP method and URI
+        :type key: str
+        :param response: An HTTP response
+        :type response: httpcore.Response
+        :param request: An HTTP request
+        :type request: httpcore.Request
+        :param metadata: Additional information about the stored response
+        :type metadata: Metadata
+        """
+
+        await self._setup()
+        assert self._connection
+
+        async with self._lock:
+            cursor = await self._connection.execute("SELECT data FROM cache WHERE key = ?", [key])
+            row = await cursor.fetchone()
+            if row is not None:
+                serialized_response = self._serializer.dumps(response=response, request=request, metadata=metadata)
+                await self._connection.execute("UPDATE cache SET data = ? WHERE key = ?", [serialized_response, key])
+                await self._connection.commit()
+                return
+        return await self.store(key, response, request, metadata)  # pragma: no cover
+
     async def retrieve(self, key: str) -> tp.Optional[StoredResponse]:
         """
         Retreives the response from the cache using his key.
@@ -297,7 +381,7 @@ class AsyncRedisStorage(AsyncBaseStorage):
         else:  # pragma: no cover
             self._client = client
 
-    async def store(self, key: str, response: Response, request: Request, metadata: Metadata) -> None:
+    async def store(self, key: str, response: Response, request: Request, metadata: Metadata | None = None) -> None:
         """
         Stores the response in the cache.
 
@@ -308,9 +392,13 @@ class AsyncRedisStorage(AsyncBaseStorage):
         :param request: An HTTP request
         :type request: httpcore.Request
         :param metadata: Additioal information about the stored response
-        :type metadata: Metadata
+        :type metadata: Optional[Metadata]
         """
 
+        metadata = metadata or Metadata(
+            cache_key=key, created_at=datetime.datetime.now(datetime.timezone.utc), number_of_uses=0
+        )
+
         if self._ttl is not None:
             px = float_seconds_to_int_milliseconds(self._ttl)
         else:
@@ -320,6 +408,31 @@ class AsyncRedisStorage(AsyncBaseStorage):
             key, self._serializer.dumps(response=response, request=request, metadata=metadata), px=px
         )
 
+    async def update_metadata(self, key: str, response: Response, request: Request, metadata: Metadata) -> None:
+        """
+        Updates the metadata of the stored response.
+
+        :param key: Hashed value of concatenated HTTP method and URI
+        :type key: str
+        :param response: An HTTP response
+        :type response: httpcore.Response
+        :param request: An HTTP request
+        :type request: httpcore.Request
+        :param metadata: Additional information about the stored response
+        :type metadata: Metadata
+        """
+
+        ttl_in_milliseconds = await self._client.pttl(key)
+
+        if ttl_in_milliseconds == -2:  # pragma: no cover
+            await self.store(key, response, request, metadata)
+        else:
+            await self._client.set(
+                key,
+                self._serializer.dumps(response=response, request=request, metadata=metadata),
+                px=ttl_in_milliseconds,
+            )
+
     async def retrieve(self, key: str) -> tp.Optional[StoredResponse]:
         """
         Retreives the response from the cache using his key.
@@ -368,7 +481,7 @@ class AsyncInMemoryStorage(AsyncBaseStorage):
         self._cache: LFUCache[str, tp.Tuple[StoredResponse, float]] = LFUCache(capacity=capacity)
         self._lock = AsyncLock()
 
-    async def store(self, key: str, response: Response, request: Request, metadata: Metadata) -> None:
+    async def store(self, key: str, response: Response, request: Request, metadata: Metadata | None = None) -> None:
         """
         Stores the response in the cache.
 
@@ -379,9 +492,13 @@ class AsyncInMemoryStorage(AsyncBaseStorage):
         :param request: An HTTP request
         :type request: httpcore.Request
         :param metadata: Additioal information about the stored response
-        :type metadata: Metadata
+        :type metadata: Optional[Metadata]
         """
 
+        metadata = metadata or Metadata(
+            cache_key=key, created_at=datetime.datetime.now(datetime.timezone.utc), number_of_uses=0
+        )
+
         async with self._lock:
             response_clone = clone_model(response)
             request_clone = clone_model(request)
@@ -389,6 +506,30 @@ class AsyncInMemoryStorage(AsyncBaseStorage):
             self._cache.put(key, (stored_response, time.monotonic()))
         await self._remove_expired_caches()
 
+    async def update_metadata(self, key: str, response: Response, request: Request, metadata: Metadata) -> None:
+        """
+        Updates the metadata of the stored response.
+
+        :param key: Hashed value of concatenated HTTP method and URI
+        :type key: str
+        :param response: An HTTP response
+        :type response: httpcore.Response
+        :param request: An HTTP request
+        :type request: httpcore.Request
+        :param metadata: Additional information about the stored response
+        :type metadata: Metadata
+        """
+
+        async with self._lock:
+            try:
+                stored_response, created_at = self._cache.get(key)
+                stored_response = (stored_response[0], stored_response[1], metadata)
+                self._cache.put(key, (stored_response, created_at))
+                return
+            except KeyError:  # pragma: no cover
+                pass
+        await self.store(key, response, request, metadata)  # pragma: no cover
+
     async def retrieve(self, key: str) -> tp.Optional[StoredResponse]:
         """
         Retreives the response from the cache using his key.
@@ -427,7 +568,7 @@ class AsyncInMemoryStorage(AsyncBaseStorage):
                 self._cache.remove_key(key)
 
 
-class AsyncS3Storage(AsyncBaseStorage):
+class AsyncS3Storage(AsyncBaseStorage):  # pragma: no cover
     """
     AWS S3 storage.
 
@@ -473,7 +614,7 @@ class AsyncS3Storage(AsyncBaseStorage):
         )
         self._lock = AsyncLock()
 
-    async def store(self, key: str, response: Response, request: Request, metadata: Metadata) -> None:
+    async def store(self, key: str, response: Response, request: Request, metadata: Metadata | None = None) -> None:
         """
         Stores the response in the cache.
 
@@ -484,15 +625,37 @@ class AsyncS3Storage(AsyncBaseStorage):
         :param request: An HTTP request
         :type request: httpcore.Request
         :param metadata: Additioal information about the stored response
-        :type metadata: Metadata`
+        :type metadata: Optional[Metadata]`
         """
 
+        metadata = metadata or Metadata(
+            cache_key=key, created_at=datetime.datetime.now(datetime.timezone.utc), number_of_uses=0
+        )
+
         async with self._lock:
             serialized = self._serializer.dumps(response=response, request=request, metadata=metadata)
             await self._s3_manager.write_to(path=key, data=serialized)
 
         await self._remove_expired_caches(key)
 
+    async def update_metadata(self, key: str, response: Response, request: Request, metadata: Metadata) -> None:
+        """
+        Updates the metadata of the stored response.
+
+        :param key: Hashed value of concatenated HTTP method and URI
+        :type key: str
+        :param response: An HTTP response
+        :type response: httpcore.Response
+        :param request: An HTTP request
+        :type request: httpcore.Request
+        :param metadata: Additional information about the stored response
+        :type metadata: Metadata
+        """
+
+        async with self._lock:
+            serialized = self._serializer.dumps(response=response, request=request, metadata=metadata)
+            await self._s3_manager.write_to(path=key, data=serialized, only_metadata=True)
+
     async def retrieve(self, key: str) -> tp.Optional[StoredResponse]:
         """
         Retreives the response from the cache using his key.