✨ Feature: add redis cache support (#162)

Author: yanyongyu

docs/usage/configuration.md

@@ -72,6 +72,12 @@ The `timeout` option is used to set the request timeout. You can pass a float, `
 
 The `cache_strategy` option defines how to cache the tokens or http responses. You can provide a githubkit built-in cache strategy or a custom one that implements the `BaseCacheStrategy` interface. By default, githubkit uses the `MemCacheStrategy` to cache the data in memory.
 
+Available built-in cache strategies:
+
+- `MemCacheStrategy`: Cache the data in memory.
+- `RedisCacheStrategy`: Cache the data in Redis (Sync only).
+- `AsyncRedisCacheStrategy`: Cache the data in Redis (Async only).
+
 ### `http_cache`
 
 The `http_cache` option enables the http caching feature powered by [Hishel](https://hishel.com/) for HTTPX. GitHub API limits the number of requests that you can make within a specific amount of time. This feature is useful to reduce the number of requests to GitHub API and avoid hitting the rate limit.

githubkit/cache/__init__.py

@@ -1,7 +1,11 @@
 from .base import BaseCache as BaseCache
 from .mem_cache import MemCache as MemCache
+from .redis import RedisCache as RedisCache
 from .base import AsyncBaseCache as AsyncBaseCache
+from .redis import AsyncRedisCache as AsyncRedisCache
 from .base import BaseCacheStrategy as BaseCacheStrategy
 from .mem_cache import MemCacheStrategy as MemCacheStrategy
+from .redis import RedisCacheStrategy as RedisCacheStrategy
+from .redis import AsyncRedisCacheStrategy as AsyncRedisCacheStrategy
 
 DEFAULT_CACHE_STRATEGY = MemCacheStrategy()

githubkit/cache/mem_cache.py

@@ -1,5 +1,6 @@
 from typing import Optional
 from dataclasses import dataclass
+from typing_extensions import override
 from datetime import datetime, timezone, timedelta
 
 from hishel import InMemoryStorage, AsyncInMemoryStorage
@@ -25,17 +26,21 @@ def expire(self):
             if item.expire_at is not None and item.expire_at < now:
                 self._cache.pop(key, None)
 
+    @override
     def get(self, key: str) -> Optional[str]:
         self.expire()
         return (item := self._cache.get(key, None)) and item.value
 
+    @override
     async def aget(self, key: str) -> Optional[str]:
         return self.get(key)
 
+    @override
     def set(self, key: str, value: str, ex: timedelta) -> None:
         self.expire()
         self._cache[key] = _Item(value, datetime.now(timezone.utc) + ex)
 
+    @override
     async def aset(self, key: str, value: str, ex: timedelta) -> None:
         return self.set(key, value, ex)
 
@@ -46,19 +51,23 @@ def __init__(self) -> None:
         self._hishel_storage: Optional[InMemoryStorage] = None
         self._hishel_async_storage: Optional[AsyncInMemoryStorage] = None
 
+    @override
     def get_cache_storage(self) -> MemCache:
         if self._cache is None:
             self._cache = MemCache()
         return self._cache
 
+    @override
     def get_async_cache_storage(self) -> MemCache:
         return self.get_cache_storage()
 
+    @override
     def get_hishel_storage(self) -> InMemoryStorage:
         if self._hishel_storage is None:
             self._hishel_storage = InMemoryStorage()
         return self._hishel_storage
 
+    @override
     def get_async_hishel_storage(self) -> AsyncInMemoryStorage:
         if self._hishel_async_storage is None:
             self._hishel_async_storage = AsyncInMemoryStorage()

githubkit/cache/redis.py

@@ -0,0 +1,102 @@
+from datetime import timedelta
+from typing_extensions import override
+from typing import TYPE_CHECKING, Any, NoReturn, Optional
+
+from hishel import RedisStorage, AsyncBaseStorage, AsyncRedisStorage
+
+from githubkit.exception import CacheUnsupportedError
+
+from .base import BaseCache, AsyncBaseCache, BaseCacheStrategy
+
+if TYPE_CHECKING:
+    from redis import Redis
+    from redis.asyncio import Redis as AsyncRedis
+
+
+def _ensure_str_or_none(value: Any) -> Optional[str]:
+    if isinstance(value, str):
+        return value
+    elif isinstance(value, bytes):
+        return value.decode("utf-8")
+    elif value is None:
+        return None
+    else:
+        raise RuntimeError(f"Unexpected redis value {value!r} with type {type(value)}")
+
+
+class RedisCache(BaseCache):
+    def __init__(self, client: "Redis") -> None:
+        self.client = client
+
+    @override
+    def get(self, key: str) -> Optional[str]:
+        data = self.client.get(key)
+        return _ensure_str_or_none(data)
+
+    @override
+    def set(self, key: str, value: str, ex: timedelta) -> None:
+        self.client.set(key, value, ex)
+
+
+class AsyncRedisCache(AsyncBaseCache):
+    def __init__(self, client: "AsyncRedis") -> None:
+        self.client = client
+
+    @override
+    async def aget(self, key: str) -> Optional[str]:
+        data = await self.client.get(key)
+        return _ensure_str_or_none(data)
+
+    @override
+    async def aset(self, key: str, value: str, ex: timedelta) -> None:
+        await self.client.set(key, value, ex)
+
+
+class RedisCacheStrategy(BaseCacheStrategy):
+    def __init__(self, client: "Redis") -> None:
+        self.client = client
+
+    @override
+    def get_cache_storage(self) -> RedisCache:
+        return RedisCache(self.client)
+
+    @override
+    def get_async_cache_storage(self) -> NoReturn:
+        raise CacheUnsupportedError(
+            "Sync redis cache strategy does not support async usage"
+        )
+
+    @override
+    def get_hishel_storage(self) -> RedisStorage:
+        return RedisStorage(client=self.client)
+
+    @override
+    def get_async_hishel_storage(self) -> NoReturn:
+        raise CacheUnsupportedError(
+            "Sync redis cache strategy does not support async usage"
+        )
+
+
+class AsyncRedisCacheStrategy(BaseCacheStrategy):
+    def __init__(self, client: "AsyncRedis") -> None:
+        self.client = client
+
+    @override
+    def get_cache_storage(self) -> NoReturn:
+        raise CacheUnsupportedError(
+            "Async redis cache strategy does not support sync usage"
+        )
+
+    @override
+    def get_async_cache_storage(self) -> AsyncRedisCache:
+        return AsyncRedisCache(self.client)
+
+    @override
+    def get_hishel_storage(self) -> NoReturn:
+        raise CacheUnsupportedError(
+            "Async redis cache strategy does not support sync usage"
+        )
+
+    @override
+    def get_async_hishel_storage(self) -> AsyncBaseStorage:
+        return AsyncRedisStorage(client=self.client)

githubkit/exception.py

@@ -14,6 +14,10 @@
 class GitHubException(Exception): ...
 
 
+class CacheUnsupportedError(GitHubException):
+    """Unsupported Cache Usage Error"""
+
+
 class AuthCredentialError(GitHubException):
     """Auth Credential Error"""
 

poetry.lock

@@ -22,6 +22,7 @@ PyJWT = { version = "^2.4.0", extras = ["crypto"], optional = true }
 
 [tool.poetry.group.dev.dependencies]
 ruff = "^0.7.0"
+redis = "^5.2.0"
 isort = "^5.13.2"
 Jinja2 = "^3.1.2"
 nonemoji = "^0.1.2"