fastapi-cachex 0.2.1__tar.gz → 0.2.3__tar.gz

{fastapi_cachex-0.2.1 → fastapi_cachex-0.2.3}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: fastapi-cachex
-Version: 0.2.1
+Version: 0.2.3
 Summary: A caching library for FastAPI with support for Cache-Control, ETag, and multiple backends.
 Keywords: fastapi,cache,etag,cache-control,redis,memcached,in-memory
-Author: Allen
-Author-email: Allen <s96016641@gmail.com>
+Author: allen0099
+Author-email: allen0099 <s96016641@gmail.com>
 License-Expression: Apache-2.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -20,6 +20,7 @@ Classifier: Framework :: FastAPI
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
 Requires-Dist: fastapi
+Requires-Dist: pydantic
 Requires-Dist: pymemcache ; extra == 'memcache'
 Requires-Dist: redis[hiredis] ; extra == 'redis'
 Requires-Dist: orjson ; extra == 'redis'
@@ -47,10 +48,11 @@ Description-Content-Type: text/markdown
 
 [English](README.md) | [繁體中文](docs/README.zh-TW.md)
 
-A high-performance caching extension for FastAPI, providing comprehensive HTTP caching support.
+A high-performance caching extension for FastAPI, providing comprehensive HTTP caching support and optional session management.
 
 ## Features
 
+### HTTP Caching
 - Support for HTTP caching headers
     - `Cache-Control`
     - `ETag`
@@ -62,6 +64,15 @@ A high-performance caching extension for FastAPI, providing comprehensive HTTP c
 - Complete Cache-Control directive implementation
 - Easy-to-use `@cache` decorator
 
+### Session Management (Optional Extension)
+- Secure session management with HMAC-SHA256 token signing
+- IP address and User-Agent binding (optional security features)
+- Header and bearer token support (API-first architecture)
+- Automatic session renewal (sliding expiration)
+- Flash messages for cross-request communication
+- Multiple backend support (Redis, Memcached, In-Memory)
+- Complete session lifecycle management (create, validate, refresh, invalidate)
+
 ### Cache-Control Directives
 
 | Directive                | Supported          | Description                                                                                             |
@@ -86,6 +97,12 @@ A high-performance caching extension for FastAPI, providing comprehensive HTTP c
 uv add fastapi-cachex
 ```
 
+### Development Installation
+
+```bash
+uv add git+https://github.com/allen0099/FastAPI-CacheX.git
+```
+
 ## Quick Start
 
 ```python
@@ -129,7 +146,7 @@ FastAPI-CacheX supports multiple caching backends. You can easily switch between
 Cache keys are generated in the following format to avoid collisions:
 
 ```
-{method}:{host}:{path}:{query_params}
+{method}|||{host}|||{path}|||{query_params}
 ```
 
 This ensures that:
@@ -236,6 +253,7 @@ async def expensive_operation():
 - [Cache Flow Explanation](docs/CACHE_FLOW.md)
 - [Development Guide](docs/DEVELOPMENT.md)
 - [Contributing Guidelines](docs/CONTRIBUTING.md)
+- [Session Management Guide](docs/SESSION.md) - Complete guide for session features
 
 ## License
 

{fastapi_cachex-0.2.1 → fastapi_cachex-0.2.3}/README.md

@@ -14,10 +14,11 @@
 
 [English](README.md) | [繁體中文](docs/README.zh-TW.md)
 
-A high-performance caching extension for FastAPI, providing comprehensive HTTP caching support.
+A high-performance caching extension for FastAPI, providing comprehensive HTTP caching support and optional session management.
 
 ## Features
 
+### HTTP Caching
 - Support for HTTP caching headers
     - `Cache-Control`
     - `ETag`
@@ -29,6 +30,15 @@ A high-performance caching extension for FastAPI, providing comprehensive HTTP c
 - Complete Cache-Control directive implementation
 - Easy-to-use `@cache` decorator
 
+### Session Management (Optional Extension)
+- Secure session management with HMAC-SHA256 token signing
+- IP address and User-Agent binding (optional security features)
+- Header and bearer token support (API-first architecture)
+- Automatic session renewal (sliding expiration)
+- Flash messages for cross-request communication
+- Multiple backend support (Redis, Memcached, In-Memory)
+- Complete session lifecycle management (create, validate, refresh, invalidate)
+
 ### Cache-Control Directives
 
 | Directive                | Supported          | Description                                                                                             |
@@ -53,6 +63,12 @@ A high-performance caching extension for FastAPI, providing comprehensive HTTP c
 uv add fastapi-cachex
 ```
 
+### Development Installation
+
+```bash
+uv add git+https://github.com/allen0099/FastAPI-CacheX.git
+```
+
 ## Quick Start
 
 ```python
@@ -96,7 +112,7 @@ FastAPI-CacheX supports multiple caching backends. You can easily switch between
 Cache keys are generated in the following format to avoid collisions:
 
 ```
-{method}:{host}:{path}:{query_params}
+{method}|||{host}|||{path}|||{query_params}
 ```
 
 This ensures that:
@@ -203,6 +219,7 @@ async def expensive_operation():
 - [Cache Flow Explanation](docs/CACHE_FLOW.md)
 - [Development Guide](docs/DEVELOPMENT.md)
 - [Contributing Guidelines](docs/CONTRIBUTING.md)
+- [Session Management Guide](docs/SESSION.md) - Complete guide for session features
 
 ## License
 

fastapi_cachex-0.2.3/fastapi_cachex/__init__.py

@@ -0,0 +1,27 @@
+"""FastAPI-CacheX: A powerful and flexible caching extension for FastAPI."""
+
+import logging
+
+from .cache import cache as cache
+from .cache import default_key_builder as default_key_builder
+from .dependencies import CacheBackend as CacheBackend
+from .dependencies import get_cache_backend as get_cache_backend
+from .proxy import BackendProxy as BackendProxy
+from .routes import add_routes as add_routes
+from .types import CacheKeyBuilder as CacheKeyBuilder
+
+_package_logger = logging.getLogger("fastapi_cachex")
+_package_logger.addHandler(
+    logging.NullHandler()
+)  # Attach a NullHandler to avoid "No handler found" warnings in user applications.
+
+# Session management (optional feature)
+__all__ = [
+    "BackendProxy",
+    "CacheBackend",
+    "CacheKeyBuilder",
+    "add_routes",
+    "cache",
+    "default_key_builder",
+    "get_cache_backend",
+]

fastapi_cachex-0.2.3/fastapi_cachex/backends/__init__.py

@@ -0,0 +1,13 @@
+"""Cache backend implementations for FastAPI-CacheX."""
+
+from .base import BaseCacheBackend
+from .memcached import MemcachedBackend
+from .memory import MemoryBackend
+from .redis import AsyncRedisCacheBackend
+
+__all__ = [
+    "AsyncRedisCacheBackend",
+    "BaseCacheBackend",
+    "MemcachedBackend",
+    "MemoryBackend",
+]

{fastapi_cachex-0.2.1 → fastapi_cachex-0.2.3}/fastapi_cachex/backends/memcached.py

@@ -1,17 +1,21 @@
 """Memcached cache backend implementation."""
 
+import logging
 import warnings
 
-from fastapi_cachex.backends.base import BaseCacheBackend
 from fastapi_cachex.exceptions import CacheXError
 from fastapi_cachex.types import ETagContent
 
+from .base import BaseCacheBackend
+
 try:
     import orjson as json
 
 except ImportError:  # pragma: no cover
     import json  # type: ignore[no-redef]  # pragma: no cover
 
+logger = logging.getLogger(__name__)
+
 # Default Memcached key prefix for fastapi-cachex
 DEFAULT_MEMCACHE_PREFIX = "fastapi_cachex:"
 
@@ -70,11 +74,13 @@ class MemcachedBackend(BaseCacheBackend):
         prefixed_key = self._make_key(key)
         value = self.client.get(prefixed_key)
         if value is None:
+            logger.debug("Memcached MISS; key=%s", key)
             return None
 
         # Memcached stores data as bytes; deserialize from JSON
         try:
             data = json.loads(value.decode("utf-8"))
+            logger.debug("Memcached HIT; key=%s", key)
             return ETagContent(
                 etag=data["etag"],
                 content=data["content"].encode()
@@ -82,6 +88,7 @@ class MemcachedBackend(BaseCacheBackend):
                 else data["content"],
             )
         except (json.JSONDecodeError, KeyError, ValueError):
+            logger.debug("Memcached DESERIALIZE ERROR; key=%s", key)
             return None
 
     async def set(self, key: str, value: ETagContent, ttl: int | None = None) -> None:
@@ -119,6 +126,7 @@ class MemcachedBackend(BaseCacheBackend):
             serialized_bytes,
             expire=ttl if ttl is not None else 0,
         )
+        logger.debug("Memcached SET; key=%s ttl=%s", key, ttl)
 
     async def delete(self, key: str) -> None:
         """Delete value from cache.
@@ -127,6 +135,7 @@ class MemcachedBackend(BaseCacheBackend):
             key: Cache key to delete
         """
         self.client.delete(self._make_key(key))
+        logger.debug("Memcached DELETE; key=%s", key)
 
     async def clear(self) -> None:
         """Clear all values from cache.
@@ -142,6 +151,7 @@ class MemcachedBackend(BaseCacheBackend):
             stacklevel=2,
         )
         self.client.flush_all()
+        logger.debug("Memcached CLEAR; flush_all issued")
 
     async def clear_path(self, path: str, include_params: bool = False) -> int:
         """Clear cached responses for a specific path.
@@ -175,9 +185,15 @@ class MemcachedBackend(BaseCacheBackend):
         except Exception:  # noqa: BLE001
             return 0
         else:
+            logger.debug(
+                "Memcached CLEAR_PATH; path=%s include_params=%s removed=%s",
+                path,
+                include_params,
+                1 if result else 0,
+            )
             return 1 if result else 0
 
-    async def clear_pattern(self, pattern: str) -> int:  # noqa: ARG002
+    async def clear_pattern(self, pattern: str) -> int:
         """Clear cached responses matching a pattern.
 
         Memcached does not support pattern matching or key scanning.
@@ -197,6 +213,7 @@ class MemcachedBackend(BaseCacheBackend):
             RuntimeWarning,
             stacklevel=2,
         )
+        logger.debug("Memcached CLEAR_PATTERN unsupported; pattern=%s", pattern)
         return 0
 
     async def get_all_keys(self) -> list[str]:
@@ -218,6 +235,7 @@ class MemcachedBackend(BaseCacheBackend):
             RuntimeWarning,
             stacklevel=2,
         )
+        logger.debug("Memcached GET_ALL_KEYS unsupported; returning empty list")
         return []
 
     async def get_cache_data(self) -> dict[str, tuple[ETagContent, float | None]]:
@@ -236,4 +254,5 @@ class MemcachedBackend(BaseCacheBackend):
             RuntimeWarning,
             stacklevel=2,
         )
+        logger.debug("Memcached GET_CACHE_DATA unsupported; returning empty dict")
         return {}

{fastapi_cachex-0.2.1 → fastapi_cachex-0.2.3}/fastapi_cachex/backends/memory.py

@@ -3,14 +3,18 @@
 import asyncio
 import contextlib
 import fnmatch
+import logging
 import time
 
+from fastapi_cachex.types import CACHE_KEY_SEPARATOR
 from fastapi_cachex.types import CacheItem
 from fastapi_cachex.types import ETagContent
 
 from .base import BaseCacheBackend
 
-# Cache keys are formatted as: method:host:path:query_params
+logger = logging.getLogger(__name__)
+
+# Cache keys are formatted as: method|||host|||path|||query_params
 # Minimum parts required to extract path component
 _MIN_KEY_PARTS = 3
 # Maximum parts to split (method, host, path, query_params)
@@ -43,6 +47,10 @@ class MemoryBackend(BaseCacheBackend):
             with contextlib.suppress(RuntimeError):
                 # No event loop yet; will be created on first async operation
                 self._cleanup_task = asyncio.create_task(self._cleanup_task_impl())
+                logger.debug(
+                    "Started memory backend cleanup task (interval=%s)",
+                    self.cleanup_interval,
+                )
 
     def start_cleanup(self) -> None:
         """Start the cleanup task if it's not already running.
@@ -56,6 +64,7 @@ class MemoryBackend(BaseCacheBackend):
         if self._cleanup_task is not None:
             self._cleanup_task.cancel()
             self._cleanup_task = None
+            logger.debug("Stopped memory backend cleanup task")
 
     async def get(self, key: str) -> ETagContent | None:
         """Retrieve a cached response.
@@ -69,10 +78,13 @@ class MemoryBackend(BaseCacheBackend):
             cached_item = self.cache.get(key)
             if cached_item:
                 if cached_item.expiry is None or cached_item.expiry > time.time():
+                    logger.debug("Memory cache HIT; key=%s", key)
                     return cached_item.value
                 # Entry has expired; clean it up
                 del self.cache[key]
+                logger.debug("Memory cache EXPIRED; key=%s removed", key)
                 return None
+            logger.debug("Memory cache MISS; key=%s", key)
             return None
 
     async def set(self, key: str, value: ETagContent, ttl: int | None = None) -> None:
@@ -86,16 +98,19 @@ class MemoryBackend(BaseCacheBackend):
         async with self.lock:
             expiry = time.time() + ttl if ttl is not None else None
             self.cache[key] = CacheItem(value=value, expiry=expiry)
+            logger.debug("Memory cache SET; key=%s ttl=%s", key, ttl)
 
     async def delete(self, key: str) -> None:
         """Remove a response from the cache."""
         async with self.lock:
             self.cache.pop(key, None)
+            logger.debug("Memory cache DELETE; key=%s", key)
 
     async def clear(self) -> None:
         """Clear all cached responses."""
         async with self.lock:
             self.cache.clear()
+            logger.debug("Memory cache CLEAR; all entries removed")
 
     async def clear_path(self, path: str, include_params: bool = False) -> int:
         """Clear cached responses for a specific path.
@@ -115,8 +130,8 @@ class MemoryBackend(BaseCacheBackend):
         async with self.lock:
             keys_to_delete = []
             for key in self.cache:
-                # Keys are formatted as: method:host:path:query_params
-                parts = key.split(":", _MAX_KEY_PARTS)
+                # Keys are formatted as: method|||host|||path|||query_params
+                parts = key.split(CACHE_KEY_SEPARATOR, _MAX_KEY_PARTS)
                 if len(parts) >= _MIN_KEY_PARTS:
                     cache_path = parts[2]
                     has_params = len(parts) > _MIN_KEY_PARTS
@@ -127,6 +142,12 @@ class MemoryBackend(BaseCacheBackend):
             for key in keys_to_delete:
                 del self.cache[key]
 
+        logger.debug(
+            "Memory cache CLEAR_PATH; path=%s include_params=%s removed=%s",
+            path,
+            include_params,
+            cleared_count,
+        )
         return cleared_count
 
     async def clear_pattern(self, pattern: str) -> int:
@@ -145,8 +166,8 @@ class MemoryBackend(BaseCacheBackend):
         async with self.lock:
             keys_to_delete = []
             for key in self.cache:
-                # Extract path component (method:host:path:query_params)
-                parts = key.split(":", _MAX_KEY_PARTS)
+                # Extract path component (method|||host|||path|||query_params)
+                parts = key.split(CACHE_KEY_SEPARATOR, _MAX_KEY_PARTS)
                 if len(parts) >= _MIN_KEY_PARTS:
                     cache_path = parts[2]
                     if fnmatch.fnmatch(cache_path, pattern):
@@ -156,6 +177,9 @@ class MemoryBackend(BaseCacheBackend):
             for key in keys_to_delete:
                 del self.cache[key]
 
+        logger.debug(
+            "Memory cache CLEAR_PATTERN; pattern=%s removed=%s", pattern, cleared_count
+        )
         return cleared_count
 
     async def get_all_keys(self) -> list[str]:
@@ -196,3 +220,7 @@ class MemoryBackend(BaseCacheBackend):
             ]
             for key in expired_keys:
                 self.cache.pop(key, None)
+            if expired_keys:
+                logger.debug(
+                    "Memory cache CLEANUP; expired removed=%s", len(expired_keys)
+                )

{fastapi_cachex-0.2.1 → fastapi_cachex-0.2.3}/fastapi_cachex/backends/redis.py

@@ -1,13 +1,16 @@
 """Redis cache backend implementation."""
 
+import logging
 from typing import TYPE_CHECKING
 from typing import Any
 from typing import Literal
 
-from fastapi_cachex.backends.base import BaseCacheBackend
 from fastapi_cachex.exceptions import CacheXError
+from fastapi_cachex.types import CACHE_KEY_SEPARATOR
 from fastapi_cachex.types import ETagContent
 
+from .base import BaseCacheBackend
+
 if TYPE_CHECKING:
     from redis.asyncio import Redis as AsyncRedis
 
@@ -17,6 +20,8 @@ try:
 except ImportError:  # pragma: no cover
     import json  # type: ignore[no-redef]  # pragma: no cover
 
+logger = logging.getLogger(__name__)
+
 # Default Redis key prefix for fastapi-cachex
 DEFAULT_REDIS_PREFIX = "fastapi_cachex:"
 
@@ -116,7 +121,9 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
     async def get(self, key: str) -> ETagContent | None:
         """Retrieve a cached response."""
         result = await self.client.get(self._make_key(key))
-        return self._deserialize(result)
+        value = self._deserialize(result)
+        logger.debug("Redis %s; key=%s", "HIT" if value else "MISS", key)
+        return value
 
     async def set(self, key: str, value: ETagContent, ttl: int | None = None) -> None:
         """Store a response in the cache."""
@@ -126,10 +133,12 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
             await self.client.setex(prefixed_key, ttl, serialized)
         else:
             await self.client.set(prefixed_key, serialized)
+        logger.debug("Redis SET; key=%s ttl=%s", key, ttl)
 
     async def delete(self, key: str) -> None:
         """Remove a response from the cache."""
         await self.client.delete(self._make_key(key))
+        logger.debug("Redis DELETE; key=%s", key)
 
     async def clear(self) -> None:
         """Clear all cached responses for this namespace.
@@ -160,6 +169,7 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
                 batch = keys_to_delete[i : i + batch_size]
                 if batch:
                     await self.client.delete(*batch)
+        logger.debug("Redis CLEAR; removed=%s", len(keys_to_delete))
 
     async def clear_path(self, path: str, include_params: bool = False) -> int:
         """Clear cached responses for a specific path.
@@ -175,11 +185,13 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         """
         # Pattern includes the HTTP method, host, and path components
         if include_params:
-            # Clear all variations: *:path:*
-            pattern = f"{self.key_prefix}*:{path}:*"
+            # Clear all variations: *|||path|||*
+            pattern = (
+                f"{self.key_prefix}*{CACHE_KEY_SEPARATOR}{path}{CACHE_KEY_SEPARATOR}*"
+            )
         else:
-            # Clear only exact path (no query params): *:path
-            pattern = f"{self.key_prefix}*:{path}"
+            # Clear only exact path (no query params): *|||path
+            pattern = f"{self.key_prefix}*{CACHE_KEY_SEPARATOR}{path}"
 
         cursor = 0
         batch_size = 100
@@ -206,6 +218,12 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
                     deleted = await self.client.delete(*batch)
                     cleared_count += deleted
 
+        logger.debug(
+            "Redis CLEAR_PATH; path=%s include_params=%s removed=%s",
+            path,
+            include_params,
+            cleared_count,
+        )
         return cleared_count
 
     async def clear_pattern(self, pattern: str) -> int:
@@ -250,6 +268,9 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
                     deleted = await self.client.delete(*batch)
                     cleared_count += deleted
 
+        logger.debug(
+            "Redis CLEAR_PATTERN; pattern=%s removed=%s", full_pattern, cleared_count
+        )
         return cleared_count
 
     async def get_all_keys(self) -> list[str]:
@@ -275,6 +296,7 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
             if cursor == 0:
                 break
 
+        logger.debug("Redis GET_ALL_KEYS; count=%s", len(all_keys))
         return all_keys
 
     async def get_cache_data(self) -> dict[str, tuple[ETagContent, float | None]]:
@@ -297,4 +319,5 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
             if value is not None:
                 cache_data[original_key] = (value, None)
 
+        logger.debug("Redis GET_CACHE_DATA; keys=%s", len(cache_data))
         return cache_data