feat: add support of valkey

Author: santoshvandari

CHANGELOG.md

@@ -10,6 +10,10 @@ This project uses [*towncrier*](https://towncrier.readthedocs.io/) and the chang
 
 ## 0.2
 
+### 0.2.2
+- Valkey backend support
+- Example for Valkey backend
+
 ### 0.2.1
 - Fix picklecoder
 - Fix connection failure transparency and add logging

examples/valkey/Readme.md

@@ -0,0 +1,47 @@
+# Valkey Backend Example
+
+This example demonstrates using FastAPI-Cache with Valkey as the backend.
+
+## Prerequisites
+
+1. Install Valkey:
+   ```bash
+   # Using Docker
+   docker run -d -p 6379:6379 valkey/valkey:latest
+   
+   # Or install locally
+   # See: https://valkey.io/download/
+   ```
+
+2. Install dependencies:
+   ```bash
+   poetry install
+   # or
+   pip install fastapi-cache2[valkey]
+   ```
+
+## Running the Example
+
+```bash
+cd examples/valkey
+fastapi dev main.py
+```
+
+## Endpoints
+
+- `GET /` - Cached endpoint (10s TTL)
+- `GET /clear` - Clear cache
+- `GET /date` - Get cached date
+- `GET /datetime` - Get cached datetime
+- `GET /blocking` - Sync cached endpoint
+- `GET /html` - Cached HTML response
+- `GET /cache_response_obj` - Cached JSON response
+
+## Configuration
+
+The example uses these Valkey settings:
+- Host: localhost
+- Port: 6379
+- DB: 0
+- decode_responses: False (required for pickle coder)
+```

examples/valkey/main.py

@@ -10,22 +10,38 @@
 from fastapi.staticfiles import StaticFiles
 from fastapi.templating import Jinja2Templates
 from fastapi_cache import FastAPICache
-from fastapi_cache.backends.redis import RedisBackend
+from fastapi_cache.backends.valkey import ValkeyBackend
 from fastapi_cache.coder import PickleCoder
 from fastapi_cache.decorator import cache
 from starlette.requests import Request
 from starlette.responses import JSONResponse, Response
 
-import redis.asyncio as redis
-from redis.asyncio.connection import ConnectionPool
+from valkey.asyncio import Valkey
 
 
 @asynccontextmanager
 async def lifespan(_: FastAPI) -> AsyncIterator[None]:
-    pool = ConnectionPool.from_url(url="redis://redis")
-    r = redis.Redis(connection_pool=pool)
-    FastAPICache.init(RedisBackend(r), prefix="fastapi-cache")
+    client = Valkey(
+        host="localhost",
+        port=6379,
+        db=0,
+        decode_responses=False,      
+    )
+    
+    # Test the connection
+    try:
+        await client.ping()
+        print(f"✓ Connected to Valkey at localhost:6379")
+    except Exception as e:
+        print(f"✗ Failed to connect to Valkey: {e}")
+        raise
+
+    FastAPICache.init(ValkeyBackend(client), prefix="fastapi-cache")
+
     yield
+    
+    print("Closing Valkey connection...")
+    await client.close()
 
 
 app = FastAPI(lifespan=lifespan)
@@ -63,10 +79,9 @@ async def get_data(request: Request, response: Response):
     return pendulum.today()
 
 
-# Note: This function MUST be sync to demonstrate fastapi-cache's correct handling,
-# i.e. running cached sync functions in threadpool just like FastAPI itself!
+# MUST be sync to verify threadpool + cache handling
 @app.get("/blocking")
-@cache(namespace="test", expire=10) # pyright: ignore[reportArgumentType]
+@cache(namespace="test", expire=10)  # pyright: ignore[reportArgumentType]
 def blocking():
     time.sleep(2)
     return {"ret": 42}
@@ -82,7 +97,9 @@ async def get_datetime(request: Request, response: Response):
 @app.get("/html", response_class=HTMLResponse)
 @cache(expire=60, namespace="html", coder=PickleCoder)
 async def cache_html(request: Request):
-    return templates.TemplateResponse("index.html", {"request": request, "ret": await get_ret()})
+    return templates.TemplateResponse(
+        "index.html", {"request": request, "ret": await get_ret()}
+    )
 
 
 @app.get("/cache_response_obj")
@@ -92,4 +109,4 @@ async def cache_response_obj():
 
 
 if __name__ == "__main__":
-    uvicorn.run("main:app", reload=True)
+    uvicorn.run("main:app", reload=True)

fastapi_cache/backends/valkey.py

@@ -13,21 +13,28 @@ def __init__(self, valkey: Union["Valkey[bytes]", "ValkeyCluster[bytes]"]):
 
     async def get_with_ttl(self, key: str) -> Tuple[int, Optional[bytes]]:
         async with self.valkey.pipeline(transaction=not self.is_cluster) as pipe:
-            # return await pipe.ttl(key).get(key).execute()
-            return await pipe.ttl(key).get(key).execute()
+            return await pipe.ttl(key).get(key).execute()  # type: ignore[union-attr,no-any-return]
 
     async def get(self, key: str) -> Optional[bytes]:
-        return await self.valkey.get(key)
+        return await self.valkey.get(key)  # type: ignore[union-attr]
 
     async def set(self, key: str, value: bytes, expire: Optional[int] = None) -> None:
-        await self.valkey.set(key, value, ex=expire)
+        await self.valkey.set(key, value, ex=expire)  # type: ignore[union-attr]
 
     async def clear(self, namespace: Optional[str] = None, key: Optional[str] = None) -> int:
         if namespace:
-            lua = f"for i, name in ipairs(valkey.call('KEYS', '{namespace}:*')) do valkey.call('DEL', name); end"
-            return await self.valkey.eval(lua, numkeys=0)
-
+            cursor = 0
+            deleted = 0
+            pattern = f"{namespace}:*"
+            
+            while True:
+                cursor, keys = await self.valkey.scan(cursor, match=pattern, count=100)  # type: ignore[union-attr]
+                if keys:
+                    deleted += await self.valkey.delete(*keys)  # type: ignore[union-attr]
+                if cursor == 0:
+                    break
+            
+            return deleted
         elif key:
-            return await self.valkey.delete(key)
-
-        return 0
+            return await self.valkey.delete(key)  # type: ignore[union-attr]
+        return 0

pyproject.toml

@@ -24,7 +24,7 @@ pendulum = "^3.0.0"
 aiomcache = { version = "^0.8.2", optional = true }
 aiobotocore = {version = "^2.13.1", optional = true}
 redis = {version = "^5.0.8", extras = ["redis"]}
-valkey = "^6.1.1"
+valkey = { version = "^6.0.0", optional = true }
 
 [tool.poetry.group.linting]
 optional = true
@@ -53,8 +53,8 @@ twine = { version = "^4.0.2", python = "^3.10" }
 [tool.poetry.extras]
 redis = ["redis"]
 memcache = ["aiomcache"]
-dynamodb = ["aiobotocore"]
-all = ["redis", "aiomcache", "aiobotocore"]
+valkey = ["valkey"]
+all = ["redis", "aiomcache", "valkey"]
 
 [tool.mypy]
 files = ["."]