Feature: support hishel v2

docs/usage/getting-started/configuration.md

@@ -312,6 +312,15 @@ github = GitHub(
 
     The `prefix` parameter adds a key namespace in Redis. Both githubkit and [Hishel](https://hishel.com/) use this prefix.
 
+!!! note "Migrating to Hishel 2.0"
+
+    githubkit now depends on Hishel `>=2.0`. If you implement a custom `BaseCacheStrategy` or use githubkit's cache clients directly, note these breaking changes:
+
+    - `get_hishel_policy()` must return a `hishel.CacheOptions` instead of a `CachePolicy`. Hishel 2.0 removed `CachePolicy` and `SpecificationPolicy`. For example, replace `SpecificationPolicy(cache_options=CacheOptions(shared=False))` with `CacheOptions(shared=False)`.
+    - `get_hishel_storage()` must return a `hishel.BaseStorage` (formerly `SyncBaseStorage`). `SyncSqliteStorage` is now `SqliteStorage`.
+    - The `policy` argument of `SyncCacheClient` / `AsyncCacheClient` now accepts `CacheOptions | bool` and defaults to `True` (RFC 9111 caching, same behavior as before). Passing an old `CachePolicy` raises a `TypeError`.
+    - `SyncMemoryStorage` / `AsyncMemoryStorage` no longer accept `refresh_ttl_on_access`.
+
 ### `http_cache`
 
 Enables HTTP response caching powered by [Hishel](https://hishel.com/). When enabled, githubkit respects standard HTTP caching headers (`ETag`, `Last-Modified`, `Cache-Control`) returned by the GitHub API. This reduces redundant API calls and helps you stay within [rate limits](https://docs.github.com/en/rest/rate-limit).

githubkit/_httpx.py

@@ -6,13 +6,13 @@
 
 if TYPE_CHECKING:
     from hishel.httpx2 import AsyncCacheTransport as AsyncCacheTransport
-    from hishel.httpx2 import SyncCacheTransport as SyncCacheTransport
+    from hishel.httpx2 import CacheTransport as CacheTransport
     import httpx2 as httpx
 else:
     httpx = None
     if not os.getenv(GITHUBKIT_HTTPX2_DISABLE_FLAG):
         try:
-            from hishel.httpx2 import AsyncCacheTransport, SyncCacheTransport
+            from hishel.httpx2 import AsyncCacheTransport, CacheTransport
             import httpx2 as httpx
         except ImportError:
             # Hishel wraps a missing HTTP client in ImportError.
@@ -21,7 +21,7 @@
     if httpx is None:
         try:
             from hishel.httpx import AsyncCacheTransport as AsyncCacheTransport
-            from hishel.httpx import SyncCacheTransport as SyncCacheTransport
+            from hishel.httpx import CacheTransport as CacheTransport
             import httpx as httpx
         except ImportError:
             raise RuntimeError(

githubkit/cache/base.py

@@ -3,10 +3,8 @@
 
 from hishel import (
     AsyncBaseStorage,
+    BaseStorage,
     CacheOptions,
-    CachePolicy,
-    SpecificationPolicy,
-    SyncBaseStorage,
 )
 
 
@@ -47,12 +45,12 @@ async def get_async_cache_storage(self) -> AsyncBaseCache:
         """
         raise NotImplementedError
 
-    def get_hishel_policy(self) -> CachePolicy:
+    def get_hishel_policy(self) -> CacheOptions:
         """Get the hishel cache policy instance"""
-        return SpecificationPolicy(cache_options=CacheOptions(shared=False))
+        return CacheOptions(shared=False)
 
     @abc.abstractmethod
-    def get_hishel_storage(self) -> SyncBaseStorage:
+    def get_hishel_storage(self) -> BaseStorage:
         """Get the hishel storage instance used in sync context"""
         raise NotImplementedError
 

githubkit/hishel.py

@@ -6,62 +6,74 @@
 from hishel import (
     AsyncBaseStorage,
     AsyncSqliteStorage,
-    CachePolicy,
-    SyncBaseStorage,
-    SyncSqliteStorage,
+    BaseStorage,
+    CacheOptions,
+    SqliteStorage,
 )
 
-from ._httpx import AsyncCacheTransport, SyncCacheTransport, httpx
+from ._httpx import AsyncCacheTransport, CacheTransport, httpx
+
+
+def _check_policy(policy: Any) -> None:
+    if not isinstance(policy, (bool, dict)):
+        raise TypeError(
+            "policy must be a hishel CacheOptions instance or a bool, "
+            f"got {type(policy).__name__}. hishel 2.0 removed CachePolicy "
+            "(e.g. SpecificationPolicy); pass CacheOptions(...) instead."
+        )
 
 
 class SyncCacheClient(httpx.Client):
     def __init__(self, *args: Any, **kwargs: Any):
-        self.storage: SyncBaseStorage | None = kwargs.pop("storage", None)
-        self.policy: CachePolicy | None = kwargs.pop("policy", None)
+        self.storage: BaseStorage | None = kwargs.pop("storage", None)
+        policy = kwargs.pop("policy", True)
+        _check_policy(policy)
+        self.policy: CacheOptions | bool = policy
         super().__init__(*args, **kwargs)
 
     def _init_transport(self, *args, **kwargs) -> httpx.BaseTransport:
         _transport = super()._init_transport(*args, **kwargs)
-        return SyncCacheTransport(
-            next_transport=_transport, storage=self.storage, policy=self.policy
+        return CacheTransport(
+            next_transport=_transport, storage=self.storage, rfc=self.policy
         )
 
     def _init_proxy_transport(self, *args, **kwargs) -> httpx.BaseTransport:
         _transport = super()._init_proxy_transport(*args, **kwargs)
-        return SyncCacheTransport(
-            next_transport=_transport, storage=self.storage, policy=self.policy
+        return CacheTransport(
+            next_transport=_transport, storage=self.storage, rfc=self.policy
         )
 
 
 class AsyncCacheClient(httpx.AsyncClient):
     def __init__(self, *args: Any, **kwargs: Any):
         self.storage: AsyncBaseStorage | None = kwargs.pop("storage", None)
-        self.policy: CachePolicy | None = kwargs.pop("policy", None)
+        policy = kwargs.pop("policy", True)
+        _check_policy(policy)
+        self.policy: CacheOptions | bool = policy
         super().__init__(*args, **kwargs)
 
     def _init_transport(self, *args, **kwargs) -> httpx.AsyncBaseTransport:
         _transport = super()._init_transport(*args, **kwargs)
         return AsyncCacheTransport(
-            next_transport=_transport, storage=self.storage, policy=self.policy
+            next_transport=_transport, storage=self.storage, rfc=self.policy
         )
 
     def _init_proxy_transport(self, *args, **kwargs) -> httpx.AsyncBaseTransport:
         _transport = super()._init_proxy_transport(*args, **kwargs)
         return AsyncCacheTransport(
-            next_transport=_transport, storage=self.storage, policy=self.policy
+            next_transport=_transport, storage=self.storage, rfc=self.policy
         )
 
 
-class SyncMemoryStorage(SyncSqliteStorage):
+class SyncMemoryStorage(SqliteStorage):
     def __init__(
         self,
         *,
         default_ttl: float | None = None,
-        refresh_ttl_on_access: bool | None = None,
         keep_unclosed: bool = False,
     ) -> None:
         super().__init__(
-            default_ttl=default_ttl, refresh_ttl_on_access=refresh_ttl_on_access
+            default_ttl=default_ttl,
         )
         # NOTE: hishel close the storage when the client transport is closed.
         # but for in-memory sqlite,
@@ -91,11 +103,10 @@ def __init__(
         self,
         *,
         default_ttl: float | None = None,
-        refresh_ttl_on_access: bool | None = None,
         keep_unclosed: bool = False,
     ) -> None:
         super().__init__(
-            default_ttl=default_ttl, refresh_ttl_on_access=refresh_ttl_on_access
+            default_ttl=default_ttl,
         )
         # NOTE: hishel close the storage when the client transport is closed.
         # but for in-memory sqlite,
@@ -117,7 +128,7 @@ async def _ensure_connection(self) -> anysqlite.Connection:
     async def close(self) -> None:
         if self.keep_unclosed:
             # Do not close the connection, but drain all pending writes
-            async with self._write_lock:
+            async with self._init_lock:
                 return
         return await super().close()
 

pyproject.toml

@@ -10,7 +10,7 @@ requires-python = ">=3.10, <4.0"
 dependencies = [
   "anyio >=3.6.1, <5.0.0",
   "httpx >=0.23.0, <1.0.0",
-  "hishel[async,httpx] >=1.4.0, <2.0.0",
+  "hishel[async,httpx] >=2.0.0, <3.0.0",
   "typing-extensions >=4.13.0, <5.0.0",
   "pydantic >=1.9.1, <3.0.0, !=2.5.0, !=2.5.1",
   "githubkit-schemas >=26.5.7",