fastapi-caching-route 0.6.0__py3-none-any.whl

fastapi_caching_route/__init__.py

@@ -0,0 +1,6 @@
+"""FastAPI Caching Route."""
+
+__all__ = ['CachingRoute', 'FastAPICache', '__version__']
+
+from fastapi_caching_route._version import version as __version__
+from fastapi_caching_route.main import CachingRoute, FastAPICache

fastapi_caching_route/_version.py

@@ -0,0 +1 @@
+version = "0.6.0"

fastapi_caching_route/_version.pyi

@@ -0,0 +1 @@
+version: str

fastapi_caching_route/main.py

@@ -0,0 +1,590 @@
+"""Implementation for FastAPI Caching Route."""
+
+from __future__ import annotations
+
+import base64
+from contextlib import AsyncExitStack
+from dataclasses import dataclass
+from hashlib import sha256
+from typing import TYPE_CHECKING, Annotated, Any, Literal, ParamSpec, TypedDict, TypeVar
+
+from fastapi import Request, Response
+from fastapi.dependencies.models import Dependant
+from fastapi.dependencies.utils import get_dependant, solve_dependencies
+from fastapi.routing import APIRoute
+from starlette.datastructures import MutableHeaders
+from starlette.responses import StreamingResponse
+from starlette.status import HTTP_200_OK, HTTP_304_NOT_MODIFIED
+
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        AsyncGenerator,
+        Awaitable,
+        Callable,
+        Coroutine,
+        Iterable,
+        Sequence,
+        Set as AbstractSet,
+    )
+
+    from aiocache import BaseCache
+    from fastapi.params import Depends
+    from typing_extensions import Buffer, Doc, NotRequired
+
+    KeyBuilder = Callable[[Request], str]
+    RouteHandler = Callable[[Request], Coroutine[Any, Any, Response]]
+
+    class CacheParamsBase(TypedDict):
+        """Cache parameters to be passed to aiocache."""
+
+        namespace: NotRequired[str | None]
+        ttl: NotRequired[float]
+
+    class CacheParams(CacheParamsBase):
+        """Cache parameters for a specific endpoint."""
+
+        key_builder: NotRequired[KeyBuilder]
+        dependencies: NotRequired[Sequence[Depends]]
+        vary_headers: NotRequired[Sequence[str]]
+
+    class CachedResponse(TypedDict):
+        """Response data to be stored in cache."""
+
+        content: Buffer
+        media_type: str | None
+        raw_headers: list[tuple[bytes, bytes]]
+        status_code: int
+
+    _T = TypeVar('_T')
+    _P = ParamSpec('_P')
+
+
+_CACHE_CONFIG = '__fastapi_caching_route_87233d36__'
+
+DEFAULT_ACCEPTED_STATUS_CODES = frozenset({HTTP_200_OK})
+
+
+@dataclass(frozen=True, slots=True)
+class _CacheConfig:
+    cache: FastAPICache
+    key_builder: KeyBuilder | None
+    early_dependencies: Sequence[Depends]
+    vary_headers: tuple[str, ...]
+    params: CacheParamsBase
+
+
+@dataclass(frozen=True, slots=True)
+class _CacheRequest:
+    request: Request
+    cache: FastAPICache
+    cache_key: str
+    caching_params: CacheParamsBase
+    namespace: str | None
+    vary_headers: tuple[str, ...]
+
+
+class FastAPICache:
+    """Manages cached routes.
+
+    ## Example
+
+    ```py
+    from aiocache import SimpleMemoryCache
+    from fastapi import APIRouter, FastAPI
+    from fastapi_caching_route import CachingRoute, FastAPICache
+
+
+    router = APIRouter(route_class=CachingRoute)
+    cache = FastAPICache(SimpleMemoryCache())
+
+    @cache()
+    @router.get('/')
+    def cached() -> str:
+        return 'Hello, World!'
+
+    app = FastAPI()
+    app.include_router(router)
+    ```
+    """
+
+    __slots__ = (
+        '_cache_header',
+        '_cache_header_hit',
+        '_cache_header_miss',
+        '_concat_namespace',
+        '_inner',
+        'accepted_status_codes',
+    )
+
+    def __init__(
+        self,
+        cache: Annotated[BaseCache, Doc('aiocache instance to perform caching.')],
+        *,
+        namespace_policy: Annotated[
+            Literal['concat', 'replace'],
+            Doc(
+                """How to process namespaces passed to the decorator.
+
+                ## concat (default)
+
+                Add to the root (passed to the aiocache instance) namespace.
+
+                ```py
+                cache = FastAPICache(RedisCache(namespace='cache'))
+
+                # resulting namespace is 'cache:user'
+                @cache(namespace='user')
+                @router.get('/{user_id}')
+                async def get_user(user_id: str):
+                    ...
+                ```
+
+                ## replace
+
+                Replace the root namespace.
+
+                ```py
+                cache = FastAPICache(RedisCache(namespace='cache'), namespace_policy='replace')
+
+                # resulting namespace is 'user'
+                @cache(namespace='user')
+                @router.get('/{user_id}')
+                async def get_user(user_id: str):
+                    ...
+                ```
+                """,
+            ),
+        ] = 'concat',
+        cache_header: str = 'X-Cache',
+        cache_header_hit: str = 'HIT',
+        cache_header_miss: str = 'MISS',
+        accepted_status_codes: Annotated[
+            AbstractSet[int] | Iterable[int],
+            Doc('Only cache responses with these HTTP status codes.'),
+        ] = DEFAULT_ACCEPTED_STATUS_CODES,
+    ) -> None:
+        self._inner = cache
+        self._concat_namespace = namespace_policy == 'concat'
+        self._cache_header = cache_header
+        self._cache_header_hit = cache_header_hit
+        self._cache_header_miss = cache_header_miss
+        self.accepted_status_codes = frozenset(accepted_status_codes)
+
+    def __call__(
+        self,
+        *,
+        key_builder: KeyBuilder | None = None,
+        dependencies: Sequence[Depends] = (),
+        vary_headers: Sequence[str] = (),
+        namespace: str | None = None,
+        ttl: float | None = None,
+    ) -> Callable[[Callable[_P, _T]], Callable[_P, _T]]:
+        """Decorate caching route.
+
+        Marks the endpoint for caching by :class:`CachingRoute`.
+
+        ```py hl_lines="3"
+            cache = FastAPICache(SimpleMemoryCache())
+
+            @cache()
+            @router.get('/')
+            def cached() -> str:
+                ...
+        ```
+        """
+        params: CacheParamsBase = {}
+        if namespace is not None:
+            params['namespace'] = namespace
+        if ttl is not None:
+            params['ttl'] = ttl
+
+        def decorator(endpoint: Callable[_P, _T]) -> Callable[_P, _T]:
+            config = _CacheConfig(
+                cache=self,
+                key_builder=key_builder,
+                early_dependencies=tuple(dependencies),
+                vary_headers=_normalize_header_names(vary_headers),
+                params=params,
+            )
+            setattr(endpoint, _CACHE_CONFIG, config)
+            return endpoint
+
+        return decorator
+
+    def get_cached(
+        self,
+        cache_key: str,
+        namespace: str | None = None,
+    ) -> Awaitable[CachedResponse | None]:
+        """Get cached response.
+
+        Returns:
+            Cached response.
+        """
+        return self._inner.get(cache_key, namespace=namespace)
+
+    def set_cached(
+        self,
+        cache_key: str,
+        value: CachedResponse,
+        caching_params: CacheParamsBase,
+    ) -> Awaitable[bool]:
+        """Set cached response.
+
+        Returns:
+            `True` if the value was set.
+        """
+        return self._inner.set(cache_key, value, **caching_params)
+
+    def invalidate_cached(
+        self,
+        cache_key: str,
+        namespace: str | None = None,
+    ) -> Annotated[Awaitable[int], Doc('Number of deleted keys.')]:
+        """Delete cached response.
+
+        Returns:
+            Number of deleted keys.
+        """
+        return self._inner.delete(cache_key, namespace)
+
+    def prepare_cache_params(self, cache_params: CacheParamsBase) -> CacheParamsBase:
+        """Prepare cache backend parameters for a request."""
+        caching_params = cache_params.copy()
+        namespace = caching_params.get('namespace', None)
+        root = self._inner.namespace
+        if self._concat_namespace and root and namespace:
+            caching_params['namespace'] = f'{root}:{namespace}'
+        return caching_params
+
+    def set_cache_header(self, headers: MutableHeaders | dict[str, str], *, hit: bool) -> None:
+        """Set a cache status header."""
+        headers[self._cache_header] = self._cache_header_hit if hit else self._cache_header_miss
+
+
+class CachingRoute(APIRoute):
+    """FastAPI route to perform caching.
+
+    Intended for use with fastapi.APIRouter.
+
+    ```py hl_lines="4"
+    from fastapi import APIRouter
+    from fastapi_caching_route import CachingRoute
+
+    router = APIRouter(route_class=CachingRoute)
+    ```
+    """
+
+    def get_route_handler(self) -> RouteHandler:  # noqa: D102
+        return _CachingRouteHandler(
+            original_handler=super().get_route_handler(),
+            path=self.path,
+            endpoint=self.endpoint,
+            query_params=self.dependant.query_params,
+        )
+
+
+@dataclass(slots=True, kw_only=True)
+class _CachingRouteHandler:
+    original_handler: RouteHandler
+    path: str
+    endpoint: Any
+    query_params: Sequence[Any]
+    early_dependant: Dependant | None | Literal[False] = False
+    default_key_builder: KeyBuilder | None = None
+
+    async def __call__(self, request: Request) -> Response:
+        config = getattr(self.endpoint, _CACHE_CONFIG, None)
+        if not isinstance(config, _CacheConfig):
+            return await self.original_handler(request)
+
+        if not await self._early_dependencies_solved(request, config):
+            return await self.original_handler(request)
+
+        cache_params = self._prepare_cache_request(request, config)
+        if cached_response := await self._get_cached_response(cache_params):
+            return cached_response
+
+        response = await self.original_handler(request)
+        return await self._cache_response(response, cache_params)
+
+    async def _early_dependencies_solved(self, request: Request, config: _CacheConfig) -> bool:
+        if self.early_dependant is False:
+            self.early_dependant = _build_early_dependant(self.path, config)
+        if self.early_dependant is None:
+            return True
+        async with AsyncExitStack() as async_exit_stack:
+            solved_dependency = await solve_dependencies(
+                request=request,
+                dependant=self.early_dependant,
+                async_exit_stack=async_exit_stack,
+                embed_body_fields=False,
+            )
+        return not solved_dependency.errors
+
+    def _prepare_cache_request(self, request: Request, config: _CacheConfig) -> _CacheRequest:
+        cache = config.cache
+        caching_params = cache.prepare_cache_params(config.params)
+        key_builder = config.key_builder or self._get_default_key_builder(config)
+        return _CacheRequest(
+            request=request,
+            cache=cache,
+            cache_key=key_builder(request),
+            caching_params=caching_params,
+            namespace=caching_params.get('namespace', None),
+            vary_headers=config.vary_headers,
+        )
+
+    def _get_default_key_builder(self, config: _CacheConfig) -> KeyBuilder:
+        if self.default_key_builder is None:
+            self.default_key_builder = _key_builder_factory(self.query_params, config.vary_headers)
+        return self.default_key_builder
+
+    async def _get_cached_response(self, cache_request: _CacheRequest) -> Response | None:
+        cached = await cache_request.cache.get_cached(
+            cache_request.cache_key,
+            cache_request.namespace,
+        )
+        if cached is None:
+            return None
+
+        headers = MutableHeaders(raw=cached['raw_headers'])
+        cache_request.cache.set_cache_header(headers, hit=True)
+        return _build_cached_response(cache_request.request, cached, headers)
+
+    async def _cache_response(self, response: Response, cache_request: _CacheRequest) -> Response:
+        cache = cache_request.cache
+        if response.status_code not in cache.accepted_status_codes:
+            return response
+
+        _add_vary_header(response.headers, cache_request.vary_headers)
+        if _get_vary_headers(response.headers) is None:
+            return response
+
+        if isinstance(response, StreamingResponse):
+            cached, response = await _cache_streaming_response(response)
+        else:
+            _ensure_etag(response.headers, response.body)
+            cached: CachedResponse = {
+                'content': response.body,
+                'media_type': response.media_type,
+                'raw_headers': list(response.raw_headers),
+                'status_code': response.status_code,
+            }
+
+        await cache.set_cached(cache_request.cache_key, cached, cache_request.caching_params)
+        cache.set_cache_header(response.headers, hit=False)
+        return response
+
+
+def _build_early_dependant(path: str, config: _CacheConfig) -> Dependant | None:
+    dependencies = [
+        get_dependant(
+            path=path,
+            call=dependency.dependency,
+            use_cache=dependency.use_cache,
+        )
+        for dependency in config.early_dependencies
+        if dependency.dependency
+    ]
+    if not dependencies:
+        return None
+    return Dependant(dependencies=dependencies)
+
+
+def _key_builder_factory(params: Sequence[Any], vary_headers: Sequence[str]) -> KeyBuilder:
+    params_ = []
+    for param in sorted(params, key=lambda p: p.alias or p.name):
+        default = '' if param.field_info.is_required() else param.default
+        if isinstance(default, list):
+            default_values = tuple(str(value) for value in default)
+        else:
+            default_values = (default,)
+        params_.append((param.alias or param.name, default_values))
+    vary_headers = _normalize_header_names(vary_headers)
+
+    def _impl(request: Request) -> str:
+        key = (
+            request.method,
+            request.scope['path'],
+            tuple((k, tuple(request.query_params.getlist(k)) or d) for k, d in params_),
+            tuple((h, request.headers.get(h, '')) for h in vary_headers),
+        )
+        digest = sha256(repr(key).encode('utf-8'), usedforsecurity=False).digest()
+        return base64.b64encode(digest).decode()
+
+    return _impl
+
+
+def _build_cached_response(
+    request: Request,
+    cached: CachedResponse,
+    headers: MutableHeaders,
+) -> Response:
+    if_none_match = request.headers.get('if-none-match', None)
+    if if_none_match and _if_none_match_matches(if_none_match, headers.get('etag', '')):
+        headers['content-length'] = '0'
+        return _build_response(
+            content=b'',
+            status_code=HTTP_304_NOT_MODIFIED,
+            headers=headers,
+            media_type=cached['media_type'],
+        )
+
+    return _build_response(
+        content=cached['content'],
+        status_code=cached['status_code'],
+        headers=headers,
+        media_type=cached['media_type'],
+    )
+
+
+def _build_response(
+    content: Buffer,
+    status_code: int,
+    headers: MutableHeaders,
+    media_type: str | None,
+) -> Response:
+    response = Response(content=content, status_code=status_code, media_type=media_type)
+    response.raw_headers = headers.raw
+    return response
+
+
+async def _cache_streaming_response(
+    response: StreamingResponse,
+) -> tuple[CachedResponse, StreamingResponse]:
+    status_code = response.status_code
+    headers = response.headers
+    media_type = response.media_type
+
+    chunks: list[bytes] = []
+    async for chunk in response.body_iterator:
+        if isinstance(chunk, str):
+            chunks.append(chunk.encode(response.charset))
+        else:
+            chunks.append(bytes(chunk))
+    content = b''.join(chunks)
+
+    _ensure_etag(headers, content)
+
+    cached: CachedResponse = {
+        'content': content,
+        'media_type': media_type,
+        'raw_headers': list(response.raw_headers),
+        'status_code': status_code,
+    }
+
+    response = StreamingResponse(
+        _content_stream(content),
+        status_code=status_code,
+        headers=headers,
+        media_type=media_type,
+    )
+
+    return cached, response
+
+
+async def _content_stream(content: bytes) -> AsyncGenerator[bytes, None]:
+    b = 0
+    for e in range(b, len(content), 10240):
+        yield content[b:e]
+        b = e
+    yield content[b:]
+
+
+def _ensure_etag(headers: MutableHeaders | dict[str, str], content: Buffer) -> None:
+    name = 'etag'
+    if any(header.lower() == name for header in headers):
+        return
+    etag = sha256(content, usedforsecurity=False).hexdigest()
+    headers[name] = f'"{etag}"'
+
+
+def _if_none_match_matches(if_none_match: str, etag: str) -> bool:
+    if not etag:
+        return False
+
+    etag_value = _normalize_etag(etag)
+    if etag_value is None:
+        return False
+
+    for candidate in _split_etag_header(if_none_match):
+        if candidate == '*':
+            return True
+        if _normalize_etag(candidate) == etag_value:
+            return True
+    return False
+
+
+def _normalize_etag(etag: str) -> str | None:
+    etag = etag.strip()
+    weak_prefix_len = 2
+    if etag[:weak_prefix_len].upper() == 'W/':
+        etag = etag[weak_prefix_len:].lstrip()
+    quoted_etag_len = 2
+    if len(etag) >= quoted_etag_len and etag[0] == '"' and etag[-1] == '"':
+        return etag
+    return None
+
+
+def _split_etag_header(header: str) -> list[str]:
+    items: list[str] = []
+    start = 0
+    in_quotes = False
+    escaped = False
+    for idx, char in enumerate(header):
+        if escaped:
+            escaped = False
+            continue
+        if char == '\\' and in_quotes:
+            escaped = True
+            continue
+        if char == '"':
+            in_quotes = not in_quotes
+            continue
+        if char == ',' and not in_quotes:
+            items.append(header[start:idx].strip())
+            start = idx + 1
+    items.append(header[start:].strip())
+    return [item for item in items if item]
+
+
+def _normalize_header_names(headers: Sequence[str]) -> tuple[str, ...]:
+    stripped = (header.strip() for header in headers)
+    return tuple(dict.fromkeys(header.lower() for header in stripped if header))
+
+
+def _merge_header_names(*headers: Sequence[str]) -> tuple[str, ...]:
+    merged: list[str] = []
+    seen: set[str] = set()
+    for header_group in headers:
+        for header in _normalize_header_names(header_group):
+            if header not in seen:
+                seen.add(header)
+                merged.append(header)
+    return tuple(merged)
+
+
+def _get_vary_headers(headers: MutableHeaders | dict[str, str]) -> tuple[str, ...] | None:
+    vary = headers.get('vary', '')
+    if not vary:
+        return ()
+
+    vary_headers = _normalize_header_names(vary.split(','))
+    if '*' in vary_headers:
+        return None
+    return vary_headers
+
+
+def _add_vary_header(headers: MutableHeaders | dict[str, str], vary_headers: Sequence[str]) -> None:
+    vary_headers = _normalize_header_names(vary_headers)
+    if not vary_headers:
+        return
+
+    existing_vary_headers = _get_vary_headers(headers)
+    if existing_vary_headers is None:
+        return
+
+    merged = _merge_header_names(existing_vary_headers, vary_headers)
+    headers['vary'] = ', '.join(merged)

fastapi_caching_route-0.6.0.dist-info/METADATA

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: fastapi-caching-route
+Version: 0.6.0
+Summary: FastAPI route for efficient caching.
+Project-URL: Homepage, https://github.com/AgroDT/fastapi-caching-route
+Project-URL: Repository, https://github.com/AgroDT/fastapi-caching-route.git
+Project-URL: Issues, https://github.com/AgroDT/fastapi-caching-route/issues
+Project-URL: Documentation, https://agrodt.github.io/fastapi-caching-route/
+Project-URL: Coverage, https://coveralls.io/github/AgroDT/fastapi-caching-route
+Author-email: Petr Tsymbarovich <petr@tsymbarovich.ru>
+License-File: LICENSE
+Classifier: Framework :: FastAPI
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: aiocache<1.0,>=0.12
+Description-Content-Type: text/markdown
+
+# FastAPI Caching Route
+
+[![PR Checks](https://github.com/AgroDT/fastapi-caching-route/actions/workflows/pr.yaml/badge.svg)](https://github.com/AgroDT/fastapi-caching-route/actions/workflows/pr.yaml)
+[![Coverage](https://github.com/AgroDT/fastapi-caching-route/actions/workflows/coverage.yaml/badge.svg)](https://github.com/AgroDT/fastapi-caching-route/actions/workflows/coverage.yaml)
+[![Coverage Status](https://coveralls.io/repos/github/AgroDT/fastapi-caching-route/badge.svg)](https://coveralls.io/github/AgroDT/fastapi-caching-route)
+[![Docs](https://github.com/AgroDT/fastapi-caching-route/actions/workflows/deploy-docs.yaml/badge.svg)](https://github.com/AgroDT/fastapi-caching-route/actions/workflows/deploy-docs.yaml)
+[![PyPI](https://img.shields.io/pypi/v/fastapi-caching-route.svg)](https://pypi.org/project/fastapi-caching-route/)
+
+FastAPI route class for response caching before entering the endpoint handler.
+
+`fastapi-caching-route` plugs into `fastapi.APIRouter`, stores complete response
+payloads in an `aiocache` backend, and serves cache hits directly from the route
+handler. It is useful for expensive read endpoints where the cache key can be
+derived from the request path, query parameters, or a custom key builder.
+
+**⚠️ This project is a proof of concept and is not yet recommended for production use!**
+
+## Features
+
+- Cache regular FastAPI responses and `StreamingResponse` bodies.
+- Return `X-Cache: MISS` for stored responses and `X-Cache: HIT` for cache hits.
+- Generate `ETag` headers for cached responses.
+- Return `304 Not Modified` for matching `If-None-Match` requests.
+- Build default cache keys from the route path and declared query parameters.
+- Provide custom key builders for path parameters or application-specific keys.
+- Include selected request headers in default cache keys for negotiated responses.
+- Run explicitly configured dependencies before cache lookup, for example API key
+  checks.
+- Pass `namespace` and `ttl` through to the underlying `aiocache` backend.
+- Manually invalidate cached values through `FastAPICache.invalidate_cached()`.
+
+## Installation
+
+```sh
+uv add fastapi-caching-route
+```
+
+```sh
+pip install fastapi-caching-route
+```
+
+Install FastAPI and a cache backend that matches your application. For local
+development or tests, `aiocache.SimpleMemoryCache` is enough:
+
+```sh
+uv add fastapi aiocache
+```
+
+```sh
+pip install fastapi aiocache
+```
+
+## Basic Usage
+
+Use `CachingRoute` as the router route class and decorate endpoints with
+`FastAPICache`.
+
+```py
+from aiocache import SimpleMemoryCache
+from fastapi import APIRouter, FastAPI
+from fastapi_caching_route import CachingRoute, FastAPICache
+
+
+router = APIRouter(route_class=CachingRoute)
+cache = FastAPICache(SimpleMemoryCache())
+
+
+@cache()
+@router.get('/')
+def cached() -> str:
+    return 'Hello, World!'
+
+
+app = FastAPI()
+app.include_router(router)
+```
+
+Start an app with this route and call it twice. The first response is produced by
+the endpoint and stored in the cache:
+
+```text
+X-Cache: MISS
+```
+
+The second response is returned from the cache before the endpoint handler is
+called:
+
+```text
+X-Cache: HIT
+```
+
+Routes decorated with `@cache()` must be registered on a router that uses
+`CachingRoute`. A plain `APIRoute` ignores the cache configuration.
+
+## Cache Keys
+
+By default, the cache key is built from the request path and declared query
+parameters. Query parameter order is normalized, so these two requests hit the
+same cache entry when the endpoint declares `a` and `b`:
+
+```text
+/query?a=a&b=b
+/query?b=b&a=a
+```
+
+Use a custom key builder when the cache key should be based on path parameters,
+headers, user context, or another application-specific value.
+
+```py
+from fastapi import Request
+
+
+def user_key_builder(request: Request) -> str:
+    user_id = request.scope['path_params']['user_id']
+    return f'user:{user_id}'
+
+
+@cache(key_builder=user_key_builder, ttl=60, namespace='users')
+@router.get('/users/{user_id}')
+def get_user(user_id: int) -> dict[str, int]:
+    return {'id': user_id}
+```
+
+`ttl` and `namespace` are passed to `aiocache`. When the underlying cache instance
+also has a namespace, `FastAPICache` concatenates the root and endpoint namespace
+by default:
+
+```py
+cache = FastAPICache(RedisCache(namespace='api'))
+
+
+@cache(namespace='users')
+@router.get('/users/{user_id}')
+def get_user(user_id: int): ...
+
+
+# Resulting namespace: "api:users"
+```
+
+Pass `namespace_policy="replace"` to `FastAPICache` if endpoint namespaces should
+replace the root namespace instead.
+
+If the response representation depends on request headers, include those headers
+in the default cache key with `vary_headers`. The route also returns a matching
+`Vary` header:
+
+```py
+@cache(vary_headers=['Accept-Language'])
+@router.get('/localized')
+def localized(request: Request) -> str:
+    return request.headers.get('accept-language', 'en')
+```
+
+Responses with `Vary: *` are not cached.
+
+## Dependencies Before Cache Lookup
+
+FastAPI dependencies on the route still run on cache misses. If a dependency
+must also be resolved before cache lookup, pass it to `@cache(dependencies=...)`.
+This is mainly useful for security dependencies that should reject unauthorized
+requests before a cached response can be served.
+
+```py
+from fastapi import Depends
+from fastapi.security import APIKeyHeader
+
+
+api_key = Depends(APIKeyHeader(name='X-Key'))
+
+
+@cache(dependencies=[api_key])
+@router.get('/private', dependencies=[api_key])
+def private_data() -> str:
+    return 'secret'
+```
+
+Keep the dependency on the route as well if it must be enforced for cache misses.
+
+## Conditional Requests
+
+Cached responses without an existing `ETag` get one based on the response body.
+If the endpoint already sets `ETag`, that value is preserved. On a cache hit,
+requests with a matching `If-None-Match` header return `304 Not Modified` with an
+empty body. `If-None-Match` supports weak tags, tag lists, and `*`.
+
+```sh
+curl http://127.0.0.1:8000/cached -H 'If-None-Match: "..."'
+```
+
+## Invalidation
+
+Use the same key builder logic when invalidating cache entries after writes.
+
+```py
+from fastapi import Request
+
+
+def user_cache_key(user_id: int) -> str:
+    return f'user:{user_id}'
+
+
+def user_key_builder(request: Request) -> str:
+    return user_cache_key(request.scope['path_params']['user_id'])
+
+
+@cache(key_builder=user_key_builder)
+@router.get('/users/{user_id}')
+def get_user(user_id: int): ...
+
+
+@router.patch('/users/{user_id}')
+async def update_user(user_id: int) -> dict[str, int]:
+    await cache.invalidate_cached(user_cache_key(user_id))
+    return {'id': user_id}
+```
+
+`invalidate_cached()` returns the number of deleted keys reported by the
+underlying cache backend.
+
+## Examples
+
+The repository contains runnable examples:
+
+- `examples/simple.py`: minimal cached route.
+- `examples/complex.py`: cache hits and misses, auth dependency, ETag handling,
+  streaming response caching, query parameter keys, and non-cacheable responses.
+- `examples/invalidate.py`: custom key builder and manual invalidation after an
+  update.
+
+Follow the detailed walkthrough in the examples README.

fastapi_caching_route-0.6.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+fastapi_caching_route/__init__.py,sha256=58kkpUUo0H5rf-JOHWU5vYXqRoDu9qKGHO986Ue0aoo,221
+fastapi_caching_route/_version.py,sha256=_JBFR15qMP_R2Doh1BNcX8m1yeXUGAmTM3CZn1PAu3g,18
+fastapi_caching_route/_version.pyi,sha256=GxQ4ZGLPQObN92QW_Hb8IJPEuYINNn186FjrRovM09g,13
+fastapi_caching_route/main.py,sha256=8I5mv3xFhwP_BEqFGAAeuqeCpr3oJEfKE8rjMURyEJY,18569
+fastapi_caching_route/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastapi_caching_route-0.6.0.dist-info/METADATA,sha256=C4M36JNTtEV2b8Gcbi7grBXRfOZ0nH7kR_jEpqCwlFY,7988
+fastapi_caching_route-0.6.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+fastapi_caching_route-0.6.0.dist-info/licenses/LICENSE,sha256=FlY1dZdSVly5VFy3nEK6NlAmTAQzqy8AS8oLr4hL0gI,1074
+fastapi_caching_route-0.6.0.dist-info/RECORD,,

fastapi_caching_route-0.6.0.dist-info/WHEEL

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

fastapi_caching_route-0.6.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Petr Tsymbarovich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.