hishel 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

hishel/__init__.py

@@ -8,10 +8,50 @@ from ._serializers import *
 from ._sync import *
 from ._lfu_cache import *
 
+__all__ = (
+    # Old API
+    "AsyncCacheClient",
+    "MockAsyncConnectionPool",
+    "MockAsyncTransport",
+    "AsyncCacheConnectionPool",
+    "AsyncBaseStorage",
+    "AsyncFileStorage",
+    "AsyncInMemoryStorage",
+    "AsyncRedisStorage",
+    "AsyncS3Storage",
+    "AsyncSQLiteStorage",
+    "AsyncCacheTransport",
+    "HEURISTICALLY_CACHEABLE_STATUS_CODES",
+    "Controller",
+    "CacheControlError",
+    "ParseError",
+    "ValidationError",
+    "CacheControl",
+    "Vary",
+    "BaseSerializer",
+    "JSONSerializer",
+    "Metadata",
+    "PickleSerializer",
+    "YAMLSerializer",
+    "clone_model",
+    "CacheClient",
+    "MockConnectionPool",
+    "MockTransport",
+    "CacheConnectionPool",
+    "BaseStorage",
+    "FileStorage",
+    "InMemoryStorage",
+    "RedisStorage",
+    "S3Storage",
+    "SQLiteStorage",
+    "CacheTransport",
+    "LFUCache",
+)
 
 def install_cache() -> None:  # pragma: no cover
     httpx.AsyncClient = AsyncCacheClient  # type: ignore
     httpx.Client = CacheClient  # type: ignore
 
 
-__version__ = "0.1.2"
+__version__ = "0.1.4"
+

hishel/_async/_client.py

@@ -2,7 +2,7 @@ import typing as tp
 
 import httpx
 
-from hishel._async._transports import AsyncCacheTransport
+from ._transports import AsyncCacheTransport
 
 __all__ = ("AsyncCacheClient",)
 

hishel/_async/_storages.py

@@ -4,7 +4,6 @@ import datetime
 import logging
 import os
 import time
-import typing as t
 import typing as tp
 import warnings
 from copy import deepcopy
@@ -24,13 +23,11 @@ except ImportError:  # pragma: no cover
 
 from httpcore import Request, Response
 
-if t.TYPE_CHECKING:  # pragma: no cover
+if tp.TYPE_CHECKING:  # pragma: no cover
     from typing_extensions import TypeAlias
 
-from hishel._serializers import BaseSerializer, clone_model
-
 from .._files import AsyncFileManager
-from .._serializers import JSONSerializer, Metadata
+from .._serializers import BaseSerializer, JSONSerializer, Metadata, clone_model
 from .._synchronization import AsyncLock
 from .._utils import float_seconds_to_int_milliseconds
 
@@ -39,10 +36,10 @@ logger = logging.getLogger("hishel.storages")
 __all__ = (
     "AsyncBaseStorage",
     "AsyncFileStorage",
-    "AsyncRedisStorage",
-    "AsyncSQLiteStorage",
     "AsyncInMemoryStorage",
+    "AsyncRedisStorage",
     "AsyncS3Storage",
+    "AsyncSQLiteStorage",
 )
 
 StoredResponse: TypeAlias = tp.Tuple[Response, Request, Metadata]
@@ -106,8 +103,7 @@ class AsyncFileStorage(AsyncBaseStorage):
         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)
+        self._base_path.mkdir(parents=True, exist_ok=True)
 
         if not self._gitignore_file.is_file():
             with open(self._gitignore_file, "w", encoding="utf-8") as f:
@@ -153,13 +149,13 @@ class AsyncFileStorage(AsyncBaseStorage):
         """
 
         if isinstance(key, Response):  # pragma: no cover
-            key = t.cast(str, key.extensions["cache_metadata"]["cache_key"])
+            key = tp.cast(str, key.extensions["cache_metadata"]["cache_key"])
 
         response_path = self._base_path / key
 
         async with self._lock:
             if response_path.exists():
-                response_path.unlink()
+                response_path.unlink(missing_ok=True)
 
     async def update_metadata(self, key: str, response: Response, request: Request, metadata: Metadata) -> None:
         """
@@ -222,7 +218,7 @@ class AsyncFileStorage(AsyncBaseStorage):
             if response_path.is_file():
                 age = time.time() - response_path.stat().st_mtime
                 if age > self._ttl:
-                    response_path.unlink()
+                    response_path.unlink(missing_ok=True)
             return
 
         self._last_cleaned = time.monotonic()
@@ -322,7 +318,7 @@ class AsyncSQLiteStorage(AsyncBaseStorage):
         assert self._connection
 
         if isinstance(key, Response):  # pragma: no cover
-            key = t.cast(str, key.extensions["cache_metadata"]["cache_key"])
+            key = tp.cast(str, key.extensions["cache_metadata"]["cache_key"])
 
         async with self._lock:
             await self._connection.execute("DELETE FROM cache WHERE key = ?", [key])
@@ -459,7 +455,7 @@ class AsyncRedisStorage(AsyncBaseStorage):
         """
 
         if isinstance(key, Response):  # pragma: no cover
-            key = t.cast(str, key.extensions["cache_metadata"]["cache_key"])
+            key = tp.cast(str, key.extensions["cache_metadata"]["cache_key"])
 
         await self._client.delete(key)
 
@@ -507,7 +503,7 @@ class AsyncRedisStorage(AsyncBaseStorage):
         return self._serializer.loads(cached_response)
 
     async def aclose(self) -> None:  # pragma: no cover
-        await self._client.close()
+        await self._client.aclose()
 
 
 class AsyncInMemoryStorage(AsyncBaseStorage):
@@ -572,7 +568,7 @@ class AsyncInMemoryStorage(AsyncBaseStorage):
         """
 
         if isinstance(key, Response):  # pragma: no cover
-            key = t.cast(str, key.extensions["cache_metadata"]["cache_key"])
+            key = tp.cast(str, key.extensions["cache_metadata"]["cache_key"])
 
         async with self._lock:
             self._cache.remove_key(key)
@@ -654,6 +650,8 @@ class AsyncS3Storage(AsyncBaseStorage):  # pragma: no cover
     :type check_ttl_every: tp.Union[int, float]
     :param client: A client for S3, defaults to None
     :type client: tp.Optional[tp.Any], optional
+    :param path_prefix: A path prefix to use for S3 object keys, defaults to "hishel-"
+    :type path_prefix: str, optional
     """
 
     def __init__(
@@ -663,6 +661,7 @@ class AsyncS3Storage(AsyncBaseStorage):  # pragma: no cover
         ttl: tp.Optional[tp.Union[int, float]] = None,
         check_ttl_every: tp.Union[int, float] = 60,
         client: tp.Optional[tp.Any] = None,
+        path_prefix: str = "hishel-",
     ) -> None:
         super().__init__(serializer, ttl)
 
@@ -680,6 +679,7 @@ class AsyncS3Storage(AsyncBaseStorage):  # pragma: no cover
             bucket_name=bucket_name,
             is_binary=self._serializer.is_binary,
             check_ttl_every=check_ttl_every,
+            path_prefix=path_prefix,
         )
         self._lock = AsyncLock()
 
@@ -716,7 +716,7 @@ class AsyncS3Storage(AsyncBaseStorage):  # pragma: no cover
         """
 
         if isinstance(key, Response):  # pragma: no cover
-            key = t.cast(str, key.extensions["cache_metadata"]["cache_key"])
+            key = tp.cast(str, key.extensions["cache_metadata"]["cache_key"])
 
         async with self._lock:
             await self._s3_manager.remove_entry(key)

hishel/_async/_transports.py

@@ -8,11 +8,10 @@ import httpx
 from httpx import AsyncByteStream, Request, Response
 from httpx._exceptions import ConnectError
 
-from hishel._utils import extract_header_values_decoded, normalized_url
-
 from .._controller import Controller, allowed_stale
 from .._headers import parse_cache_control
 from .._serializers import JSONSerializer, Metadata
+from .._utils import extract_header_values_decoded, normalized_url
 from ._storages import AsyncBaseStorage, AsyncFileStorage
 
 if tp.TYPE_CHECKING:  # pragma: no cover
@@ -211,11 +210,17 @@ class AsyncCacheTransport(httpx.AsyncBaseTransport):
                 )
 
         regular_response = await self._transport.handle_async_request(request)
-        assert isinstance(regular_response.stream, tp.AsyncIterable)
+        try:
+            # Prefer already-read content, if available
+            stream = fake_stream(regular_response.content)
+        except httpx.ResponseNotRead:
+            # Fall back to stream if not yet read
+            assert isinstance(regular_response.stream, tp.AsyncIterable)
+            stream = regular_response.stream
         httpcore_regular_response = httpcore.Response(
             status=regular_response.status_code,
             headers=regular_response.headers.raw,
-            content=AsyncCacheStream(regular_response.stream),
+            content=AsyncCacheStream(stream),
             extensions=regular_response.extensions,
         )
         await httpcore_regular_response.aread()

hishel/_controller.py

@@ -3,8 +3,7 @@ import typing as tp
 
 from httpcore import Request, Response
 
-from hishel._headers import Vary, parse_cache_control
-
+from ._headers import Vary, parse_cache_control
 from ._utils import (
     BaseClock,
     Clock,
@@ -21,7 +20,7 @@ logger = logging.getLogger("hishel.controller")
 HEURISTICALLY_CACHEABLE_STATUS_CODES = (200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414, 501)
 HTTP_METHODS = ["GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT", "OPTIONS", "TRACE", "PATCH"]
 
-__all__ = ("Controller", "HEURISTICALLY_CACHEABLE_STATUS_CODES")
+__all__ = ("HEURISTICALLY_CACHEABLE_STATUS_CODES", "Controller")
 
 
 def get_updated_headers(

hishel/_lmdb_types_.pyi

@@ -0,0 +1,53 @@
+from contextlib import contextmanager
+from typing import Any, Iterator
+
+class Database: ...
+
+class Transaction:
+    def get(self, key: bytes, *, db: Database | None = None) -> bytes | None:
+        """
+        Get the value associated with the given key.
+        """
+        pass
+
+    def put(self, key: bytes, value: bytes, *, db: Database | None = None, dupdata: bool = False) -> None:
+        """
+        Put a key-value pair into the database.
+        """
+        pass
+
+    def delete(self, key: bytes, *, db: Database | None = None) -> bool:
+        """
+        Delete the key from the database.
+        """
+        pass
+
+    def cursor(self, db: Database) -> Any:
+        """
+        Create a cursor for iterating over key-value pairs in the database.
+        """
+        pass
+
+class Environment:
+    @contextmanager
+    def begin(self, *, db: Database | None = None, write: bool = False) -> Iterator[Transaction]:
+        """
+        Begin a transaction in the environment.
+        """
+        raise NotImplementedError("It's only for type hinting purposes")
+
+    def open_db(self, key: bytes, dupsort: bool = False) -> Database:
+        """
+        Open a database within the environment.
+        """
+        raise NotImplementedError("It's only for type hinting purposes")
+
+def open(
+    path: str,
+    *,
+    max_dbs: int = 0,
+) -> Environment:
+    """
+    Open an LMDB environment at the specified path.
+    """
+    raise NotImplementedError("It's only for type hinting purposes")

hishel/_s3.py

@@ -11,16 +11,22 @@ def get_timestamp_in_ms() -> float:
 
 class S3Manager:
     def __init__(
-        self, client: tp.Any, bucket_name: str, check_ttl_every: tp.Union[int, float], is_binary: bool = False
+        self,
+        client: tp.Any,
+        bucket_name: str,
+        check_ttl_every: tp.Union[int, float],
+        is_binary: bool = False,
+        path_prefix: str = "hishel-",
     ):
         self._client = client
         self._bucket_name = bucket_name
         self._is_binary = is_binary
         self._last_cleaned = time.monotonic()
         self._check_ttl_every = check_ttl_every
+        self._path_prefix = path_prefix
 
     def write_to(self, path: str, data: tp.Union[bytes, str], only_metadata: bool = False) -> None:
-        path = "hishel-" + path
+        path = self._path_prefix + path
         if isinstance(data, str):
             data = data.encode("utf-8")
 
@@ -43,7 +49,7 @@ class S3Manager:
         )
 
     def read_from(self, path: str) -> tp.Union[bytes, str]:
-        path = "hishel-" + path
+        path = self._path_prefix + path
         response = self._client.get_object(
             Bucket=self._bucket_name,
             Key=path,
@@ -57,7 +63,7 @@ class S3Manager:
         return tp.cast(str, content.decode("utf-8"))
 
     def remove_expired(self, ttl: int, key: str) -> None:
-        path = "hishel-" + key
+        path = self._path_prefix + key
 
         if time.monotonic() - self._last_cleaned < self._check_ttl_every:
             try:
@@ -72,7 +78,7 @@ class S3Manager:
 
         self._last_cleaned = time.monotonic()
         for obj in self._client.list_objects(Bucket=self._bucket_name).get("Contents", []):
-            if not obj["Key"].startswith("hishel-"):  # pragma: no cover
+            if not obj["Key"].startswith(self._path_prefix):  # pragma: no cover
                 continue
 
             try:
@@ -88,15 +94,20 @@ class S3Manager:
                 self._client.delete_object(Bucket=self._bucket_name, Key=obj["Key"])
 
     def remove_entry(self, key: str) -> None:
-        path = "hishel-" + key
+        path = self._path_prefix + key
         self._client.delete_object(Bucket=self._bucket_name, Key=path)
 
 
 class AsyncS3Manager:  # pragma: no cover
     def __init__(
-        self, client: tp.Any, bucket_name: str, check_ttl_every: tp.Union[int, float], is_binary: bool = False
+        self,
+        client: tp.Any,
+        bucket_name: str,
+        check_ttl_every: tp.Union[int, float],
+        is_binary: bool = False,
+        path_prefix: str = "hishel-",
     ):
-        self._sync_manager = S3Manager(client, bucket_name, check_ttl_every, is_binary)
+        self._sync_manager = S3Manager(client, bucket_name, check_ttl_every, is_binary, path_prefix)
 
     async def write_to(self, path: str, data: tp.Union[bytes, str], only_metadata: bool = False) -> None:
         return await to_thread.run_sync(self._sync_manager.write_to, path, data, only_metadata)

hishel/_serializers.py

@@ -6,7 +6,7 @@ from datetime import datetime
 
 from httpcore import Request, Response
 
-from hishel._utils import normalized_url
+from ._utils import normalized_url
 
 try:
     import yaml
@@ -17,7 +17,7 @@ HEADERS_ENCODING = "iso-8859-1"
 KNOWN_RESPONSE_EXTENSIONS = ("http_version", "reason_phrase")
 KNOWN_REQUEST_EXTENSIONS = ("timeout", "sni_hostname")
 
-__all__ = ("PickleSerializer", "JSONSerializer", "YAMLSerializer", "BaseSerializer", "clone_model")
+__all__ = ("BaseSerializer", "JSONSerializer", "Metadata", "PickleSerializer", "YAMLSerializer", "clone_model")
 
 T = tp.TypeVar("T", Request, Response)
 

hishel/_sync/_client.py

@@ -2,7 +2,7 @@ import typing as tp
 
 import httpx
 
-from hishel._sync._transports import CacheTransport
+from ._transports import CacheTransport
 
 __all__ = ("CacheClient",)
 

hishel/_sync/_storages.py

@@ -4,7 +4,6 @@ import datetime
 import logging
 import os
 import time
-import typing as t
 import typing as tp
 import warnings
 from copy import deepcopy
@@ -24,13 +23,11 @@ except ImportError:  # pragma: no cover
 
 from httpcore import Request, Response
 
-if t.TYPE_CHECKING:  # pragma: no cover
+if tp.TYPE_CHECKING:  # pragma: no cover
     from typing_extensions import TypeAlias
 
-from hishel._serializers import BaseSerializer, clone_model
-
 from .._files import FileManager
-from .._serializers import JSONSerializer, Metadata
+from .._serializers import BaseSerializer, JSONSerializer, Metadata, clone_model
 from .._synchronization import Lock
 from .._utils import float_seconds_to_int_milliseconds
 
@@ -39,10 +36,10 @@ logger = logging.getLogger("hishel.storages")
 __all__ = (
     "BaseStorage",
     "FileStorage",
-    "RedisStorage",
-    "SQLiteStorage",
     "InMemoryStorage",
+    "RedisStorage",
     "S3Storage",
+    "SQLiteStorage",
 )
 
 StoredResponse: TypeAlias = tp.Tuple[Response, Request, Metadata]
@@ -106,8 +103,7 @@ class FileStorage(BaseStorage):
         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)
+        self._base_path.mkdir(parents=True, exist_ok=True)
 
         if not self._gitignore_file.is_file():
             with open(self._gitignore_file, "w", encoding="utf-8") as f:
@@ -153,13 +149,13 @@ class FileStorage(BaseStorage):
         """
 
         if isinstance(key, Response):  # pragma: no cover
-            key = t.cast(str, key.extensions["cache_metadata"]["cache_key"])
+            key = tp.cast(str, key.extensions["cache_metadata"]["cache_key"])
 
         response_path = self._base_path / key
 
         with self._lock:
             if response_path.exists():
-                response_path.unlink()
+                response_path.unlink(missing_ok=True)
 
     def update_metadata(self, key: str, response: Response, request: Request, metadata: Metadata) -> None:
         """
@@ -222,7 +218,7 @@ class FileStorage(BaseStorage):
             if response_path.is_file():
                 age = time.time() - response_path.stat().st_mtime
                 if age > self._ttl:
-                    response_path.unlink()
+                    response_path.unlink(missing_ok=True)
             return
 
         self._last_cleaned = time.monotonic()
@@ -322,7 +318,7 @@ class SQLiteStorage(BaseStorage):
         assert self._connection
 
         if isinstance(key, Response):  # pragma: no cover
-            key = t.cast(str, key.extensions["cache_metadata"]["cache_key"])
+            key = tp.cast(str, key.extensions["cache_metadata"]["cache_key"])
 
         with self._lock:
             self._connection.execute("DELETE FROM cache WHERE key = ?", [key])
@@ -459,7 +455,7 @@ class RedisStorage(BaseStorage):
         """
 
         if isinstance(key, Response):  # pragma: no cover
-            key = t.cast(str, key.extensions["cache_metadata"]["cache_key"])
+            key = tp.cast(str, key.extensions["cache_metadata"]["cache_key"])
 
         self._client.delete(key)
 
@@ -572,7 +568,7 @@ class InMemoryStorage(BaseStorage):
         """
 
         if isinstance(key, Response):  # pragma: no cover
-            key = t.cast(str, key.extensions["cache_metadata"]["cache_key"])
+            key = tp.cast(str, key.extensions["cache_metadata"]["cache_key"])
 
         with self._lock:
             self._cache.remove_key(key)
@@ -654,6 +650,8 @@ class S3Storage(BaseStorage):  # pragma: no cover
     :type check_ttl_every: tp.Union[int, float]
     :param client: A client for S3, defaults to None
     :type client: tp.Optional[tp.Any], optional
+    :param path_prefix: A path prefix to use for S3 object keys, defaults to "hishel-"
+    :type path_prefix: str, optional
     """
 
     def __init__(
@@ -663,6 +661,7 @@ class S3Storage(BaseStorage):  # pragma: no cover
         ttl: tp.Optional[tp.Union[int, float]] = None,
         check_ttl_every: tp.Union[int, float] = 60,
         client: tp.Optional[tp.Any] = None,
+        path_prefix: str = "hishel-",
     ) -> None:
         super().__init__(serializer, ttl)
 
@@ -680,6 +679,7 @@ class S3Storage(BaseStorage):  # pragma: no cover
             bucket_name=bucket_name,
             is_binary=self._serializer.is_binary,
             check_ttl_every=check_ttl_every,
+            path_prefix=path_prefix,
         )
         self._lock = Lock()
 
@@ -716,7 +716,7 @@ class S3Storage(BaseStorage):  # pragma: no cover
         """
 
         if isinstance(key, Response):  # pragma: no cover
-            key = t.cast(str, key.extensions["cache_metadata"]["cache_key"])
+            key = tp.cast(str, key.extensions["cache_metadata"]["cache_key"])
 
         with self._lock:
             self._s3_manager.remove_entry(key)

hishel/_sync/_transports.py

@@ -8,11 +8,10 @@ import httpx
 from httpx import SyncByteStream, Request, Response
 from httpx._exceptions import ConnectError
 
-from hishel._utils import extract_header_values_decoded, normalized_url
-
 from .._controller import Controller, allowed_stale
 from .._headers import parse_cache_control
 from .._serializers import JSONSerializer, Metadata
+from .._utils import extract_header_values_decoded, normalized_url
 from ._storages import BaseStorage, FileStorage
 
 if tp.TYPE_CHECKING:  # pragma: no cover
@@ -211,11 +210,17 @@ class CacheTransport(httpx.BaseTransport):
                 )
 
         regular_response = self._transport.handle_request(request)
-        assert isinstance(regular_response.stream, tp.Iterable)
+        try:
+            # Prefer already-read content, if available
+            stream = fake_stream(regular_response.content)
+        except httpx.ResponseNotRead:
+            # Fall back to stream if not yet read
+            assert isinstance(regular_response.stream, tp.Iterable)
+            stream = regular_response.stream
         httpcore_regular_response = httpcore.Response(
             status=regular_response.status_code,
             headers=regular_response.headers.raw,
-            content=CacheStream(regular_response.stream),
+            content=CacheStream(stream),
             extensions=regular_response.extensions,
         )
         httpcore_regular_response.read()