fastapi-cachex 0.2.1__py3-none-any.whl

fastapi_cachex/routes.py

@@ -0,0 +1,311 @@
+"""Optional routes for cache monitoring and management."""
+
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from fastapi_cachex.backends import BaseCacheBackend
+from fastapi_cachex.exceptions import BackendNotFoundError
+from fastapi_cachex.proxy import BackendProxy
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+# Constants
+CACHE_KEY_MIN_PARTS = 3
+CACHE_KEY_MAX_PARTS = 3
+
+
+@dataclass
+class CacheHitRecord:
+    """Record for a single cache hit."""
+
+    cache_key: str
+    method: str
+    host: str
+    path: str
+    query_params: str
+    etag: str
+    is_expired: bool
+    ttl_remaining: float | None
+
+
+@dataclass
+class CacheHitSummary:
+    """Summary of cache hit statistics."""
+
+    total_cached_entries: int
+    active_entries: int
+    frequently_cached_routes: list[str]
+
+
+@dataclass
+class CacheHitsResponse:
+    """Response for cached hits endpoint."""
+
+    cached_hits: list[CacheHitRecord]
+    total_hits: int
+    valid_hits: int
+    expired_hits: int
+    unique_routes: int
+    summary: CacheHitSummary
+
+
+@dataclass
+class CachedRecord:
+    """Record for a single cached item."""
+
+    cache_key: str
+    method: str
+    host: str
+    path: str
+    query_params: str
+    etag: str
+    content_type: str
+    content_size: int
+    is_expired: bool
+    ttl_remaining: float | None
+    content_preview: str
+
+
+@dataclass
+class CacheSummary:
+    """Summary of cached records."""
+
+    total_entries: int
+    valid_entries: int
+    estimated_cache_size_kb: float
+
+
+@dataclass
+class CachedRecordsResponse:
+    """Response for cached records endpoint."""
+
+    cached_records: list[CachedRecord]
+    total_records: int
+    active_records: int
+    expired_records: int
+    total_cache_size_bytes: int
+    summary: CacheSummary
+
+
+def _parse_cache_key(cache_key: str) -> tuple[str, str, str, str]:
+    """Parse cache key into components.
+
+    Args:
+        cache_key: Cache key in format method:host:path:query_params
+
+    Returns:
+        Tuple of (method, host, path, query_params)
+    """
+    key_parts = cache_key.split(":", CACHE_KEY_MAX_PARTS)
+    if len(key_parts) >= CACHE_KEY_MIN_PARTS:
+        method, host, path = key_parts[0], key_parts[1], key_parts[2]
+        query_params = key_parts[3] if len(key_parts) > CACHE_KEY_MIN_PARTS else ""
+        return method, host, path, query_params
+
+    return "", "", "", ""
+
+
+async def _get_cached_hits_handler(backend: BaseCacheBackend) -> CacheHitsResponse:
+    """Handle the cached hits request.
+
+    Args:
+        backend: The cache backend instance
+
+    Returns:
+        CacheHitsResponse
+    """
+    cache_data = await backend.get_cache_data()
+
+    now = time.time()
+    cached_hits: list[CacheHitRecord] = []
+
+    for cache_key, (etag_content, expiry) in cache_data.items():
+        method, host, path, query_params = _parse_cache_key(cache_key)
+        if method:  # Valid cache key
+            # Check if cache entry is expired
+            is_expired = expiry is not None and expiry <= now
+            ttl_remaining = round(expiry - now, 2) if expiry is not None else None
+
+            cached_hits.append(
+                CacheHitRecord(
+                    cache_key=cache_key,
+                    method=method,
+                    host=host,
+                    path=path,
+                    query_params=query_params,
+                    etag=etag_content.etag,
+                    is_expired=is_expired,
+                    ttl_remaining=ttl_remaining,
+                )
+            )
+
+    # Calculate summary statistics
+    valid_hits: list[CacheHitRecord] = [h for h in cached_hits if not h.is_expired]
+    routes_hit: set[str] = {h.path for h in valid_hits}
+
+    return CacheHitsResponse(
+        cached_hits=cached_hits,
+        total_hits=len(cached_hits),
+        valid_hits=len(valid_hits),
+        expired_hits=len(cached_hits) - len(valid_hits),
+        unique_routes=len(routes_hit),
+        summary=CacheHitSummary(
+            total_cached_entries=len(cached_hits),
+            active_entries=len(valid_hits),
+            frequently_cached_routes=sorted(routes_hit),
+        ),
+    )
+
+
+async def _get_cached_records_handler(
+    backend: BaseCacheBackend,
+) -> CachedRecordsResponse:
+    """Handle the cached records request.
+
+    Args:
+        backend: The cache backend instance
+
+    Returns:
+        CachedRecordsResponse
+    """
+    cache_data = await backend.get_cache_data()
+
+    now = time.time()
+    cached_records: list[CachedRecord] = []
+
+    for cache_key, (etag_content, expiry) in cache_data.items():
+        method, host, path, query_params = _parse_cache_key(cache_key)
+        if method:  # Valid cache key
+            # Check if cache entry is expired
+            is_expired = expiry is not None and expiry <= now
+
+            # Get content size
+            content = etag_content.content
+            content_size = len(content) if isinstance(content, (bytes, str)) else 0
+
+            ttl_remaining = round(expiry - now, 2) if expiry is not None else None
+
+            content_preview = (
+                content[:100].decode("utf-8", errors="ignore")
+                if isinstance(content, bytes)
+                else str(content)[:100]
+            )
+
+            cached_records.append(
+                CachedRecord(
+                    cache_key=cache_key,
+                    method=method,
+                    host=host,
+                    path=path,
+                    query_params=query_params,
+                    etag=etag_content.etag,
+                    content_type=type(content).__name__,
+                    content_size=content_size,
+                    is_expired=is_expired,
+                    ttl_remaining=ttl_remaining,
+                    content_preview=content_preview,
+                )
+            )
+
+    # Count active records and total size
+    active_records = sum(1 for r in cached_records if not r.is_expired)
+    total_size = sum(r.content_size for r in cached_records)
+
+    return CachedRecordsResponse(
+        cached_records=cached_records,
+        total_records=len(cached_records),
+        active_records=active_records,
+        expired_records=len(cached_records) - active_records,
+        total_cache_size_bytes=total_size,
+        summary=CacheSummary(
+            total_entries=len(cached_records),
+            valid_entries=active_records,
+            estimated_cache_size_kb=round(total_size / 1024, 2),
+        ),
+    )
+
+
+def add_routes(
+    app: "FastAPI", prefix: str = "", include_in_schema: bool = False
+) -> None:
+    """Add cache monitoring routes to the FastAPI application.
+
+    This function allows users to optionally add cache monitoring routes
+    to their FastAPI application. Users can call this function to enable
+    cache hit tracking and cache record display.
+
+    Args:
+        app: FastAPI application instance
+        prefix: URL prefix for the routes (e.g., "/api/cache", "/admin/cache").
+                Defaults to "" (no prefix).
+        include_in_schema: Whether to include routes in OpenAPI schema.
+                          Defaults to False.
+
+    Example:
+        from fastapi import FastAPI
+        from fastapi_cachex import add_routes
+
+        app = FastAPI()
+        add_routes(app)  # Routes at /cached-hits and /cached-records
+
+        # Or with prefix
+        add_routes(app, prefix="/api/cache")  # Routes at /api/cache/cached-hits and /api/cache/cached-records
+    """
+
+    @app.get(f"{prefix}/cached-hits", include_in_schema=include_in_schema)
+    async def get_cached_hits() -> CacheHitsResponse:
+        """Return cached hit records.
+
+        Shows cache statistics including which routes are frequently being cached,
+        hit counts, and cache key information.
+
+        Returns:
+            CacheHitsResponse containing cache hit records and statistics
+        """
+        try:
+            backend: BaseCacheBackend = BackendProxy.get_backend()
+        except BackendNotFoundError:
+            return CacheHitsResponse(
+                cached_hits=[],
+                total_hits=0,
+                valid_hits=0,
+                expired_hits=0,
+                unique_routes=0,
+                summary=CacheHitSummary(
+                    total_cached_entries=0,
+                    active_entries=0,
+                    frequently_cached_routes=[],
+                ),
+            )
+
+        return await _get_cached_hits_handler(backend)
+
+    @app.get(f"{prefix}/cached-records", include_in_schema=include_in_schema)
+    async def get_cached_records() -> CachedRecordsResponse:
+        """Display currently cached records.
+
+        Returns all currently cached records in the cache backend with their
+        content information and expiry details.
+
+        Returns:
+            CachedRecordsResponse containing cached records and statistics
+        """
+        try:
+            backend: BaseCacheBackend = BackendProxy.get_backend()
+        except BackendNotFoundError:
+            return CachedRecordsResponse(
+                cached_records=[],
+                total_records=0,
+                active_records=0,
+                expired_records=0,
+                total_cache_size_bytes=0,
+                summary=CacheSummary(
+                    total_entries=0,
+                    valid_entries=0,
+                    estimated_cache_size_kb=0.0,
+                ),
+            )
+
+        return await _get_cached_records_handler(backend)

fastapi_cachex/types.py

@@ -0,0 +1,25 @@
+"""Type definitions and type aliases for FastAPI-CacheX."""
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class ETagContent:
+    """ETag and content for cache items."""
+
+    etag: str
+    content: Any
+
+
+@dataclass
+class CacheItem:
+    """Cache item with optional expiry time.
+
+    Args:
+        value: The cached ETagContent
+        expiry: Epoch timestamp when this cache item expires (None = never expires)
+    """
+
+    value: ETagContent
+    expiry: float | None = None

fastapi_cachex-0.2.1.dist-info/METADATA

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: fastapi-cachex
+Version: 0.2.1
+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>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3 :: Only
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Dist: fastapi
+Requires-Dist: pymemcache ; extra == 'memcache'
+Requires-Dist: redis[hiredis] ; extra == 'redis'
+Requires-Dist: orjson ; extra == 'redis'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/allen0099/FastAPI-CacheX
+Project-URL: Issues, https://github.com/allen0099/FastAPI-CacheX/issues
+Project-URL: Repository, https://github.com/allen0099/FastAPI-CacheX.git
+Provides-Extra: memcache
+Provides-Extra: redis
+Description-Content-Type: text/markdown
+
+# FastAPI-Cache X
+
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Tests](https://github.com/allen0099/FastAPI-CacheX/actions/workflows/test.yml/badge.svg)](https://github.com/allen0099/FastAPI-CacheX/actions/workflows/test.yml)
+[![Coverage Status](https://raw.githubusercontent.com/allen0099/FastAPI-CacheX/coverage-badge/coverage.svg)](https://github.com/allen0099/FastAPI-CacheX/actions/workflows/coverage.yml)
+
+[![Downloads](https://static.pepy.tech/badge/fastapi-cachex)](https://pepy.tech/project/fastapi-cachex)
+[![Weekly downloads](https://static.pepy.tech/badge/fastapi-cachex/week)](https://pepy.tech/project/fastapi-cachex)
+[![Monthly downloads](https://static.pepy.tech/badge/fastapi-cachex/month)](https://pepy.tech/project/fastapi-cachex)
+
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-cachex.svg?logo=pypi&logoColor=gold&label=PyPI)](https://pypi.org/project/fastapi-cachex)
+[![Python Versions](https://img.shields.io/pypi/pyversions/fastapi-cachex.svg?logo=python&label=Python&logoColor=gold)](https://pypi.org/project/fastapi-cachex/)
+
+[English](README.md) | [繁體中文](docs/README.zh-TW.md)
+
+A high-performance caching extension for FastAPI, providing comprehensive HTTP caching support.
+
+## Features
+
+- Support for HTTP caching headers
+    - `Cache-Control`
+    - `ETag`
+    - `If-None-Match`
+- Multiple backend cache support
+    - Redis
+    - Memcached
+    - In-memory cache
+- Complete Cache-Control directive implementation
+- Easy-to-use `@cache` decorator
+
+### Cache-Control Directives
+
+| Directive                | Supported          | Description                                                                                             |
+|--------------------------|--------------------|---------------------------------------------------------------------------------------------------------|
+| `max-age`                | :white_check_mark: | Specifies the maximum amount of time a resource is considered fresh.                                    |
+| `s-maxage`               | :x:                | Specifies the maximum amount of time a resource is considered fresh for shared caches.                  |
+| `no-cache`               | :white_check_mark: | Forces caches to submit the request to the origin server for validation before releasing a cached copy. |
+| `no-store`               | :white_check_mark: | Instructs caches not to store any part of the request or response.                                      |
+| `no-transform`           | :x:                | Instructs caches not to transform the response content.                                                 |
+| `must-revalidate`        | :white_check_mark: | Forces caches to revalidate the response with the origin server after it becomes stale.                 |
+| `proxy-revalidate`       | :x:                | Similar to `must-revalidate`, but only for shared caches.                                               |
+| `must-understand`        | :x:                | Indicates that the recipient must understand the directive or treat it as an error.                     |
+| `private`                | :white_check_mark: | Indicates that the response is intended for a single user and should not be stored by shared caches.    |
+| `public`                 | :white_check_mark: | Indicates that the response may be cached by any cache, even if it is normally non-cacheable.           |
+| `immutable`              | :white_check_mark: | Indicates that the response body will not change over time, allowing for longer caching.                |
+| `stale-while-revalidate` | :white_check_mark: | Indicates that a cache can serve a stale response while it revalidates the response in the background.  |
+| `stale-if-error`         | :white_check_mark: | Indicates that a cache can serve a stale response if the origin server is unavailable.                  |
+
+## Installation
+
+```bash
+uv add fastapi-cachex
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+from fastapi_cachex import cache
+from fastapi_cachex import CacheBackend
+
+app = FastAPI()
+
+
+@app.get("/")
+@cache(ttl=60)  # Cache for 60 seconds
+async def read_root():
+    return {"Hello": "World"}
+
+
+@app.get("/no-cache")
+@cache(no_cache=True)  # Mark this endpoint as non-cacheable
+async def non_cache_endpoint():
+    return {"Hello": "World"}
+
+
+@app.get("/no-store")
+@cache(no_store=True)  # Mark this endpoint as non-cacheable
+async def non_store_endpoint():
+    return {"Hello": "World"}
+
+
+@app.get("/clear_cache")
+async def remove_cache(cache: CacheBackend):
+    await cache.clear_path("/path/to/clear")  # Clear cache for a specific path
+    await cache.clear_pattern("/path/to/clear/*")  # Clear cache for a specific pattern
+```
+
+## Backend Configuration
+
+FastAPI-CacheX supports multiple caching backends. You can easily switch between them using the `BackendProxy`.
+
+### Cache Key Format
+
+Cache keys are generated in the following format to avoid collisions:
+
+```
+{method}:{host}:{path}:{query_params}
+```
+
+This ensures that:
+- Different HTTP methods (GET, POST, etc.) don't share cache
+- Different hosts don't share cache (useful for multi-tenant scenarios)
+- Different query parameters get separate cache entries
+- The same endpoint with different parameters can be cached independently
+
+All backends automatically namespace keys with a prefix (e.g., `fastapi_cachex:`) to avoid conflicts with other applications.
+
+### Cache Hit Behavior
+
+When a cached entry is valid (within TTL):
+- **Default behavior**: Returns the cached content with HTTP 200 status code directly without re-executing the endpoint handler
+- **With `If-None-Match` header**: Returns HTTP 304 Not Modified if the ETag matches
+- **With `no-cache` directive**: Forces revalidation with fresh content before deciding on 304
+
+This means **cached hits are extremely fast** - the endpoint handler function is never executed.
+
+### In-Memory Cache (default)
+
+If you don't specify a backend, FastAPI-CacheX will use the in-memory cache by default.
+This is suitable for development and testing purposes. The backend automatically runs
+a cleanup task to remove expired entries every 60 seconds.
+
+```python
+from fastapi_cachex.backends import MemoryBackend
+from fastapi_cachex import BackendProxy
+
+backend = MemoryBackend()
+BackendProxy.set_backend(backend)
+```
+
+**Note**: In-memory cache is not suitable for production with multiple processes.
+Each process maintains its own separate cache.
+
+### Memcached
+
+```python
+from fastapi_cachex.backends import MemcachedBackend
+from fastapi_cachex import BackendProxy
+
+backend = MemcachedBackend(servers=["localhost:11211"])
+BackendProxy.set_backend(backend)
+```
+
+**Limitations**:
+- Pattern-based key clearing (`clear_pattern`) is not supported by the Memcached protocol
+- Keys are namespaced with `fastapi_cachex:` prefix to avoid conflicts
+- Consider using Redis backend if you need pattern-based cache clearing
+
+### Redis
+
+```python
+from fastapi_cachex.backends import AsyncRedisCacheBackend
+from fastapi_cachex import BackendProxy
+
+backend = AsyncRedisCacheBackend(host="127.0.0.1", port=6379, db=0)
+BackendProxy.set_backend(backend)
+```
+
+**Features**:
+- Fully async implementation
+- Supports pattern-based key clearing
+- Uses SCAN instead of KEYS for safe production use (non-blocking)
+- Namespaced with `fastapi_cachex:` prefix by default
+- Optional custom key prefix for multi-tenant scenarios
+
+**Example with custom prefix**:
+
+```python
+backend = AsyncRedisCacheBackend(
+    host="127.0.0.1",
+    port=6379,
+    key_prefix="myapp:cache:",
+)
+BackendProxy.set_backend(backend)
+```
+
+## Performance Considerations
+
+### Cache Hit Performance
+
+When a cache hit occurs (within TTL), the response is returned directly without executing your endpoint handler. This is extremely fast:
+
+```python
+@app.get("/expensive")
+@cache(ttl=3600)  # Cache for 1 hour
+async def expensive_operation():
+    # This is ONLY executed when cache misses
+    # On cache hits, this function is never called
+    result = perform_expensive_calculation()
+    return result
+```
+
+### Backend Selection
+
+- **MemoryBackend**: Fastest for single-process development; not suitable for production
+- **Memcached**: Good for distributed systems; has limitations on pattern clearing
+- **Redis**: Best for production; fully async, supports all features, non-blocking operations
+
+## Documentation
+
+- [Cache Flow Explanation](docs/CACHE_FLOW.md)
+- [Development Guide](docs/DEVELOPMENT.md)
+- [Contributing Guidelines](docs/CONTRIBUTING.md)
+
+## License
+
+This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

fastapi_cachex-0.2.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+fastapi_cachex/__init__.py,sha256=T8KTNtlTxqYUzUZTbDutL9QErRFc-Ev7yh406u578e4,325
+fastapi_cachex/backends/__init__.py,sha256=9dZr4l-Ozca9PC1Qsnbjnks8-r6A22fFWL8WP9DOR-I,414
+fastapi_cachex/backends/base.py,sha256=7nQ15GQ_c8r7OnKYAeK8DqCEnrT30Qt1OaCfXl28vZw,2083
+fastapi_cachex/backends/memcached.py,sha256=HHreoCLYtNYaz_wuK9h3St5AOS7LvItnNXjazwvKvy8,8103
+fastapi_cachex/backends/memory.py,sha256=djQbj-jeTd9MIu_G-HUcfDauoNhu9wxynfak-mR5nYY,6950
+fastapi_cachex/backends/redis.py,sha256=uFNrHjFoshGmFMmMBb6ooVLS34GHz_Xl7WA8POE3sJk,9977
+fastapi_cachex/cache.py,sha256=W1nr-sUjTsFluRfXpiZjOeKRz9sIT0J_fX5ZGB81bDU,11284
+fastapi_cachex/dependencies.py,sha256=RZfsO9U9BDdbhmZ7QEWd178vwQ_qb4vUvU6Z_fsmy4M,450
+fastapi_cachex/directives.py,sha256=0W9_rRbxF1YioII7DNCa498ets3sHpqny0JLm-EUw5s,585
+fastapi_cachex/exceptions.py,sha256=64Ub9pOa4w_jCc4DEjIngYYLXPuzVYEkn5vh_CLS69I,432
+fastapi_cachex/proxy.py,sha256=iEKuLX3Qc8z4NcokMANdigDuZmXrgYbcZPBH75BtRkk,1047
+fastapi_cachex/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastapi_cachex/routes.py,sha256=A8KvOsFQniwoo2rS4sSnVzujTicHFbM38e2619nxDG0,9363
+fastapi_cachex/types.py,sha256=DkNyZYl4bIe3Vrlz_FZnxjHyMbmniwrAVwL0OVgccaM,498
+fastapi_cachex-0.2.1.dist-info/WHEEL,sha256=ZyFSCYkV2BrxH6-HRVRg3R9Fo7MALzer9KiPYqNxSbo,79
+fastapi_cachex-0.2.1.dist-info/METADATA,sha256=fEaMiWm77W-Mih0mDhm-EyvcpcfMczx2uzVuzlgUb2U,10310
+fastapi_cachex-0.2.1.dist-info/RECORD,,

fastapi_cachex-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.18
+Root-Is-Purelib: true
+Tag: py3-none-any