fastapi-cachekit 0.1.0__tar.gz

fastapi_cachekit-0.1.0/PKG-INFO

@@ -0,0 +1,289 @@
+Metadata-Version: 2.4
+Name: fastapi-cachekit
+Version: 0.1.0
+Summary: High-performance caching solution for FastAPI applications
+Author-email: Bijay Nayak <bijay6779@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/devbijay/fast-cache
+Project-URL: Documentation, https://github.com/devbijay/fast-cache#readme
+Project-URL: Repository, https://github.com/devbijay/fast-cache.git
+Project-URL: Issues, https://github.com/devbijay/fast-cache/issues
+Keywords: fastapi,cache,redis,async,python,starlette,asyncio
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.75.0
+Requires-Dist: uvicorn[standard]>=0.20.0
+Provides-Extra: redis
+Requires-Dist: redis>=4.2.0; extra == "redis"
+Provides-Extra: postgres
+Requires-Dist: psycopg[pool]>=3.2.9; extra == "postgres"
+Provides-Extra: memcached
+Requires-Dist: aiomcache>=0.8.1; extra == "memcached"
+Requires-Dist: pymemcache>=4.0.0; extra == "memcached"
+Provides-Extra: all
+Requires-Dist: redis>=4.2.0; extra == "all"
+Requires-Dist: psycopg[pool]>=3.2.9; extra == "all"
+Requires-Dist: aiomcache>=0.8.1; extra == "all"
+Requires-Dist: pymemcache>=4.0.0; extra == "all"
+
+# fastapi-cachekit
+
+A high-performance, flexible caching solution for FastAPI applications. fastapi-cachekit supports both synchronous and asynchronous operations with a clean API and multiple backend options.
+
+[![PyPI version](https://badge.fury.io/py/fastapi-cachekit.svg)](https://badge.fury.io/py/fastapi-cachekit)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/release/python-380/)
+[![Downloads](https://pepy.tech/badge/fastapi-cache)](https://pepy.tech/project/fastapi-cachekit)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- ✅ Full async/sync support for all operations
+- ✅ Redis backend with connection pooling
+- ✅ Function result caching with decorator syntax
+- ✅ FastAPI dependency injection support
+- ✅ Namespace support for isolating cache entries
+- ✅ Customizable key generation
+- ✅ Type hinting throughout the codebase
+- ✅ Expiration time support (seconds or timedelta)
+
+## 📦 Backends & Sync/Async Support
+
+| Backend            | Sync API | Async API | Install Extra         |
+|--------------------|:--------:|:---------:|----------------------|
+| `InMemoryBackend`  |   ✅     |    ✅     | _built-in_           |
+| `RedisBackend`     |   ✅     |    ✅     | `redis`              |
+| `PostgresBackend`  |   ✅     |    ✅     | `postgres`           |
+| `MemcachedBackend` |   ✅     |    ✅     | `memcached`          |
+
+---
+
+## 🛠️ Installation
+
+**Base (in-memory only):**
+```bash
+pip install fastapi-cachekit
+```
+
+**With Redis:**
+```bash
+pip install fastapi-cachekit[redis]
+```
+
+**With Postgres:**
+```bash
+pip install fastapi-cachekit[postgres]
+```
+
+**With Memcached:**
+```bash
+pip install fastapi-cachekit[memcached]
+```
+
+**All backends:**
+```bash
+pip install fastapi-cachekit[all]
+```
+
+
+## Quick Start
+
+```python
+from fastapi import FastAPI, Depends
+from fast_cache import cache, RedisBackend
+from typing import Annotated
+
+app = FastAPI()
+
+# Initialize cache with Redis backend
+cache.init_app(
+    app=app,
+    backend=RedisBackend(redis_url="redis://localhost:6379/0", namespace="myapp"),
+    default_expire=300  # 5 minutes default expiration
+)
+
+
+# Use function caching decorator
+@app.get("/items/{item_id}")
+@cache.cached(expire=60)  # Cache for 60 seconds
+async def read_item(item_id: int):
+    # Expensive operation simulation
+    return {"item_id": item_id, "name": f"Item {item_id}"}
+
+# Use cache backend directly with dependency injection
+@app.get("/manual-cache")
+async def manual_cache_example(cache_backend: Annotated[RedisBackend, Depends(cache.get_cache)]):
+    # Check if key exists
+    has_key = await cache_backend.ahas("my-key")
+
+    if not has_key:
+        # Set a value in the cache
+        await cache_backend.aset("my-key", {"data": "cached value"}, expire=30)
+        return {"cache_set": True}
+
+    # Get the value from cache
+    value = await cache_backend.aget("my-key")
+    return {"cached_value": value}
+```
+Now You Can use the cache from other Sub Routes by importing from
+```from fast_cache import cache```
+
+## Detailed Usage
+
+### Initializing the Cache
+
+Before using the cache, you need to initialize it with a backend:
+
+```python
+from fastapi import FastAPI
+from fast_cache import cache, RedisBackend
+from datetime import timedelta
+
+app = FastAPI()
+
+cache.init_app(
+    app=app,
+    backend=RedisBackend(
+        redis_url="redis://localhost:6379/0",
+        namespace="myapp",
+        max_connections=20
+    ),
+    default_expire=timedelta(minutes=5)
+)
+```
+
+### Method1: Caching a Function Result Using A Cache Decorator
+
+The `@cache.cached()` decorator is the simplest way to cache function results:
+
+```python
+from fast_cache import cache
+
+# Cache with default expiration time
+@cache.cached()
+def get_user_data(user_id: int):
+    # Expensive database query
+    return {"user_id": user_id, "name": "John Doe"}
+
+# Cache with custom namespace and expiration
+@cache.cached(namespace="users", expire=300)
+async def get_user_profile(user_id: int):
+    # Async expensive operation
+    return {"user_id": user_id, "profile": "..."}
+
+# Cache with custom key builder
+@cache.cached(key_builder=lambda user_id, **kwargs: f"user:{user_id}")
+def get_user_permissions(user_id: int):
+    # Complex permission calculation
+    return ["read", "write"]
+
+# Skip Cache for Specific Calls
+
+Sometimes you need to bypass the cache for certain requests:
+
+@cache.cached()
+async def get_weather(city: str, skip_cache: bool = False):
+    # Function will be called directly if skip_cache is True
+    return await fetch_weather_data(city)
+
+# Usage:
+weather = await get_weather("New York", skip_cache=True)  # Bypasses cache
+```
+
+
+### Method 2: Using Via Dependency Injection
+
+You can access the cache backend directly for more control:
+
+```python
+from fastapi import Depends
+from fast_cache import cache, CacheBackend
+from typing import Annotated
+
+@app.get("/api/data")
+async def get_data(cache_backend: Annotated[CacheBackend, Depends(cache.get_cache)]):
+    # Try to get from cache
+    cached_data = await cache_backend.aget("api:data")
+    if cached_data:
+        return cached_data
+
+    # Generate new data
+    data = await fetch_expensive_api_data()
+
+    # Store in cache for 1 hour
+    await cache_backend.aset("api:data", data, expire=3600)
+
+    return data
+```
+
+
+
+### Advanced: Implementing Custom Backends
+
+You can create your own cache backend by implementing the `CacheBackend` abstract class:
+
+```python
+from fast_cache.backends.backend import CacheBackend
+from typing import Any, Optional, Union
+from datetime import timedelta
+
+class MyCustomBackend(CacheBackend):
+    # Implement all required methods
+    async def aget(self, key: str) -> Any:
+        # Your implementation here
+        ...
+
+    def get(self, key: str) -> Any:
+        # Your implementation here
+        ...
+
+    # ... implement all other required methods
+```
+
+## API Reference
+
+### Cache Instance
+
+- `cache.init_app(app, backend, default_expire=None)` - Initialize cache with FastAPI app
+- `cache.get_cache()` - Get cache backend instance (for dependency injection)
+- `cache.cached(expire=None, key_builder=None, namespace=None)` - Caching decorator
+
+### CacheBackend Interface
+
+All backends implement these methods in both sync and async versions:
+
+- `get(key)` / `aget(key)` - Retrieve a value
+- `set(key, value, expire)` / `aset(key, value, expire)` - Store a value
+- `delete(key)` / `adelete(key)` - Delete a value
+- `clear()` / `aclear()` - Clear all values
+- `has(key)` / `ahas(key)` - Check if key exists
+
+### RedisBackend Configuration
+
+- `redis_url` - Redis connection string (required)
+- `namespace` - Key prefix (default: "fastapi-cache")
+- `pool_size` - Minimum pool connections (default: 10)
+- `max_connections` - Maximum pool connections (default: 20)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

fastapi_cachekit-0.1.0/README.md

@@ -0,0 +1,246 @@
+# fastapi-cachekit
+
+A high-performance, flexible caching solution for FastAPI applications. fastapi-cachekit supports both synchronous and asynchronous operations with a clean API and multiple backend options.
+
+[![PyPI version](https://badge.fury.io/py/fastapi-cachekit.svg)](https://badge.fury.io/py/fastapi-cachekit)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/release/python-380/)
+[![Downloads](https://pepy.tech/badge/fastapi-cache)](https://pepy.tech/project/fastapi-cachekit)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- ✅ Full async/sync support for all operations
+- ✅ Redis backend with connection pooling
+- ✅ Function result caching with decorator syntax
+- ✅ FastAPI dependency injection support
+- ✅ Namespace support for isolating cache entries
+- ✅ Customizable key generation
+- ✅ Type hinting throughout the codebase
+- ✅ Expiration time support (seconds or timedelta)
+
+## 📦 Backends & Sync/Async Support
+
+| Backend            | Sync API | Async API | Install Extra         |
+|--------------------|:--------:|:---------:|----------------------|
+| `InMemoryBackend`  |   ✅     |    ✅     | _built-in_           |
+| `RedisBackend`     |   ✅     |    ✅     | `redis`              |
+| `PostgresBackend`  |   ✅     |    ✅     | `postgres`           |
+| `MemcachedBackend` |   ✅     |    ✅     | `memcached`          |
+
+---
+
+## 🛠️ Installation
+
+**Base (in-memory only):**
+```bash
+pip install fastapi-cachekit
+```
+
+**With Redis:**
+```bash
+pip install fastapi-cachekit[redis]
+```
+
+**With Postgres:**
+```bash
+pip install fastapi-cachekit[postgres]
+```
+
+**With Memcached:**
+```bash
+pip install fastapi-cachekit[memcached]
+```
+
+**All backends:**
+```bash
+pip install fastapi-cachekit[all]
+```
+
+
+## Quick Start
+
+```python
+from fastapi import FastAPI, Depends
+from fast_cache import cache, RedisBackend
+from typing import Annotated
+
+app = FastAPI()
+
+# Initialize cache with Redis backend
+cache.init_app(
+    app=app,
+    backend=RedisBackend(redis_url="redis://localhost:6379/0", namespace="myapp"),
+    default_expire=300  # 5 minutes default expiration
+)
+
+
+# Use function caching decorator
+@app.get("/items/{item_id}")
+@cache.cached(expire=60)  # Cache for 60 seconds
+async def read_item(item_id: int):
+    # Expensive operation simulation
+    return {"item_id": item_id, "name": f"Item {item_id}"}
+
+# Use cache backend directly with dependency injection
+@app.get("/manual-cache")
+async def manual_cache_example(cache_backend: Annotated[RedisBackend, Depends(cache.get_cache)]):
+    # Check if key exists
+    has_key = await cache_backend.ahas("my-key")
+
+    if not has_key:
+        # Set a value in the cache
+        await cache_backend.aset("my-key", {"data": "cached value"}, expire=30)
+        return {"cache_set": True}
+
+    # Get the value from cache
+    value = await cache_backend.aget("my-key")
+    return {"cached_value": value}
+```
+Now You Can use the cache from other Sub Routes by importing from
+```from fast_cache import cache```
+
+## Detailed Usage
+
+### Initializing the Cache
+
+Before using the cache, you need to initialize it with a backend:
+
+```python
+from fastapi import FastAPI
+from fast_cache import cache, RedisBackend
+from datetime import timedelta
+
+app = FastAPI()
+
+cache.init_app(
+    app=app,
+    backend=RedisBackend(
+        redis_url="redis://localhost:6379/0",
+        namespace="myapp",
+        max_connections=20
+    ),
+    default_expire=timedelta(minutes=5)
+)
+```
+
+### Method1: Caching a Function Result Using A Cache Decorator
+
+The `@cache.cached()` decorator is the simplest way to cache function results:
+
+```python
+from fast_cache import cache
+
+# Cache with default expiration time
+@cache.cached()
+def get_user_data(user_id: int):
+    # Expensive database query
+    return {"user_id": user_id, "name": "John Doe"}
+
+# Cache with custom namespace and expiration
+@cache.cached(namespace="users", expire=300)
+async def get_user_profile(user_id: int):
+    # Async expensive operation
+    return {"user_id": user_id, "profile": "..."}
+
+# Cache with custom key builder
+@cache.cached(key_builder=lambda user_id, **kwargs: f"user:{user_id}")
+def get_user_permissions(user_id: int):
+    # Complex permission calculation
+    return ["read", "write"]
+
+# Skip Cache for Specific Calls
+
+Sometimes you need to bypass the cache for certain requests:
+
+@cache.cached()
+async def get_weather(city: str, skip_cache: bool = False):
+    # Function will be called directly if skip_cache is True
+    return await fetch_weather_data(city)
+
+# Usage:
+weather = await get_weather("New York", skip_cache=True)  # Bypasses cache
+```
+
+
+### Method 2: Using Via Dependency Injection
+
+You can access the cache backend directly for more control:
+
+```python
+from fastapi import Depends
+from fast_cache import cache, CacheBackend
+from typing import Annotated
+
+@app.get("/api/data")
+async def get_data(cache_backend: Annotated[CacheBackend, Depends(cache.get_cache)]):
+    # Try to get from cache
+    cached_data = await cache_backend.aget("api:data")
+    if cached_data:
+        return cached_data
+
+    # Generate new data
+    data = await fetch_expensive_api_data()
+
+    # Store in cache for 1 hour
+    await cache_backend.aset("api:data", data, expire=3600)
+
+    return data
+```
+
+
+
+### Advanced: Implementing Custom Backends
+
+You can create your own cache backend by implementing the `CacheBackend` abstract class:
+
+```python
+from fast_cache.backends.backend import CacheBackend
+from typing import Any, Optional, Union
+from datetime import timedelta
+
+class MyCustomBackend(CacheBackend):
+    # Implement all required methods
+    async def aget(self, key: str) -> Any:
+        # Your implementation here
+        ...
+
+    def get(self, key: str) -> Any:
+        # Your implementation here
+        ...
+
+    # ... implement all other required methods
+```
+
+## API Reference
+
+### Cache Instance
+
+- `cache.init_app(app, backend, default_expire=None)` - Initialize cache with FastAPI app
+- `cache.get_cache()` - Get cache backend instance (for dependency injection)
+- `cache.cached(expire=None, key_builder=None, namespace=None)` - Caching decorator
+
+### CacheBackend Interface
+
+All backends implement these methods in both sync and async versions:
+
+- `get(key)` / `aget(key)` - Retrieve a value
+- `set(key, value, expire)` / `aset(key, value, expire)` - Store a value
+- `delete(key)` / `adelete(key)` - Delete a value
+- `clear()` / `aclear()` - Clear all values
+- `has(key)` / `ahas(key)` - Check if key exists
+
+### RedisBackend Configuration
+
+- `redis_url` - Redis connection string (required)
+- `namespace` - Key prefix (default: "fastapi-cache")
+- `pool_size` - Minimum pool connections (default: 10)
+- `max_connections` - Maximum pool connections (default: 20)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

fastapi_cachekit-0.1.0/fast_cache/__init__.py

@@ -0,0 +1,13 @@
+from .integration import FastAPICache
+from .backends.backend import CacheBackend
+
+from .backends.redis import RedisBackend
+from .backends.memory import InMemoryBackend
+from .backends.postgres import PostgresBackend
+from .backends.memcached import MemcachedBackend
+
+__all__ = ["FastAPICache", "RedisBackend", "CacheBackend", "InMemoryBackend","PostgresBackend", "cache","MemcachedBackend" ]
+
+
+# Create global cache instance
+cache = FastAPICache()

fastapi_cachekit-0.1.0/fast_cache/backends/backend.py

@@ -0,0 +1,126 @@
+from abc import ABC, abstractmethod
+from typing import Any, Optional, Union
+from datetime import timedelta
+
+
+class CacheBackend(ABC):
+    """
+    Abstract base class for cache backends.
+
+    All cache backend implementations must inherit from this class and implement
+    both synchronous and asynchronous methods for cache operations.
+    """
+
+    @abstractmethod
+    async def aget(self, key: str) -> Optional[Any]:
+        """
+        Asynchronously retrieve a value from the cache.
+
+        Args:
+            key (str): The key to retrieve.
+
+        Returns:
+            Optional[Any]: The cached value, or None if not found.
+        """
+        pass
+
+    @abstractmethod
+    def get(self, key: str) -> Optional[Any]:
+        """
+        Synchronously retrieve a value from the cache.
+
+        Args:
+            key (str): The key to retrieve.
+
+        Returns:
+            Optional[Any]: The cached value, or None if not found.
+        """
+        pass
+
+    @abstractmethod
+    async def aset(
+        self, key: str, value: Any, expire: Optional[Union[int, timedelta]] = None
+    ) -> None:
+        """
+        Asynchronously set a value in the cache.
+
+        Args:
+            key (str): The key under which to store the value.
+            value (Any): The value to store.
+            expire (Optional[Union[int, timedelta]]): Expiration time in seconds or as timedelta.
+        """
+        pass
+
+    @abstractmethod
+    def set(
+        self, key: str, value: Any, expire: Optional[Union[int, timedelta]] = None
+    ) -> None:
+        """
+        Synchronously set a value in the cache.
+
+        Args:
+            key (str): The key under which to store the value.
+            value (Any): The value to store.
+            expire (Optional[Union[int, timedelta]]): Expiration time in seconds or as timedelta.
+        """
+        pass
+
+    @abstractmethod
+    async def adelete(self, key: str) -> None:
+        """
+        Asynchronously delete a value from the cache.
+
+        Args:
+            key (str): The key to delete.
+        """
+        pass
+
+    @abstractmethod
+    def delete(self, key: str) -> None:
+        """
+        Synchronously delete a value from the cache.
+
+        Args:
+            key (str): The key to delete.
+        """
+        pass
+
+    @abstractmethod
+    async def aclear(self) -> None:
+        """
+        Asynchronously clear all values from the cache.
+        """
+        pass
+
+    @abstractmethod
+    def clear(self) -> None:
+        """
+        Synchronously clear all values from the cache.
+        """
+        pass
+
+    @abstractmethod
+    async def ahas(self, key: str) -> bool:
+        """
+        Asynchronously check if a key exists in the cache.
+
+        Args:
+            key (str): The key to check.
+
+        Returns:
+            bool: True if the key exists, False otherwise.
+        """
+        pass
+
+    @abstractmethod
+    def has(self, key: str) -> bool:
+        """
+        Synchronously check if a key exists in the cache.
+
+        Args:
+            key (str): The key to check.
+
+        Returns:
+            bool: True if the key exists, False otherwise.
+        """
+        pass