fastapi-cachekit 0.1.5__tar.gz → 0.2.0__tar.gz

{fastapi_cachekit-0.1.5/fastapi_cachekit.egg-info → fastapi_cachekit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-cachekit
-Version: 0.1.5
+Version: 0.2.0
 Summary: High-performance caching solution for FastAPI applications
 Author-email: Bijay Nayak <bijay6779@gmail.com>
 License-Expression: MIT
@@ -18,6 +18,7 @@ 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: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content

{fastapi_cachekit-0.1.5 → fastapi_cachekit-0.2.0}/fast_cache/__init__.py

@@ -1,6 +1,10 @@
+from importlib.metadata import version
+
 from .integration import FastAPICache
 from .backends.backend import CacheBackend
 
+__version__ = version("fastapi-cachekit")
+
 from .backends.redis import RedisBackend
 from .backends.memory import InMemoryBackend
 from .backends.postgres import PostgresBackend

{fastapi_cachekit-0.1.5 → fastapi_cachekit-0.2.0}/fast_cache/backends/backend.py

@@ -12,28 +12,30 @@ class CacheBackend(ABC):
     """
 
     @abstractmethod
-    async def aget(self, key: str) -> Optional[Any]:
+    async def aget(self, key: str, default: Any = None) -> Any:
         """
         Asynchronously retrieve a value from the cache.
 
         Args:
             key (str): The key to retrieve.
+            default (Any): Value to return if key is not found. Defaults to None.
 
         Returns:
-            Optional[Any]: The cached value, or None if not found.
+            Any: The cached value, or default if not found.
         """
         pass
 
     @abstractmethod
-    def get(self, key: str) -> Optional[Any]:
+    def get(self, key: str, default: Any = None) -> Any:
         """
         Synchronously retrieve a value from the cache.
 
         Args:
             key (str): The key to retrieve.
+            default (Any): Value to return if key is not found. Defaults to None.
 
         Returns:
-            Optional[Any]: The cached value, or None if not found.
+            Any: The cached value, or default if not found.
         """
         pass
 

{fastapi_cachekit-0.1.5 → fastapi_cachekit-0.2.0}/fast_cache/backends/dynamodb.py

@@ -1,4 +1,6 @@
+import asyncio
 import hashlib
+import logging
 from typing import Any, Optional, Union
 from datetime import timedelta
 import pickle
@@ -6,6 +8,8 @@ import time
 
 from .backend import CacheBackend
 
+logger = logging.getLogger(__name__)
+
 
 class DynamoDBBackend(CacheBackend):
     """
@@ -79,23 +83,32 @@ class DynamoDBBackend(CacheBackend):
         self._async_resource = None
         self._async_table = None
         self._async_session = aioboto3.Session()
+        self._async_table_lock = asyncio.Lock()
 
         # Create table if requested
         if create_table:
             self._ensure_table_exists()
 
     async def _get_async_table(self):
-        if self._async_table is None:
-            # Create the resource context
+        if self._async_table is not None:
+            return self._async_table
+        async with self._async_table_lock:
+            if self._async_table is not None:
+                return self._async_table
+            # Create the resource context manager
             self._async_resource = self._async_session.resource(
                 "dynamodb", **self._connection_params
             )
 
-            # Enter the context and get the actual resource
-            actual_resource = await self._async_resource.__aenter__()
-
-            # Create the table from the actual resource
-            self._async_table = await actual_resource.Table(self._table_name)
+            # Enter the context and get the actual resource,
+            # ensuring cleanup on failure to prevent leaks
+            try:
+                actual_resource = await self._async_resource.__aenter__()
+                self._async_table = await actual_resource.Table(self._table_name)
+            except BaseException:
+                await self._async_resource.__aexit__(None, None, None)
+                self._async_resource = None
+                raise
 
         return self._async_table
 
@@ -233,60 +246,64 @@ class DynamoDBBackend(CacheBackend):
 
         return item
 
-    def get(self, key: str) -> Optional[Any]:
+    def get(self, key: str, default: Any = None) -> Any:
         """
         Synchronously retrieve a value from the cache.
 
         Args:
             key (str): The key to retrieve.
+            default (Any): Value to return if key is not found. Defaults to None.
 
         Returns:
-            Optional[Any]: The cached value, or None if not found.
+            Any: The cached value, or default if not found.
         """
         try:
             response = self._sync_table.get_item(Key={"cache_key": self._make_key(key)})
 
             if "Item" not in response:
-                return None
+                return default
 
             item = response["Item"]
 
             # Check if item has expired and delete if so
             if self._is_expired(item):
                 self.delete(key)
-                return None
+                return default
             value = self._deserialize_value(item["value"])
             return value
-        except Exception:
-            return None
+        except Exception as e:
+            logger.warning("Cache get failed: %s", e)
+            return default
 
-    async def aget(self, key: str) -> Optional[Any]:
+    async def aget(self, key: str, default: Any = None) -> Any:
         """
         Asynchronously retrieve a value from the cache.
 
         Args:
             key (str): The key to retrieve.
+            default (Any): Value to return if key is not found. Defaults to None.
 
         Returns:
-            Optional[Any]: The cached value, or None if not found.
+            Any: The cached value, or default if not found.
         """
         try:
             table = await self._get_async_table()
             response = await table.get_item(Key={"cache_key": self._make_key(key)})
 
             if "Item" not in response:
-                return None
+                return default
 
             item = response["Item"]
 
             # Check if item has expired and delete if so
             if self._is_expired(item):
                 await self.adelete(key)
-                return None
+                return default
 
             return self._deserialize_value(item["value"])
-        except Exception:
-            return None
+        except Exception as e:
+            logger.warning("Cache aget failed: %s", e)
+            return default
 
     def set(
         self, key: str, value: Any, expire: Optional[Union[int, timedelta]] = None
@@ -302,8 +319,8 @@ class DynamoDBBackend(CacheBackend):
         try:
             item = self._build_item(key, value, expire)
             self._sync_table.put_item(Item=item)
-        except Exception:
-            pass
+        except Exception as e:
+            logger.warning("Cache set failed: %s", e)
 
     async def aset(
         self, key: str, value: Any, expire: Optional[Union[int, timedelta]] = None
@@ -320,8 +337,8 @@ class DynamoDBBackend(CacheBackend):
             table = await self._get_async_table()
             item = self._build_item(key, value, expire)
             await table.put_item(Item=item)
-        except Exception:
-            pass
+        except Exception as e:
+            logger.warning("Cache aset failed: %s", e)
 
     def delete(self, key: str) -> None:
         """
@@ -332,8 +349,8 @@ class DynamoDBBackend(CacheBackend):
         """
         try:
             self._sync_table.delete_item(Key={"cache_key": self._make_key(key)})
-        except Exception:
-            pass
+        except Exception as e:
+            logger.warning("Cache delete failed: %s", e)
 
     async def adelete(self, key: str) -> None:
         """
@@ -345,8 +362,8 @@ class DynamoDBBackend(CacheBackend):
         try:
             table = await self._get_async_table()
             await table.delete_item(Key={"cache_key": self._make_key(key)})
-        except Exception:
-            pass
+        except Exception as e:
+            logger.warning("Cache adelete failed: %s", e)
 
     def has(self, key: str) -> bool:
         """
@@ -376,7 +393,8 @@ class DynamoDBBackend(CacheBackend):
                 return False
 
             return True
-        except Exception:
+        except Exception as e:
+            logger.warning("Cache has failed: %s", e)
             return False
 
     async def ahas(self, key: str) -> bool:
@@ -408,7 +426,8 @@ class DynamoDBBackend(CacheBackend):
                 return False
 
             return True
-        except Exception:
+        except Exception as e:
+            logger.warning("Cache ahas failed: %s", e)
             return False
 
     def clear(self) -> None:
@@ -443,8 +462,8 @@ class DynamoDBBackend(CacheBackend):
                         for item in response["Items"]:
                             batch.delete_item(Key={"cache_key": item["cache_key"]})
 
-        except Exception:
-            pass
+        except Exception as e:
+            logger.warning("Cache clear failed: %s", e)
 
     async def aclear(self) -> None:
         """
@@ -482,8 +501,8 @@ class DynamoDBBackend(CacheBackend):
                                 Key={"cache_key": item["cache_key"]}
                             )
 
-        except Exception:
-            pass
+        except Exception as e:
+            logger.warning("Cache aclear failed: %s", e)
 
     async def close(self) -> None:
         """

{fastapi_cachekit-0.1.5 → fastapi_cachekit-0.2.0}/fast_cache/backends/google_firestore.py

@@ -148,18 +148,19 @@ class FirestoreBackend(CacheBackend):
         """
         return expires_at is not None and expires_at < time.time()
 
-    def get(self, key: str) -> Optional[Any]:
+    def get(self, key: str, default: Any = None) -> Any:
         """
         Synchronously retrieves a value from the cache by key.
 
-        If the key does not exist or the entry has expired, returns None. If the
+        If the key does not exist or the entry has expired, returns default. If the
         entry is expired, it is not automatically deleted.
 
         Args:
             key (str): The cache key to retrieve.
+            default (Any): Value to return if key is not found. Defaults to None.
 
         Returns:
-            Optional[Any]: The cached Python object, or None if not found or expired.
+            Any: The cached Python object, or default if not found or expired.
 
         Notes:
             - The value is deserialized using pickle.
@@ -176,8 +177,8 @@ class FirestoreBackend(CacheBackend):
                 try:
                     return pickle.loads(data["value"])
                 except (pickle.UnpicklingError, KeyError):
-                    return None
-        return None
+                    return default
+        return default
 
     def set(
         self, key: str, value: Any, expire: Optional[Union[int, timedelta]] = None
@@ -268,18 +269,19 @@ class FirestoreBackend(CacheBackend):
             return not self._is_expired(data.get("expires_at"))
         return False
 
-    async def aget(self, key: str) -> Optional[Any]:
+    async def aget(self, key: str, default: Any = None) -> Any:
         """
         Asynchronously retrieves a value from the cache by key.
 
-        If the key does not exist or the entry has expired, returns None. If the
+        If the key does not exist or the entry has expired, returns default. If the
         entry is expired, it is not automatically deleted.
 
         Args:
             key (str): The cache key to retrieve.
+            default (Any): Value to return if key is not found. Defaults to None.
 
         Returns:
-            Optional[Any]: The cached Python object, or None if not found or expired.
+            Any: The cached Python object, or default if not found or expired.
 
         Notes:
             - The value is deserialized using pickle.
@@ -296,9 +298,8 @@ class FirestoreBackend(CacheBackend):
                 try:
                     return pickle.loads(data["value"])
                 except (pickle.UnpicklingError, KeyError):
-                    # Handle potential deserialization errors or missing value field
-                    return None
-        return None
+                    return default
+        return default
 
     async def aset(
         self, key: str, value: Any, expire: Optional[Union[int, timedelta]] = None
@@ -499,7 +500,7 @@ class FirestoreBackend(CacheBackend):
             count += 1
             if count == 500:
                 batch.commit()
-                batch = self._async_db.batch()
+                batch = self._sync_db.batch()
                 count = 0
         if count > 0:
             batch.commit()

{fastapi_cachekit-0.1.5 → fastapi_cachekit-0.2.0}/fast_cache/backends/memcached.py

@@ -1,8 +1,11 @@
+import logging
 import pickle
 from typing import Any, Optional, Union
 from datetime import timedelta
 from .backend import CacheBackend
 
+logger = logging.getLogger(__name__)
+
 
 class MemcachedBackend(CacheBackend):
     """
@@ -80,17 +83,18 @@ class MemcachedBackend(CacheBackend):
         """
         return f"{self._namespace}:{key}".encode()
 
-    def get(self, key: str) -> Optional[Any]:
+    def get(self, key: str, default: Any = None) -> Any:
         """
         Synchronously retrieves a value from the cache by key.
 
-        If the key does not exist, returns None.
+        If the key does not exist, returns default.
 
         Args:
             key (str): The cache key to retrieve.
+            default (Any): Value to return if key is not found. Defaults to None.
 
         Returns:
-            Optional[Any]: The cached Python object, or None if not found.
+            Any: The cached Python object, or default if not found.
 
         Notes:
             - The value is deserialized using pickle.
@@ -99,9 +103,10 @@ class MemcachedBackend(CacheBackend):
         """
         try:
             value = self._sync_client.get(self._make_key(key))
-            return pickle.loads(value) if value else None
-        except Exception:
-            return None
+            return pickle.loads(value) if value else default
+        except Exception as e:
+            logger.warning("Cache get failed: %s", e)
+            return default
 
     def set(
         self, key: str, value: Any, expire: Optional[Union[int, timedelta]] = None
@@ -134,8 +139,8 @@ class MemcachedBackend(CacheBackend):
             self._sync_client.set(
                 self._make_key(key), pickle.dumps(value), expire=exptime
             )
-        except Exception:
-            pass
+        except Exception as e:
+            logger.warning("Cache set failed: %s", e)
 
     def delete(self, key: str) -> None:
         """
@@ -152,8 +157,8 @@ class MemcachedBackend(CacheBackend):
         """
         try:
             self._sync_client.delete(self._make_key(key))
-        except Exception:
-            pass
+        except Exception as e:
+            logger.warning("Cache delete failed: %s", e)
 
     def clear(self) -> None:
         """
@@ -170,8 +175,8 @@ class MemcachedBackend(CacheBackend):
 
         try:
             self._sync_client.flush_all()
-        except Exception:
-            pass
+        except Exception as e:
+            logger.warning("Cache clear failed: %s", e)
 
     def has(self, key: str) -> bool:
         """
@@ -189,20 +194,22 @@ class MemcachedBackend(CacheBackend):
         """
         try:
             return self._sync_client.get(self._make_key(key)) is not None
-        except Exception:
+        except Exception as e:
+            logger.warning("Cache has failed: %s", e)
             return False
 
-    async def aget(self, key: str) -> Optional[Any]:
+    async def aget(self, key: str, default: Any = None) -> Any:
         """
         Asynchronously retrieves a value from the cache by key.
 
-        If the key does not exist, returns None.
+        If the key does not exist, returns default.
 
         Args:
             key (str): The cache key to retrieve.
+            default (Any): Value to return if key is not found. Defaults to None.
 
         Returns:
-            Optional[Any]: The cached Python object, or None if not found.
+            Any: The cached Python object, or default if not found.
 
         Notes:
             - The value is deserialized using pickle.
@@ -211,9 +218,10 @@ class MemcachedBackend(CacheBackend):
         """
         try:
             value = await self._async_client.get(self._make_key(key))
-            return pickle.loads(value) if value else None
-        except Exception:
-            return None
+            return pickle.loads(value) if value else default
+        except Exception as e:
+            logger.warning("Cache aget failed: %s", e)
+            return default
 
     async def aset(
         self, key: str, value: Any, expire: Optional[Union[int, timedelta]] = None
@@ -246,8 +254,8 @@ class MemcachedBackend(CacheBackend):
             await self._async_client.set(
                 self._make_key(key), pickle.dumps(value), exptime=exptime
             )
-        except Exception:
-            pass
+        except Exception as e:
+            logger.warning("Cache aset failed: %s", e)
 
     async def adelete(self, key: str) -> None:
         """
@@ -264,8 +272,8 @@ class MemcachedBackend(CacheBackend):
         """
         try:
             await self._async_client.delete(self._make_key(key))
-        except Exception:
-            pass
+        except Exception as e:
+            logger.warning("Cache adelete failed: %s", e)
 
     async def aclear(self) -> None:
         """
@@ -281,8 +289,8 @@ class MemcachedBackend(CacheBackend):
         """
         try:
             await self._async_client.flush_all()
-        except Exception:
-            pass
+        except Exception as e:
+            logger.warning("Cache aclear failed: %s", e)
 
     async def ahas(self, key: str) -> bool:
         """
@@ -301,7 +309,8 @@ class MemcachedBackend(CacheBackend):
         try:
             value = await self._async_client.get(self._make_key(key))
             return value is not None
-        except Exception:
+        except Exception as e:
+            logger.warning("Cache ahas failed: %s", e)
             return False
 
     async def close(self) -> None:
@@ -318,5 +327,5 @@ class MemcachedBackend(CacheBackend):
         try:
             await self._async_client.close()
             self._sync_client.close()
-        except Exception:
-            pass
+        except Exception as e:
+            logger.warning("Cache close failed: %s", e)

{fastapi_cachekit-0.1.5 → fastapi_cachekit-0.2.0}/fast_cache/backends/memory.py

@@ -123,15 +123,14 @@ class InMemoryBackend(CacheBackend):
             - Only entries with a non-null expiration time and an expiration
               time earlier than the current time are deleted.
         """
-        while True:
-            now = time.monotonic()
-            keys_to_delete = [
-                k
-                for k, (_, exp) in list(self._cache.items())
-                if exp is not None and now > exp
-            ]
-            for k in keys_to_delete:
-                self._cache.pop(k, None)
+        now = time.monotonic()
+        keys_to_delete = [
+            k
+            for k, (_, exp) in list(self._cache.items())
+            if exp is not None and now > exp
+        ]
+        for k in keys_to_delete:
+            self._cache.pop(k, None)
 
     def _make_key(self, key: str) -> str:
         """
@@ -206,19 +205,20 @@ class InMemoryBackend(CacheBackend):
             while len(self._cache) > self._max_size:
                 self._cache.popitem(last=False)  # Remove oldest (LRU)
 
-    def get(self, key: str) -> Optional[Any]:
+    def get(self, key: str, default: Any = None) -> Any:
         """
         Synchronously retrieves a value from the cache by key.
 
-        If the key does not exist or the entry has expired, returns None. If the
+        If the key does not exist or the entry has expired, returns default. If the
         entry is expired, it is deleted from the cache (lazy deletion). Accessing
         an item moves it to the end of the LRU order.
 
         Args:
             key (str): The cache key to retrieve.
+            default (Any): Value to return if key is not found. Defaults to None.
 
         Returns:
-            Optional[Any]: The cached Python object, or None if not found or expired.
+            Any: The cached Python object, or default if not found or expired.
 
         Notes:
             - Thread-safe.
@@ -234,7 +234,7 @@ class InMemoryBackend(CacheBackend):
                     self._cache.move_to_end(k)
                     return value
                 self._cache.pop(k, None)
-            return None
+            return default
 
     def set(
         self, key: str, value: Any, expire: Optional[Union[int, timedelta]] = None
@@ -326,19 +326,20 @@ class InMemoryBackend(CacheBackend):
                 self._cache.pop(k, None)
             return False
 
-    async def aget(self, key: str) -> Optional[Any]:
+    async def aget(self, key: str, default: Any = None) -> Any:
         """
         Asynchronously retrieves a value from the cache by key.
 
-        If the key does not exist or the entry has expired, returns None. If the
+        If the key does not exist or the entry has expired, returns default. If the
         entry is expired, it is deleted from the cache (lazy deletion). Accessing
         an item moves it to the end of the LRU order.
 
         Args:
             key (str): The cache key to retrieve.
+            default (Any): Value to return if key is not found. Defaults to None.
 
         Returns:
-            Optional[Any]: The cached Python object, or None if not found or expired.
+            Any: The cached Python object, or default if not found or expired.
 
         Notes:
             - Asyncio-safe.
@@ -354,7 +355,7 @@ class InMemoryBackend(CacheBackend):
                     self._cache.move_to_end(k)
                     return value
                 self._cache.pop(k, None)
-            return None
+            return default
 
     async def aset(
         self, key: str, value: Any, expire: Optional[Union[int, timedelta]] = None
@@ -458,4 +459,4 @@ class InMemoryBackend(CacheBackend):
             - The background cleanup scheduler is stopped.
         """
         self._stop_cleanup_scheduler()
-        self._cache = None
+        self._cache.clear()

{fastapi_cachekit-0.1.5 → fastapi_cachekit-0.2.0}/fast_cache/backends/mongodb.py

@@ -61,23 +61,24 @@ class MongoDBBackend(CacheBackend):
         """
         return f"{self._namespace}:{key}"
 
-    def get(self, key: str) -> Optional[Any]:
+    def get(self, key: str, default: Any = None) -> Any:
         """
         Synchronously retrieve a value from the cache.
 
         Args:
             key (str): The cache key.
+            default (Any): Value to return if key is not found. Defaults to None.
 
         Returns:
-            Optional[Any]: The cached value, or None if not found or expired.
+            Any: The cached value, or default if not found or expired.
         """
         doc = self._sync_collection.find_one({"_id": self._make_key(key)})
         if doc and (doc.get("expires_at", float("inf")) > time.time()):
             try:
                 return pickle.loads(doc["value"])
             except Exception:
-                return None
-        return None
+                return default
+        return default
 
     def set(
         self, key: str, value: Any, expire: Optional[Union[int, timedelta]] = None
@@ -128,23 +129,24 @@ class MongoDBBackend(CacheBackend):
         doc = self._sync_collection.find_one({"_id": self._make_key(key)})
         return bool(doc and (doc.get("expires_at", float("inf")) > time.time()))
 
-    async def aget(self, key: str) -> Optional[Any]:
+    async def aget(self, key: str, default: Any = None) -> Any:
         """
         Asynchronously retrieve a value from the cache.
 
         Args:
             key (str): The cache key.
+            default (Any): Value to return if key is not found. Defaults to None.
 
         Returns:
-            Optional[Any]: The cached value, or None if not found or expired.
+            Any: The cached value, or default if not found or expired.
         """
         doc = await self._async_collection.find_one({"_id": self._make_key(key)})
         if doc and (doc.get("expires_at", float("inf")) > time.time()):
             try:
                 return pickle.loads(doc["value"])
             except Exception:
-                return None
-        return None
+                return default
+        return default
 
     async def aset(
         self, key: str, value: Any, expire: Optional[Union[int, timedelta]] = None

{fastapi_cachekit-0.1.5 → fastapi_cachekit-0.2.0}/fast_cache/backends/postgres.py

@@ -1,3 +1,4 @@
+import asyncio
 import pickle
 import re
 import threading
@@ -91,6 +92,7 @@ class PostgresBackend(CacheBackend):
 
         self._scheduler = None
         self._scheduler_lock = threading.Lock()
+        self._async_pool_lock = asyncio.Lock()
 
         if self._auto_cleanup:
             self._start_cleanup_scheduler()
@@ -236,18 +238,19 @@ class PostgresBackend(CacheBackend):
                 )
                 conn.commit()
 
-    def get(self, key: str) -> Optional[Any]:
+    def get(self, key: str, default: Any = None) -> Any:
         """
         Retrieves a value from the cache by key.
 
-        If the key does not exist or the entry has expired, returns None. If the
+        If the key does not exist or the entry has expired, returns default. If the
         entry is expired, it is deleted from the cache (lazy deletion).
 
         Args:
             key (str): The cache key to retrieve.
+            default (Any): Value to return if key is not found. Defaults to None.
 
         Returns:
-            Optional[Any]: The cached Python object, or None if not found or expired.
+            Any: The cached Python object, or default if not found or expired.
 
         Notes:
             - The value is deserialized using pickle.
@@ -261,11 +264,11 @@ class PostgresBackend(CacheBackend):
                 )
                 row = cur.fetchone()
                 if not row:
-                    return None
+                    return default
                 value, expire_at = row
                 if self._is_expired(expire_at):
                     self.delete(key)  # Lazy delete
-                    return None
+                    return default
                 return pickle.loads(value)
 
     def delete(self, key: str) -> None:
@@ -371,18 +374,19 @@ class PostgresBackend(CacheBackend):
                 )
                 await conn.commit()
 
-    async def aget(self, key: str) -> Optional[Any]:
+    async def aget(self, key: str, default: Any = None) -> Any:
         """
         Asynchronously retrieves a value from the cache by key.
 
-        If the key does not exist or the entry has expired, returns None. If the
+        If the key does not exist or the entry has expired, returns default. If the
         entry is expired, it is deleted from the cache (lazy deletion).
 
         Args:
             key (str): The cache key to retrieve.
+            default (Any): Value to return if key is not found. Defaults to None.
 
         Returns:
-            Optional[Any]: The cached Python object, or None if not found or expired.
+            Any: The cached Python object, or default if not found or expired.
 
         Notes:
             - Uses the asynchronous connection pool.
@@ -398,11 +402,11 @@ class PostgresBackend(CacheBackend):
                 )
                 row = await cur.fetchone()
                 if not row:
-                    return None
+                    return default
                 value, expire_at = row
                 if self._is_expired(expire_at):
                     await self.adelete(key)  # Lazy delete
-                    return None
+                    return default
                 return pickle.loads(value)
 
     async def adelete(self, key: str) -> None:
@@ -537,10 +541,15 @@ class PostgresBackend(CacheBackend):
         Ensures that the asynchronous connection pool is open before use.
 
         If the pool is not already open, it is opened asynchronously.
+        Uses a lock to prevent concurrent coroutines from racing to open
+        the pool simultaneously.
 
         Notes:
             - Used internally by all asynchronous methods.
             - Prevents errors from using a closed or uninitialized pool.
         """
-        if not self._async_pool._opened:
-            await self._async_pool.open()
+        if self._async_pool._opened:
+            return
+        async with self._async_pool_lock:
+            if not self._async_pool._opened:
+                await self._async_pool.open()

{fastapi_cachekit-0.1.5 → fastapi_cachekit-0.2.0}/fast_cache/backends/redis.py

@@ -1,9 +1,25 @@
+import asyncio
+import logging
+import time
+import uuid
 from typing import Any, Optional, Union
 from datetime import timedelta
 import pickle
 
 from .backend import CacheBackend
 
+logger = logging.getLogger(__name__)
+
+# Atomic unlock: only delete if the caller's token still matches.
+# Prevents releasing a lock that expired and was re-acquired by another process.
+_UNLOCK_SCRIPT = """
+if redis.call("get", KEYS[1]) == ARGV[1] then
+    return redis.call("del", KEYS[1])
+else
+    return 0
+end
+"""
+
 
 class RedisBackend(CacheBackend):
     """
@@ -93,37 +109,41 @@ class RedisBackend(CacheBackend):
                 break
         return keys
 
-    async def aget(self, key: str) -> Optional[Any]:
+    async def aget(self, key: str, default: Any = None) -> Any:
         """
         Asynchronously retrieve a value from the cache.
 
         Args:
             key (str): The key to retrieve.
+            default (Any): Value to return if key is not found. Defaults to None.
 
         Returns:
-            Optional[Any]: The cached value, or None if not found.
+            Any: The cached value, or default if not found.
         """
         try:
             result = await self._async_client.get(self._make_key(key))
-            return pickle.loads(result) if result else None
-        except Exception:
-            return None
+            return pickle.loads(result) if result else default
+        except Exception as e:
+            logger.warning("Cache aget failed: %s", e)
+            return default
 
-    def get(self, key: str) -> Optional[Any]:
+    def get(self, key: str, default: Any = None) -> Any:
         """
         Synchronously retrieve a value from the cache.
 
         Args:
             key (str): The key to retrieve.
+            default (Any): Value to return if key is not found. Defaults to None.
 
         Returns:
-            Optional[Any]: The cached value, or None if not found.
+            Any: The cached value, or default if not found.
         """
         try:
             result = self._sync_client.get(self._make_key(key))
-            return pickle.loads(result) if result else None
-        except Exception:
-            return None
+            return pickle.loads(result) if result else default
+        except Exception as e:
+            logger.warning("Cache get failed: %s", e)
+            return default
 
     async def aset(
         self, key: str, value: Any, expire: Optional[Union[int, timedelta]] = None
@@ -141,8 +161,8 @@ class RedisBackend(CacheBackend):
             await self._async_client.set(
                 self._make_key(key), pickle.dumps(value), ex=ex
             )
-        except Exception:
-            pass
+        except Exception as e:
+            logger.warning("Cache aset failed: %s", e)
 
     def set(
         self, key: str, value: Any, expire: Optional[Union[int, timedelta]] = None
@@ -158,8 +178,8 @@ class RedisBackend(CacheBackend):
         try:
             ex = expire.total_seconds() if isinstance(expire, timedelta) else expire
             self._sync_client.set(self._make_key(key), pickle.dumps(value), ex=ex)
-        except Exception:
-            pass
+        except Exception as e:
+            logger.warning("Cache set failed: %s", e)
 
     async def adelete(self, key: str) -> None:
         """
@@ -170,8 +190,8 @@ class RedisBackend(CacheBackend):
         """
         try:
             await self._async_client.delete(self._make_key(key))
-        except Exception:
-            pass
+        except Exception as e:
+            logger.warning("Cache adelete failed: %s", e)
 
     def delete(self, key: str) -> None:
         """
@@ -182,8 +202,8 @@ class RedisBackend(CacheBackend):
         """
         try:
             self._sync_client.delete(self._make_key(key))
-        except Exception:
-            pass
+        except Exception as e:
+            logger.warning("Cache delete failed: %s", e)
 
     async def aclear(self) -> None:
         """
@@ -193,8 +213,8 @@ class RedisBackend(CacheBackend):
             keys = await self._scan_keys()
             if keys:
                 await self._async_client.delete(*keys)
-        except Exception:
-            pass
+        except Exception as e:
+            logger.warning("Cache aclear failed: %s", e)
 
     def clear(self) -> None:
         """
@@ -212,8 +232,8 @@ class RedisBackend(CacheBackend):
                     self._sync_client.delete(*keys)
                 if cursor == 0:
                     break
-        except Exception:
-            pass
+        except Exception as e:
+            logger.warning("Cache clear failed: %s", e)
 
     async def ahas(self, key: str) -> bool:
         """
@@ -227,7 +247,8 @@ class RedisBackend(CacheBackend):
         """
         try:
             return await self._async_client.exists(self._make_key(key)) > 0
-        except Exception:
+        except Exception as e:
+            logger.warning("Cache ahas failed: %s", e)
             return False
 
     def has(self, key: str) -> bool:
@@ -242,7 +263,125 @@ class RedisBackend(CacheBackend):
         """
         try:
             return self._sync_client.exists(self._make_key(key)) > 0
-        except Exception:
+        except Exception as e:
+            logger.warning("Cache has failed: %s", e)
+            return False
+
+    def acquire_lock(
+        self,
+        key: str,
+        timeout: int = 30,
+        wait: float = 5.0,
+        poll_interval: float = 0.05,
+    ) -> Optional[str]:
+        """
+        Acquire a distributed lock for stampede protection.
+
+        Args:
+            key: Cache key to lock (lock suffix added internally).
+            timeout: Lock auto-expiry in seconds (deadlock protection).
+            wait: Max seconds to poll before giving up.
+            poll_interval: Sleep between poll attempts in seconds.
+
+        Returns:
+            A token string if acquired, None if the lock could not be
+            obtained within the wait period or on Redis failure.
+        """
+        lock_key = self._make_key(f"{key}:_lock")
+        token = uuid.uuid4().hex
+        deadline = time.monotonic() + wait
+
+        try:
+            while True:
+                if self._sync_client.set(lock_key, token, nx=True, ex=timeout):
+                    return token
+                if time.monotonic() >= deadline:
+                    return None
+                time.sleep(poll_interval)
+        except Exception as e:
+            logger.warning("Lock acquire failed: %s", e)
+            return None
+
+    def release_lock(self, key: str, token: str) -> bool:
+        """
+        Release a distributed lock only if the caller still owns it.
+
+        Uses a Lua script to atomically check the token and delete,
+        preventing release of a lock re-acquired by another process.
+
+        Args:
+            key: Cache key that was locked.
+            token: The token returned by acquire_lock.
+
+        Returns:
+            True if the lock was released, False otherwise.
+        """
+        lock_key = self._make_key(f"{key}:_lock")
+        try:
+            return self._sync_client.eval(_UNLOCK_SCRIPT, 1, lock_key, token) == 1
+        except Exception as e:
+            logger.warning("Lock release failed: %s", e)
+            return False
+
+    async def aacquire_lock(
+        self,
+        key: str,
+        timeout: int = 30,
+        wait: float = 5.0,
+        poll_interval: float = 0.05,
+    ) -> Optional[str]:
+        """
+        Asynchronously acquire a distributed lock for stampede protection.
+
+        Args:
+            key: Cache key to lock (lock suffix added internally).
+            timeout: Lock auto-expiry in seconds (deadlock protection).
+            wait: Max seconds to poll before giving up.
+            poll_interval: Sleep between poll attempts in seconds.
+
+        Returns:
+            A token string if acquired, None if the lock could not be
+            obtained within the wait period or on Redis failure.
+        """
+        lock_key = self._make_key(f"{key}:_lock")
+        token = uuid.uuid4().hex
+        deadline = time.monotonic() + wait
+
+        try:
+            while True:
+                if await self._async_client.set(
+                    lock_key, token, nx=True, ex=timeout
+                ):
+                    return token
+                if time.monotonic() >= deadline:
+                    return None
+                await asyncio.sleep(poll_interval)
+        except Exception as e:
+            logger.warning("Lock aacquire failed: %s", e)
+            return None
+
+    async def arelease_lock(self, key: str, token: str) -> bool:
+        """
+        Asynchronously release a distributed lock only if the caller still owns it.
+
+        Uses a Lua script to atomically check the token and delete,
+        preventing release of a lock re-acquired by another process.
+
+        Args:
+            key: Cache key that was locked.
+            token: The token returned by aacquire_lock.
+
+        Returns:
+            True if the lock was released, False otherwise.
+        """
+        lock_key = self._make_key(f"{key}:_lock")
+        try:
+            result = await self._async_client.eval(
+                _UNLOCK_SCRIPT, 1, lock_key, token
+            )
+            return result == 1
+        except Exception as e:
+            logger.warning("Lock arelease failed: %s", e)
             return False
 
     async def close(self) -> None:

{fastapi_cachekit-0.1.5 → fastapi_cachekit-0.2.0}/fast_cache/integration.py

@@ -6,6 +6,8 @@ import inspect
 from functools import wraps
 from .backends.backend import CacheBackend
 
+_CACHE_MISS = object()
+
 
 class FastAPICache:
     """
@@ -42,6 +44,9 @@ class FastAPICache:
         expire: Optional[Union[int, timedelta]] = None,
         key_builder: Optional[Callable[..., str]] = None,
         namespace: Optional[str] = None,
+        stampede_protection: bool = True,
+        lock_timeout: int = 30,
+        lock_wait: float = 5.0,
     ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
         """
         Decorator for caching function results.
@@ -50,6 +55,12 @@ class FastAPICache:
             expire (Optional[Union[int, timedelta]]): Expiration time in seconds or as a timedelta.
             key_builder (Optional[Callable[..., str]]): Custom function to build the cache key.
             namespace (Optional[str]): Optional namespace for the cache key.
+            stampede_protection (bool): Enable distributed lock to prevent thundering herd
+                on cache miss. Requires a backend that supports locking (e.g., Redis).
+                Silently skipped for backends without lock support. Defaults to True.
+            lock_timeout (int): Lock auto-expiry in seconds (deadlock protection). Defaults to 30.
+            lock_wait (float): Max seconds to wait for the lock before falling back
+                to a direct function call. Defaults to 5.0.
 
         Returns:
             Callable: A decorator that caches the function result.
@@ -89,6 +100,11 @@ class FastAPICache:
 
                 return key
 
+            def _backend_supports_locking() -> bool:
+                return self._backend is not None and hasattr(
+                    self._backend, "acquire_lock"
+                )
+
             @wraps(func)
             async def async_wrapper(*args, **kwargs) -> Any:
                 """
@@ -109,16 +125,46 @@ class FastAPICache:
                     return await func(*args, **kwargs)
 
                 cache_key = build_cache_key(*args, **kwargs)
+                effective_expire = expire or self._default_expire
 
-                # Try to get from cache
-                cached_value = await self._backend.aget(cache_key)
-                if cached_value is not None:
+                # Fast path: cache hit
+                cached_value = await self._backend.aget(
+                    cache_key, default=_CACHE_MISS
+                )
+                if cached_value is not _CACHE_MISS:
                     return cached_value
 
-                # Execute function and cache result
+                # Stampede protection: distributed lock
+                if stampede_protection and _backend_supports_locking():
+                    token = await self._backend.aacquire_lock(
+                        cache_key, timeout=lock_timeout, wait=lock_wait
+                    )
+
+                    if token is not None:
+                        # We are the lock holder — rebuild the value
+                        try:
+                            result = await func(*args, **kwargs)
+                            await self._backend.aset(
+                                cache_key, result, expire=effective_expire
+                            )
+                            return result
+                        finally:
+                            await self._backend.arelease_lock(cache_key, token)
+                    else:
+                        # Another process is rebuilding — check if it finished
+                        cached_value = await self._backend.aget(
+                            cache_key, default=_CACHE_MISS
+                        )
+                        if cached_value is not _CACHE_MISS:
+                            return cached_value
+
+                        # Still no value — fallback: call function directly
+                        return await func(*args, **kwargs)
+
+                # No stampede protection — original behavior
                 result = await func(*args, **kwargs)
                 await self._backend.aset(
-                    cache_key, result, expire=expire or self._default_expire
+                    cache_key, result, expire=effective_expire
                 )
                 return result
 
@@ -142,16 +188,46 @@ class FastAPICache:
                     return func(*args, **kwargs)
 
                 cache_key = build_cache_key(*args, **kwargs)
+                effective_expire = expire or self._default_expire
 
-                # Try to get from cache
-                cached_value = self._backend.get(cache_key)
-                if cached_value is not None:
+                # Fast path: cache hit
+                cached_value = self._backend.get(
+                    cache_key, default=_CACHE_MISS
+                )
+                if cached_value is not _CACHE_MISS:
                     return cached_value
 
-                # Execute function and cache result
+                # Stampede protection: distributed lock
+                if stampede_protection and _backend_supports_locking():
+                    token = self._backend.acquire_lock(
+                        cache_key, timeout=lock_timeout, wait=lock_wait
+                    )
+
+                    if token is not None:
+                        # We are the lock holder — rebuild the value
+                        try:
+                            result = func(*args, **kwargs)
+                            self._backend.set(
+                                cache_key, result, expire=effective_expire
+                            )
+                            return result
+                        finally:
+                            self._backend.release_lock(cache_key, token)
+                    else:
+                        # Another process is rebuilding — check if it finished
+                        cached_value = self._backend.get(
+                            cache_key, default=_CACHE_MISS
+                        )
+                        if cached_value is not _CACHE_MISS:
+                            return cached_value
+
+                        # Still no value — fallback: call function directly
+                        return func(*args, **kwargs)
+
+                # No stampede protection — original behavior
                 result = func(*args, **kwargs)
                 self._backend.set(
-                    cache_key, result, expire=expire or self._default_expire
+                    cache_key, result, expire=effective_expire
                 )
                 return result
 

{fastapi_cachekit-0.1.5 → fastapi_cachekit-0.2.0/fastapi_cachekit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-cachekit
-Version: 0.1.5
+Version: 0.2.0
 Summary: High-performance caching solution for FastAPI applications
 Author-email: Bijay Nayak <bijay6779@gmail.com>
 License-Expression: MIT
@@ -18,6 +18,7 @@ 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: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content

{fastapi_cachekit-0.1.5 → fastapi_cachekit-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-cachekit"
-version = "0.1.5"
+version = "0.2.0"
 description = "High-performance caching solution for FastAPI applications"
 readme = "README.md"
 license = "MIT"
@@ -19,6 +19,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Internet :: WWW/HTTP",
     "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
@@ -92,6 +93,7 @@ build-backend = "setuptools.build_meta"
 
 [dependency-groups]
 dev = [
+    {include-group = "all-backends"},
     "httpx>=0.28.1",
     "mkdocs-material>=9.6.14",
     "mkdocstrings[python]>=0.29.1",
@@ -105,3 +107,13 @@ dev = [
     "twine>=6.1.0",
     "uvicorn[standard]>=0.34.3",
 ]
+all-backends = [
+    "redis>=4.2.0",
+    "psycopg[pool]>=3.2.9",
+    "aiomcache>=0.8.1",
+    "pymemcache>=4.0.0",
+    "pymongo[snappy,gssapi,srv]>=4.6.0",
+    "google-cloud-firestore>=2.3.0",
+    "boto3>=1.10.0",
+    "aioboto3>=6.0.0",
+]