Bump towncrier from 22.12.0 to 24.8.0

Bumps [towncrier](https://github.com/twisted/towncrier) from 22.12.0 to 24.8.0.
- [Release notes](https://github.com/twisted/towncrier/releases)
- [Changelog](https://github.com/twisted/towncrier/blob/trunk/NEWS.rst)
- [Commits](https://github.com/twisted/towncrier/compare/22.12.0...24.8.0)

---
updated-dependencies:
- dependency-name: towncrier
  dependency-type: direct:development
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>

.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+- package-ecosystem: pip
+  directory: "/"
+  schedule:
+    interval: daily
+  open-pull-requests-limit: 10
+  target-branch: main
+- package-ecosystem: github-actions
+  directory: "/"
+  schedule:
+    interval: daily
+  open-pull-requests-limit: 10
+  target-branch: main

.github/workflows/ci-cd.yml

@@ -0,0 +1,118 @@
+name: CI/CD
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  lint:
+    name: Linter
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install Poetry
+        run: pipx install poetry
+      - name: Setup Python
+        id: setup-python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+          cache: poetry
+      - name: Cache mypy cache
+        uses: actions/cache@v3
+        with:
+          path: .mypy_cache
+          key: ${{ runner.os }}-mypy-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('poetry.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-mypy-${{ steps.setup-python.outputs.python-version }}-
+            ${{ runner.os }}-mypy-
+      - name: Install linting requirements
+        run: poetry install --no-root
+      - name: Execute linters
+        run: make lint
+
+  test:
+    needs:
+      - lint
+    strategy:
+      matrix:
+        python: ["3.8", "3.9", "3.10", "3.11"]
+      fail-fast: false
+
+    name: "Test on Python ${{ matrix.python }}"
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install Poetry
+        run: pipx install poetry
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "${{ matrix.python }}"
+          cache: poetry
+      - name: Install testing requirements
+        run: |
+          poetry install --no-root
+          poetry run pip install tox-gh-actions
+      - name: Execute tests
+        run: poetry run tox
+
+  test-summary:
+    name: Test matrix status
+    runs-on: ubuntu-latest
+    needs: [test]
+    if: always()
+    steps:
+      - name: Decide whether the needed jobs succeeded or failed
+        uses: re-actors/alls-green@release/v1
+        with:
+          jobs: ${{ toJSON(needs) }}
+
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    needs: [test-summary]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Install Poetry
+        run: pipx install poetry
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+          cache: poetry
+      - name: Build distributions
+        run:
+          make build
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: dist
+          path: dist
+
+  publish:
+    name: Build and publish Python 🐍 distributions 📦 to PyPI
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      # The URL is used in the 'successfully deployed' message as the link
+      # for the 'View deployment' button.
+      url: https://pypi.org/p/fastapi-cache2
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v2
+        with:
+          name: dist
+          path: dist
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/ci.yml

@@ -1,15 +0,0 @@
-name: ci
-on: [ push, pull_request ]
-jobs:
-  ci:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
-        with:
-          python-version: "3.x"
-      - uses: abatilo/actions-poetry@v2.1.6
-      - name: Config poetry
-        run: poetry config experimental.new-installer false
-      - name: CI
-        run: make ci

.github/workflows/codeql.yml

@@ -0,0 +1,34 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [ "main" ]
+  schedule:
+    - cron: '29 15 * * 5'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v3
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v2
+      with:
+        languages: python
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v2
+      with:
+        category: "/language:python"

.github/workflows/dependabot-auto-merge.yml

@@ -0,0 +1,35 @@
+name: Dependabot auto-merge
+on: pull_request_target
+
+permissions:
+  pull-requests: write
+  contents: write
+
+jobs:
+  dependabot:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.user.login == 'dependabot[bot]'
+    steps:
+      - name: Dependabot metadata
+        id: dependabot-metadata
+        uses: dependabot/fetch-metadata@v1
+
+      - uses: actions/checkout@v3
+      - name: Approve PR
+        # only auto-approve direct deps that are minor or patch updates
+        #   dependency type is indirect, direct:development or direct:production
+        #   version-update is semver-major, semver-minor or semver-patch
+        if: |
+          steps.dependabot-metadata.outputs.dependency-type != 'indirect'
+          && steps.dependabot-metadata.outputs.update-type != 'version-update:semver-major'
+        run: |
+          if [ "$(gh pr view "$PR_URL" --json reviewDecision -q .reviewDecision)" != "APPROVED" ]; then
+            gh pr review --approve "$PR_URL"
+          else
+            echo "PR already approved, skipping additional approvals to minimize emails/notification noise."
+          fi
+          gh pr merge --auto --squash "$PR_URL"
+          gh pr edit "$PR_URL" --add-label "auto-merge"
+        env:
+          PR_URL: ${{github.event.pull_request.html_url}}
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

.github/workflows/labeller.yaml

@@ -0,0 +1,30 @@
+name: Labeller
+on:
+  pull_request_target:
+    types:
+      - auto_merge_disabled
+      - auto_merge_enabled
+  
+permissions: {}
+
+jobs:
+  add_remove_labels:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Add auto-merge label
+        if: github.event.action == 'auto_merge_enabled'
+        run: gh pr edit "$PR_URL" --add-label "auto-merge"
+        env:
+          PR_URL: ${{github.event.pull_request.html_url}}
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+
+      - name: Remove auto-merge label
+        if: github.event.action == 'auto_merge_disabled'
+        run: gh pr edit "$PR_URL" --remove-label "auto-merge"
+        env:
+          PR_URL: ${{github.event.pull_request.html_url}}
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

.github/workflows/pypi.yml

@@ -1,23 +0,0 @@
-name: pypi
-on:
-  release:
-    types:
-      - created
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v1
-        with:
-          python-version: '3.x'
-      - uses: abatilo/actions-poetry@v2.1.3
-      - name: Config poetry
-        run: poetry config experimental.new-installer false
-      - name: Build dists
-        run: make build
-      - name: Pypi Publish
-        uses: pypa/gh-action-pypi-publish@master
-        with:
-          user: __token__
-          password: ${{ secrets.pypi_password }}

.github/workflows/towncrier.yml

@@ -0,0 +1,54 @@
+name: Changelog
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - labeled
+      - unlabeled
+    branches:
+      - main
+
+jobs:
+  towncrier:
+    name: Towncrier
+    runs-on: ubuntu-latest
+    # skip if this is a bot or the PR has the skip-changelog label
+    # note that the towncrier check command can recognize a release PR, by looking
+    # for changes to the CHANGELOG.md file.
+    if: |
+      !(
+           github.event.pull_request.user.login == 'dependabot[bot]'
+        || contains(github.event.pull_request.labels.*.name, 'skip-changelog')
+      )
+    steps:
+    - uses: actions/checkout@v2
+    - name: Install Poetry
+      run: pipx install poetry
+    - name: Setup Python
+      id: setup-python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
+        cache: poetry
+    - name: Install development tools
+      run: poetry install --no-root --only=dev
+    - name: Check for a towncrier fragment
+      run: |
+        # fetch enough commits from this merge commit to the base sha to ensure
+        # towncrier can inspect what changed
+        while [[ -z $(git merge-base $PR_BASE_SHA HEAD 2> /dev/null) ]]; do
+          git fetch --quiet --deepen=50 --no-tags --no-recurse-submodules origin $PR_BASE_SHA HEAD
+        done
+        if poetry run towncrier check --compare-with $PR_BASE_SHA; then
+          gh pr edit "$PR_URL" --add-label "changelog-provided"
+        else
+          gh pr edit "$PR_URL" --remove-label "changelog-provided"
+          exit 1
+        fi
+
+      env:
+        PR_BASE_SHA: ${{github.event.pull_request.base.sha}}
+        PR_URL: ${{github.event.pull_request.html_url}}
+        GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

.gitignore

@@ -28,6 +28,9 @@ share/python-wheels/
 *.egg
 MANIFEST
 
+# Ruff
+.ruff_cache/
+
 # PyInstaller
 #  Usually these files are written by a python script from a template
 #  before PyInstaller builds the exe, so as to inject date/other infos into it.

CHANGELOG.md

@@ -1,7 +1,21 @@
 # ChangeLog
 
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+This project uses [*towncrier*](https://towncrier.readthedocs.io/) and the changes for the upcoming release can be found in <https://github.com/long2ice/fastapi-cache/tree/main/changelog.d/>.
+
+<!-- towncrier release notes start -->
+
 ## 0.2
 
+### 0.2.1
+- Fix picklecoder
+- Fix connection failure transparency and add logging
+- Add Cache-Control and ETag on first response
+- Support Async RedisCluster client from redis-py
+
 ### 0.2.0
 
 - Make `request` and `response` optional.

Makefile

@@ -1,27 +1,28 @@
-checkfiles = fastapi_cache/ examples/ tests/
-py_warn = PYTHONDEVMODE=1
-
 up:
 	@poetry update
 
 deps:
-	@poetry install --no-root -E all
+	@poetry install --no-root --with=linting --all-extras
 
-style: deps
+format: deps
-	@poetry run isort -src $(checkfiles)
+	@poetry run tox run -e format
-	@poetry run black $(checkfiles)
 
-check: deps
+lint: deps
-	@poetry run black $(checkfiles) || (echo "Please run 'make style' to auto-fix style issues" && false)
+	@poetry run tox run -e lint
-	@poetry run flake8 $(checkfiles)
 
 test: deps
-	$(py_warn) poetry run pytest
+	@poetry run tox
+
+test-parallel: deps
+	@poetry run tox run-parallel
 
 build: clean deps
 	@poetry build
+	@poetry run tox run -e lint_distributions
 
 clean:
 	@rm -rf ./dist
 
-ci: check test
+# aliases
+check: lint
+style: format

README.md

@@ -1,27 +1,26 @@
 # fastapi-cache
 
-![pypi](https://img.shields.io/pypi/v/fastapi-cache2.svg?style=flat)
+[![pypi](https://img.shields.io/pypi/v/fastapi-cache2.svg?style=flat)](https://pypi.org/p/fastapi-cache2)
-![license](https://img.shields.io/github/license/long2ice/fastapi-cache)
+[![license](https://img.shields.io/github/license/long2ice/fastapi-cache)](https://github.com/long2ice/fastapi-cache/blob/main/LICENSE)
-![workflows](https://github.com/long2ice/fastapi-cache/workflows/pypi/badge.svg)
+[![CI/CD](https://github.com/long2ice/fastapi-cache/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/long2ice/fastapi-cache/actions/workflows/ci-cd.yml)
-![workflows](https://github.com/long2ice/fastapi-cache/workflows/ci/badge.svg)
 
 ## Introduction
 
-`fastapi-cache` is a tool to cache fastapi response and function result, with backends support `redis`, `memcache`,
+`fastapi-cache` is a tool to cache FastAPI endpoint and function results, with
-and `dynamodb`.
+backends supporting Redis, Memcached, and Amazon DynamoDB.
 
 ## Features
 
-- Support `redis`, `memcache`, `dynamodb`, and `in-memory` backends.
+- Supports `redis`, `memcache`, `dynamodb`, and `in-memory` backends.
-- Easily integration with `fastapi`.
+- Easy integration with [FastAPI](https://fastapi.tiangolo.com/).
-- Support http cache like `ETag` and `Cache-Control`.
+- Support for HTTP cache headers like `ETag` and `Cache-Control`, as well as conditional `If-Match-None` requests.
 
 ## Requirements
 
-- `asyncio` environment.
+- FastAPI
-- `redis` if use `RedisBackend`.
+- `redis` when using `RedisBackend`.
-- `memcache` if use `MemcacheBackend`.
+- `memcache` when using `MemcacheBackend`.
-- `aiobotocore` if use `DynamoBackend`.
+- `aiobotocore` when using `DynamoBackend`.
 
 ## Install
 
@@ -52,6 +51,9 @@ or
 ### Quick Start
 
 ```python
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
 from fastapi import FastAPI
 from starlette.requests import Request
 from starlette.responses import Response
@@ -62,7 +64,15 @@ from fastapi_cache.decorator import cache
 
 from redis import asyncio as aioredis
 
-app = FastAPI()
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+    redis = aioredis.from_url("redis://localhost")
+    FastAPICache.init(RedisBackend(redis), prefix="fastapi-cache")
+    yield
+
+
+app = FastAPI(lifespan=lifespan)
 
 
 @cache()
@@ -74,32 +84,63 @@ async def get_cache():
 @cache(expire=60)
 async def index():
     return dict(hello="world")
-
-
-@app.on_event("startup")
-async def startup():
-    redis = aioredis.from_url("redis://localhost", encoding="utf8", decode_responses=True)
-    FastAPICache.init(RedisBackend(redis), prefix="fastapi-cache")
-
 ```
 
 ### Initialization
 
-Firstly you must call `FastAPICache.init` on startup event of `fastapi`, there are some global config you can pass in.
+First you must call `FastAPICache.init` during startup FastAPI startup; this is where you set global configuration.
 
-### Use `cache` decorator
+### Use the `@cache` decorator
 
-If you want cache `fastapi` response transparently, you can use `cache` as decorator between router decorator and view
+If you want cache a FastAPI response transparently, you can use the `@cache`
-function and must pass `request` as param of view function.
+decorator between the router decorator and the view function.
 
-Parameter | type, description
+Parameter | type | default | description
------------- | -------------
+------------ | ----| --------- | --------
-expire | int, states a caching time in seconds
+`expire` | `int` |  | sets the caching time in seconds
-namespace | str, namespace to use to store certain cache items
+`namespace` | `str` | `""` | namespace to use to store certain cache items
-coder | which coder to use, e.g. JsonCoder
+`coder` | `Coder` | `JsonCoder` | which coder to use, e.g. `JsonCoder`
-key_builder | which key builder to use, default to builtin
+`key_builder` | `KeyBuilder` callable | `default_key_builder` | which key builder to use
+`injected_dependency_namespace` | `str` | `__fastapi_cache` | prefix for injected dependency keywords.
+`cache_status_header` | `str` | `X-FastAPI-Cache` | Name for the header on the response indicating if the request was served from cache; either `HIT` or `MISS`.
 
-You can also use `cache` as decorator like other cache tools to cache common function result.
+You can also use the `@cache` decorator on regular functions to cache their result.
+
+### Injected Request and Response dependencies
+
+The `cache` decorator injects dependencies for the `Request` and `Response`
+objects, so that it can add cache control headers to the outgoing response, and
+return a 304 Not Modified response when the incoming request has a matching
+`If-Non-Match` header. This only happens if the decorated endpoint doesn't already
+list these dependencies already.
+
+The keyword arguments for these extra dependencies are named
+`__fastapi_cache_request` and `__fastapi_cache_response` to minimize collisions.
+Use the `injected_dependency_namespace` argument to `@cache` to change the
+prefix used if those names would clash anyway.
+
+
+### Supported data types
+
+When using the (default) `JsonCoder`, the cache can store any data type that FastAPI can convert to JSON, including Pydantic models and dataclasses,
+_provided_ that your endpoint has a correct return type annotation. An
+annotation is not needed if the return type is a standard JSON-supported Python
+type such as a dictionary or a list.
+
+E.g. for an endpoint that returns a Pydantic model named `SomeModel`, the return annotation is used to ensure that the cached result is converted back to the correct class:
+
+```python
+from .models import SomeModel, create_some_model
+
+@app.get("/foo")
+@cache(expire=60)
+async def foo() -> SomeModel:
+    return create_some_model()
+```
+
+It is not sufficient to configure a response model in the route decorator; the cache needs to know what the method itself returns. If no return type decorator is given, the primitive JSON type is returned instead.
+
+For broader type support, use the `fastapi_cache.coder.PickleCoder` or implement a custom coder (see below).
 
 ### Custom coder
 
@@ -107,41 +148,78 @@ By default use `JsonCoder`, you can write custom coder to encode and decode cach
 inherit `fastapi_cache.coder.Coder`.
 
 ```python
+from typing import Any
+import orjson
+from fastapi.encoders import jsonable_encoder
+from fastapi_cache import Coder
+
+class ORJsonCoder(Coder):
+    @classmethod
+    def encode(cls, value: Any) -> bytes:
+        return orjson.dumps(
+            value,
+            default=jsonable_encoder,
+            option=orjson.OPT_NON_STR_KEYS | orjson.OPT_SERIALIZE_NUMPY,
+        )
+
+    @classmethod
+    def decode(cls, value: bytes) -> Any:
+        return orjson.loads(value)
+
+
 @app.get("/")
-@cache(expire=60, coder=JsonCoder)
+@cache(expire=60, coder=ORJsonCoder)
 async def index():
     return dict(hello="world")
 ```
 
 ### Custom key builder
 
-By default use builtin key builder, if you need, you can override this and pass in `cache` or `FastAPICache.init` to
+By default the `default_key_builder` builtin key builder is used; this creates a
-take effect globally.
+cache key from the function module and name, and the positional and keyword
+arguments converted to their `repr()` representations, encoded as a MD5 hash.
+You can provide your own by passing a key builder in to `@cache()`, or to
+`FastAPICache.init()` to apply globally.
+
+For example, if you wanted to use the request method, URL and query string as a cache key instead of the function identifier you could use:
 
 ```python
-def my_key_builder(
+def request_key_builder(
     func,
-        namespace: Optional[str] = "",
+    namespace: str = "",
+    *,
     request: Request = None,
     response: Response = None,
     *args,
     **kwargs,
 ):
-    prefix = FastAPICache.get_prefix()
+    return ":".join([
-    cache_key = f"{prefix}:{namespace}:{func.__module__}:{func.__name__}:{args}:{kwargs}"
+        namespace,
-    return cache_key
+        request.method.lower(),
+        request.url.path,
+        repr(sorted(request.query_params.items()))
+    ])
 
 
 @app.get("/")
-@cache(expire=60, coder=JsonCoder, key_builder=my_key_builder)
+@cache(expire=60, key_builder=request_key_builder)
 async def index():
     return dict(hello="world")
 ```
 
+## Backend notes
+
 ### InMemoryBackend
 
-`InMemoryBackend` store cache data in memory and use lazy delete, which mean if you don't access it after cached, it
+The `InMemoryBackend` stores cache data in memory and only deletes when an
-will not delete automatically.
+expired key is accessed. This means that if you don't access a function after
+data has been cached, the data will not be removed automatically.
+
+### RedisBackend
+
+When using the Redis backend, please make sure you pass in a redis client that does [_not_ decode responses][redis-decode] (`decode_responses` **must** be `False`, which is the default). Cached data is stored as `bytes` (binary), decoding these in the Redis client would break caching.
+
+[redis-decode]: https://redis-py.readthedocs.io/en/latest/examples/connection_examples.html#by-default-Redis-return-binary-responses,-to-decode-them-use-decode_responses=True
 
 ## Tests and coverage
 

changelog.d/172.feature.md

@@ -0,0 +1 @@
+Use `importlib.metadata` to include project version string as `fastapi_cache.__version__`.

changelog.d/changelog_template.jinja

@@ -0,0 +1,15 @@
+{% if sections[""] -%}
+{% for category, val in definitions.items() if category in sections[""] -%}
+
+### {{ definitions[category]['name'] }}
+
+{% for text, values in sections[""][category].items() %}
+- {{ text }} {{ values|join(', ') }}
+{% endfor %}
+
+{% endfor -%}
+{% else -%}
+No significant changes.
+
+
+{% endif -%}

examples/in_memory/main.py

@@ -1,14 +1,25 @@
+# pyright: reportGeneralTypeIssues=false
+from contextlib import asynccontextmanager
+from typing import AsyncIterator, Dict, Optional
+
 import pendulum
 import uvicorn
 from fastapi import FastAPI
-from starlette.requests import Request
-from starlette.responses import JSONResponse, Response
-
 from fastapi_cache import FastAPICache
 from fastapi_cache.backends.inmemory import InMemoryBackend
 from fastapi_cache.decorator import cache
+from pydantic import BaseModel
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
 
-app = FastAPI()
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+    FastAPICache.init(InMemoryBackend())
+    yield
+
+
+app = FastAPI(lifespan=lifespan)
 
 ret = 0
 
@@ -23,7 +34,7 @@ async def get_ret():
 @app.get("/")
 @cache(namespace="test", expire=10)
 async def index():
-    return dict(ret=await get_ret())
+    return {"ret": await get_ret()}
 
 
 @app.get("/clear")
@@ -43,8 +54,18 @@ async def get_datetime(request: Request, response: Response):
     return {"now": pendulum.now()}
 
 
-@app.get("/sync-me")
 @cache(namespace="test")
+async def func_kwargs(*unused_args, **kwargs):
+    return kwargs
+
+
+@app.get("/kwargs")
+async def get_kwargs(name: str):
+    return await func_kwargs(name, name=name)
+
+
+@app.get("/sync-me")
+@cache(namespace="test") # pyright: ignore[reportArgumentType]
 def sync_me():
     # as per the fastapi docs, this sync function is wrapped in a thread,
     # thereby converted to async. fastapi-cache does the same.
@@ -57,10 +78,63 @@ async def cache_response_obj():
     return JSONResponse({"a": 1})
 
 
-@app.on_event("startup")
+class SomeClass:
-async def startup():
+    def __init__(self, value):
-    FastAPICache.init(InMemoryBackend())
+        self.value = value
+
+    async def handler_method(self):
+        return self.value
+
+
+# register an instance method as a handler
+instance = SomeClass(17)
+app.get("/method")(cache(namespace="test")(instance.handler_method))
+
+
+# cache a Pydantic model instance; the return type annotation is required in this case
+class Item(BaseModel):
+    name: str
+    description: Optional[str] = None
+    price: float
+    tax: Optional[float] = None
+
+
+@app.get("/pydantic_instance")
+@cache(namespace="test", expire=5)
+async def pydantic_instance() -> Item:
+    return Item(name="Something", description="An instance of a Pydantic model", price=10.5)
+
+
+put_ret = 0
+
+
+@app.put("/uncached_put")
+@cache(namespace="test", expire=5)
+async def uncached_put():
+    global put_ret
+    put_ret = put_ret + 1
+    return {"value": put_ret}
+
+put_ret2 = 0
+
+@app.get("/cached_put")
+@cache(namespace="test", expire=5)
+async def cached_put():
+    global put_ret2
+    put_ret2 = put_ret2 + 1
+    return {"value": put_ret2}
+
+
+@app.get("/namespaced_injection")
+@cache(namespace="test", expire=5, injected_dependency_namespace="monty_python") # pyright: ignore[reportArgumentType]
+def namespaced_injection(
+    __fastapi_cache_request: int = 42, __fastapi_cache_response: int = 17
+) -> Dict[str, int]:
+    return {
+        "__fastapi_cache_request": __fastapi_cache_request,
+        "__fastapi_cache_response": __fastapi_cache_response,
+    }
 
 
 if __name__ == "__main__":
-    uvicorn.run("main:app", debug=True, reload=True)
+    uvicorn.run("main:app", reload=True)

examples/pyproject.toml

@@ -0,0 +1,3 @@
+[tool.ruff]
+extend = "../pyproject.toml"
+

examples/redis/main.py

@@ -1,22 +1,34 @@
+# pyright: reportGeneralTypeIssues=false
 import time
+from contextlib import asynccontextmanager
+from typing import AsyncIterator
 
 import pendulum
-import redis.asyncio as redis
 import uvicorn
 from fastapi import FastAPI
 from fastapi.responses import HTMLResponse
 from fastapi.staticfiles import StaticFiles
 from fastapi.templating import Jinja2Templates
-from redis.asyncio.connection import ConnectionPool
-from starlette.requests import Request
-from starlette.responses import JSONResponse, Response
-
 from fastapi_cache import FastAPICache
 from fastapi_cache.backends.redis import RedisBackend
 from fastapi_cache.coder import PickleCoder
 from fastapi_cache.decorator import cache
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
 
-app = FastAPI()
+import redis.asyncio as redis
+from redis.asyncio.connection import ConnectionPool
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+    pool = ConnectionPool.from_url(url="redis://redis")
+    r = redis.Redis(connection_pool=pool)
+    FastAPICache.init(RedisBackend(r), prefix="fastapi-cache")
+    yield
+
+
+app = FastAPI(lifespan=lifespan)
 
 app.mount(
     path="/static",
@@ -37,7 +49,7 @@ async def get_ret():
 @app.get("/")
 @cache(namespace="test", expire=10)
 async def index():
-    return dict(ret=await get_ret())
+    return {"ret": await get_ret()}
 
 
 @app.get("/clear")
@@ -54,10 +66,10 @@ async def get_data(request: Request, response: Response):
 # Note: This function MUST be sync to demonstrate fastapi-cache's correct handling,
 # i.e. running cached sync functions in threadpool just like FastAPI itself!
 @app.get("/blocking")
-@cache(namespace="test", expire=10)
+@cache(namespace="test", expire=10) # pyright: ignore[reportArgumentType]
 def blocking():
     time.sleep(2)
-    return dict(ret=42)
+    return {"ret": 42}
 
 
 @app.get("/datetime")
@@ -79,12 +91,5 @@ async def cache_response_obj():
     return JSONResponse({"a": 1})
 
 
-@app.on_event("startup")
-async def startup():
-    pool = ConnectionPool.from_url(url="redis://redis")
-    r = redis.Redis(connection_pool=pool)
-    FastAPICache.init(RedisBackend(r), prefix="fastapi-cache")
-
-
 if __name__ == "__main__":
-    uvicorn.run("main:app", debug=True, reload=True)
+    uvicorn.run("main:app", reload=True)

fastapi_cache/__init__.py

@@ -1,18 +1,30 @@
-from typing import Callable, Optional, Type
+from importlib.metadata import version
+from typing import ClassVar, Optional, Type
 
-from fastapi_cache.backends import Backend
 from fastapi_cache.coder import Coder, JsonCoder
 from fastapi_cache.key_builder import default_key_builder
+from fastapi_cache.types import Backend, KeyBuilder
+
+__version__ = version("fastapi-cache2")  # pyright: ignore[reportUnknownVariableType]
+__all__ = [
+    "Backend",
+    "Coder",
+    "FastAPICache",
+    "JsonCoder",
+    "KeyBuilder",
+    "default_key_builder",
+]
 
 
 class FastAPICache:
-    _backend: Optional[Backend] = None
+    _backend: ClassVar[Optional[Backend]] = None
-    _prefix: Optional[str] = None
+    _prefix: ClassVar[Optional[str]] = None
-    _expire: Optional[int] = None
+    _expire: ClassVar[Optional[int]] = None
-    _init = False
+    _init: ClassVar[bool] = False
-    _coder: Optional[Type[Coder]] = None
+    _coder: ClassVar[Optional[Type[Coder]]] = None
-    _key_builder: Optional[Callable] = None
+    _key_builder: ClassVar[Optional[KeyBuilder]] = None
-    _enable = True
+    _cache_status_header: ClassVar[Optional[str]] = None
+    _enable: ClassVar[bool] = True
 
     @classmethod
     def init(
@@ -21,7 +33,8 @@ class FastAPICache:
         prefix: str = "",
         expire: Optional[int] = None,
         coder: Type[Coder] = JsonCoder,
-        key_builder: Callable = default_key_builder,
+        key_builder: KeyBuilder = default_key_builder,
+        cache_status_header: str = "X-FastAPI-Cache",
         enable: bool = True,
     ) -> None:
         if cls._init:
@@ -32,6 +45,7 @@ class FastAPICache:
         cls._expire = expire
         cls._coder = coder
         cls._key_builder = key_builder
+        cls._cache_status_header = cache_status_header
         cls._enable = enable
 
     @classmethod
@@ -42,16 +56,17 @@ class FastAPICache:
         cls._expire = None
         cls._coder = None
         cls._key_builder = None
+        cls._cache_status_header = None
         cls._enable = True
 
     @classmethod
     def get_backend(cls) -> Backend:
-        assert cls._backend, "You must call init first!"  # nosec: B101
+        assert cls._backend, "You must call init first!"  # noqa: S101
         return cls._backend
 
     @classmethod
     def get_prefix(cls) -> str:
-        assert cls._prefix is not None, "You must call init first!"  # nosec: B101
+        assert cls._prefix is not None, "You must call init first!"  # noqa: S101
         return cls._prefix
 
     @classmethod
@@ -60,20 +75,29 @@ class FastAPICache:
 
     @classmethod
     def get_coder(cls) -> Type[Coder]:
-        assert cls._coder, "You must call init first!"  # nosec: B101
+        assert cls._coder, "You must call init first!"  # noqa: S101
         return cls._coder
 
     @classmethod
-    def get_key_builder(cls) -> Callable:
+    def get_key_builder(cls) -> KeyBuilder:
-        assert cls._key_builder, "You must call init first!"  # nosec: B101
+        assert cls._key_builder, "You must call init first!"  # noqa: S101
         return cls._key_builder
 
+    @classmethod
+    def get_cache_status_header(cls) -> str:
+        assert cls._cache_status_header, "You must call init first!"  # noqa: S101
+        return cls._cache_status_header
+
     @classmethod
     def get_enable(cls) -> bool:
         return cls._enable
 
     @classmethod
-    async def clear(cls, namespace: Optional[str] = None, key: Optional[str] = None) -> int:
+    async def clear(
-        assert cls._backend and cls._prefix is not None, "You must call init first!"  # nosec: B101
+        cls, namespace: Optional[str] = None, key: Optional[str] = None
+    ) -> int:
+        assert (  # noqa: S101
+            cls._backend and cls._prefix is not None
+        ), "You must call init first!"
         namespace = cls._prefix + (":" + namespace if namespace else "")
         return await cls._backend.clear(namespace, key)

fastapi_cache/backends/__init__.py

@@ -1,20 +1,28 @@
-import abc
+from fastapi_cache.backends import inmemory
-from typing import Optional, Tuple
+from fastapi_cache.types import Backend
 
+__all__ = ["Backend", "inmemory"]
 
-class Backend:
+# import each backend in turn and add to __all__. This syntax
-    @abc.abstractmethod
+# is explicitly supported by type checkers, while more dynamic
-    async def get_with_ttl(self, key: str) -> Tuple[int, Optional[str]]:
+# syntax would not be recognised.
-        raise NotImplementedError
+try:
+    from fastapi_cache.backends import dynamodb
+except ImportError:
+    pass
+else:
+    __all__ += ["dynamodb"]
 
-    @abc.abstractmethod
+try:
-    async def get(self, key: str) -> Optional[str]:
+    from fastapi_cache.backends import memcached
-        raise NotImplementedError
+except ImportError:
+    pass
+else:
+    __all__ += ["memcached"]
 
-    @abc.abstractmethod
+try:
-    async def set(self, key: str, value: str, expire: Optional[int] = None) -> None:
+    from fastapi_cache.backends import redis
-        raise NotImplementedError
+except ImportError:
-
+    pass
-    @abc.abstractmethod
+else:
-    async def clear(self, namespace: Optional[str] = None, key: Optional[str] = None) -> int:
+    __all__ += ["redis"]
-        raise NotImplementedError

fastapi_cache/backends/dynamodb.py

@@ -1,10 +1,15 @@
 import datetime
-from typing import Optional, Tuple
+from typing import TYPE_CHECKING, Optional, Tuple
 
 from aiobotocore.client import AioBaseClient
-from aiobotocore.session import get_session
+from aiobotocore.session import AioSession, get_session
 
-from fastapi_cache.backends import Backend
+from fastapi_cache.types import Backend
+
+if TYPE_CHECKING:
+    from types_aiobotocore_dynamodb import DynamoDBClient
+else:
+    DynamoDBClient = AioBaseClient
 
 
 class DynamoBackend(Backend):
@@ -25,25 +30,29 @@ class DynamoBackend(Backend):
         >> FastAPICache.init(dynamodb)
     """
 
+    client: DynamoDBClient
+    session: AioSession
+    table_name: str
+    region: Optional[str]
+
     def __init__(self, table_name: str, region: Optional[str] = None) -> None:
-        self.session = get_session()
+        self.session: AioSession = get_session()
-        self.client: Optional[AioBaseClient] = None  # Needs async init
         self.table_name = table_name
         self.region = region
 
     async def init(self) -> None:
-        self.client = await self.session.create_client(
+        self.client = await self.session.create_client(  # pyright: ignore[reportUnknownMemberType]
             "dynamodb", region_name=self.region
         ).__aenter__()
 
     async def close(self) -> None:
         self.client = await self.client.__aexit__(None, None, None)
 
-    async def get_with_ttl(self, key: str) -> Tuple[int, str]:
+    async def get_with_ttl(self, key: str) -> Tuple[int, Optional[bytes]]:
         response = await self.client.get_item(TableName=self.table_name, Key={"key": {"S": key}})
 
         if "Item" in response:
-            value = response["Item"].get("value", {}).get("S")
+            value = response["Item"].get("value", {}).get("B")
             ttl = response["Item"].get("ttl", {}).get("N")
 
             if not ttl:
@@ -56,12 +65,13 @@ class DynamoBackend(Backend):
 
         return 0, None
 
-    async def get(self, key: str) -> str:
+    async def get(self, key: str) -> Optional[bytes]:
         response = await self.client.get_item(TableName=self.table_name, Key={"key": {"S": key}})
         if "Item" in response:
-            return response["Item"].get("value", {}).get("S")
+            return response["Item"].get("value", {}).get("B")
+        return None
 
-    async def set(self, key: str, value: str, expire: Optional[int] = None) -> None:
+    async def set(self, key: str, value: bytes, expire: Optional[int] = None) -> None:
         ttl = (
             {
                 "ttl": {
@@ -83,7 +93,7 @@ class DynamoBackend(Backend):
             Item={
                 **{
                     "key": {"S": key},
-                    "value": {"S": value},
+                    "value": {"B": value},
                 },
                 **ttl,
             },

fastapi_cache/backends/inmemory.py

@@ -3,12 +3,12 @@ from asyncio import Lock
 from dataclasses import dataclass
 from typing import Dict, Optional, Tuple
 
-from fastapi_cache.backends import Backend
+from fastapi_cache.types import Backend
 
 
 @dataclass
 class Value:
-    data: str
+    data: bytes
     ttl_ts: int
 
 
@@ -29,21 +29,21 @@ class InMemoryBackend(Backend):
                 return v
         return None
 
-    async def get_with_ttl(self, key: str) -> Tuple[int, Optional[str]]:
+    async def get_with_ttl(self, key: str) -> Tuple[int, Optional[bytes]]:
         async with self._lock:
             v = self._get(key)
             if v:
                 return v.ttl_ts - self._now, v.data
             return 0, None
 
-    async def get(self, key: str) -> Optional[str]:
+    async def get(self, key: str) -> Optional[bytes]:
         async with self._lock:
             v = self._get(key)
             if v:
                 return v.data
             return None
 
-    async def set(self, key: str, value: str, expire: Optional[int] = None) -> None:
+    async def set(self, key: str, value: bytes, expire: Optional[int] = None) -> None:
         async with self._lock:
             self._store[key] = Value(value, self._now + (expire or 0))
 

fastapi_cache/backends/memcached.py

@@ -2,21 +2,21 @@ from typing import Optional, Tuple
 
 from aiomcache import Client
 
-from fastapi_cache.backends import Backend
+from fastapi_cache.types import Backend
 
 
 class MemcachedBackend(Backend):
     def __init__(self, mcache: Client):
         self.mcache = mcache
 
-    async def get_with_ttl(self, key: str) -> Tuple[int, Optional[str]]:
+    async def get_with_ttl(self, key: str) -> Tuple[int, Optional[bytes]]:
-        return 3600, await self.mcache.get(key.encode())
+        return 3600, await self.get(key)
 
-    async def get(self, key: str) -> Optional[str]:
+    async def get(self, key: str) -> Optional[bytes]:
-        return await self.mcache.get(key, key.encode())
+        return await self.mcache.get(key.encode())
 
-    async def set(self, key: str, value: str, expire: Optional[int] = None) -> None:
+    async def set(self, key: str, value: bytes, expire: Optional[int] = None) -> None:
-        await self.mcache.set(key.encode(), value.encode(), exptime=expire or 0)
+        await self.mcache.set(key.encode(), value, exptime=expire or 0)
 
     async def clear(self, namespace: Optional[str] = None, key: Optional[str] = None) -> int:
         raise NotImplementedError

fastapi_cache/backends/redis.py

@@ -1,28 +1,30 @@
-from typing import Optional, Tuple
+from typing import Optional, Tuple, Union
 
 from redis.asyncio.client import Redis
+from redis.asyncio.cluster import RedisCluster
 
-from fastapi_cache.backends import Backend
+from fastapi_cache.types import Backend
 
 
 class RedisBackend(Backend):
-    def __init__(self, redis: Redis):
+    def __init__(self, redis: Union["Redis[bytes]", "RedisCluster[bytes]"]):
         self.redis = redis
+        self.is_cluster: bool = isinstance(redis, RedisCluster)
 
-    async def get_with_ttl(self, key: str) -> Tuple[int, str]:
+    async def get_with_ttl(self, key: str) -> Tuple[int, Optional[bytes]]:
-        async with self.redis.pipeline(transaction=True) as pipe:
+        async with self.redis.pipeline(transaction=not self.is_cluster) as pipe:
-            return await (pipe.ttl(key).get(key).execute())
+            return await pipe.ttl(key).get(key).execute()  # type: ignore[union-attr,no-any-return]
 
-    async def get(self, key: str) -> Optional[str]:
+    async def get(self, key: str) -> Optional[bytes]:
-        return await self.redis.get(key)
+        return await self.redis.get(key)  # type: ignore[union-attr]
 
-    async def set(self, key: str, value: str, expire: Optional[int] = None) -> None:
+    async def set(self, key: str, value: bytes, expire: Optional[int] = None) -> None:
-        return await self.redis.set(key, value, ex=expire)
+        await self.redis.set(key, value, ex=expire)  # type: ignore[union-attr]
 
     async def clear(self, namespace: Optional[str] = None, key: Optional[str] = None) -> int:
         if namespace:
             lua = f"for i, name in ipairs(redis.call('KEYS', '{namespace}:*')) do redis.call('DEL', name); end"
-            return await self.redis.eval(lua, numkeys=0)
+            return await self.redis.eval(lua, numkeys=0)  # type: ignore[union-attr,no-any-return]
         elif key:
-            return await self.redis.delete(key)
+            return await self.redis.delete(key)  # type: ignore[union-attr]
         return 0

fastapi_cache/coder.py

@@ -2,14 +2,33 @@ import datetime
 import json
 import pickle  # nosec:B403
 from decimal import Decimal
-from typing import Any
+from typing import (
+    Any,
+    Callable,
+    ClassVar,
+    Dict,
+    Optional,
+    TypeVar,
+    Union,
+    overload,
+)
 
 import pendulum
 from fastapi.encoders import jsonable_encoder
 from starlette.responses import JSONResponse
-from starlette.templating import _TemplateResponse as TemplateResponse
+from starlette.templating import (
+    _TemplateResponse as TemplateResponse,  # pyright: ignore[reportPrivateUsage]
+)
 
-CONVERTERS = {
+
+class ModelField:
+    pass
+
+_T = TypeVar("_T", bound=type)
+
+
+CONVERTERS: Dict[str, Callable[[str], Any]] = {
+    # Pendulum 3.0.0 adds parse to __all__, at which point these ignores can be removed
     "date": lambda x: pendulum.parse(x, exact=True),
     "datetime": lambda x: pendulum.parse(x, exact=True),
     "decimal": Decimal,
@@ -17,15 +36,15 @@ CONVERTERS = {
 
 
 class JsonEncoder(json.JSONEncoder):
-    def default(self, obj: Any) -> Any:
+    def default(self, o: Any) -> Any:
-        if isinstance(obj, datetime.datetime):
+        if isinstance(o, datetime.datetime):
-            return {"val": str(obj), "_spec_type": "datetime"}
+            return {"val": str(o), "_spec_type": "datetime"}
-        elif isinstance(obj, datetime.date):
+        elif isinstance(o, datetime.date):
-            return {"val": str(obj), "_spec_type": "date"}
+            return {"val": str(o), "_spec_type": "date"}
-        elif isinstance(obj, Decimal):
+        elif isinstance(o, Decimal):
-            return {"val": str(obj), "_spec_type": "decimal"}
+            return {"val": str(o), "_spec_type": "decimal"}
         else:
-            return jsonable_encoder(obj)
+            return jsonable_encoder(o)
 
 
 def object_hook(obj: Any) -> Any:
@@ -34,40 +53,77 @@ def object_hook(obj: Any) -> Any:
         return obj
 
     if _spec_type in CONVERTERS:
-        return CONVERTERS[_spec_type](obj["val"])  # type: ignore
+        return CONVERTERS[_spec_type](obj["val"])
     else:
-        raise TypeError("Unknown {}".format(_spec_type))
+        raise TypeError(f"Unknown {_spec_type}")
 
 
 class Coder:
     @classmethod
-    def encode(cls, value: Any) -> str:
+    def encode(cls, value: Any) -> bytes:
         raise NotImplementedError
 
     @classmethod
-    def decode(cls, value: Any) -> Any:
+    def decode(cls, value: bytes) -> Any:
         raise NotImplementedError
 
+    # (Shared) cache for endpoint return types to Pydantic model fields.
+    # Note that subclasses share this cache! If a subclass overrides the
+    # decode_as_type method and then stores a different kind of field for a
+    # given type, do make sure that the subclass provides its own class
+    # attribute for this cache.
+    _type_field_cache: ClassVar[Dict[Any, ModelField]] = {}
+
+    @overload
+    @classmethod
+    def decode_as_type(cls, value: bytes, *, type_: _T) -> _T:
+        ...
+
+    @overload
+    @classmethod
+    def decode_as_type(cls, value: bytes, *, type_: None) -> Any:
+        ...
+
+    @classmethod
+    def decode_as_type(cls, value: bytes, *, type_: Optional[_T]) -> Union[_T, Any]:
+        """Decode value to the specific given type
+
+        The default implementation uses the Pydantic model system to convert the value.
+
+        """
+        result = cls.decode(value)
+        return result
+
 
 class JsonCoder(Coder):
     @classmethod
-    def encode(cls, value: Any) -> str:
+    def encode(cls, value: Any) -> Any:
         if isinstance(value, JSONResponse):
             return value.body
-        return json.dumps(value, cls=JsonEncoder)
+        return json.dumps(value, cls=JsonEncoder).encode()
 
     @classmethod
-    def decode(cls, value: Any) -> str:
+    def decode(cls, value: bytes) -> Any:
-        return json.loads(value, object_hook=object_hook)
+        # explicitly decode from UTF-8 bytes first, as otherwise
+        # json.loads() will first have to detect the correct UTF-
+        # encoding used.
+        return json.loads(value.decode(), object_hook=object_hook)
 
 
 class PickleCoder(Coder):
     @classmethod
-    def encode(cls, value: Any) -> str:
+    def encode(cls, value: Any) -> bytes:
         if isinstance(value, TemplateResponse):
             value = value.body
-        return str(pickle.dumps(value))
+        return pickle.dumps(value)
 
     @classmethod
-    def decode(cls, value: Any) -> Any:
+    def decode(cls, value: bytes) -> Any:
-        return pickle.loads(bytes(value))  # nosec:B403,B301
+        return pickle.loads(value)  # noqa: S301
+
+    @classmethod
+    def decode_as_type(cls, value: bytes, *, type_: Optional[_T]) -> Any:
+        # Pickle already produces the correct type on decoding, no point
+        # in paying an extra performance penalty for pydantic to discover
+        # the same.
+        return cls.decode(value)

fastapi_cache/decorator.py

@@ -1,7 +1,17 @@
-import inspect
+import logging
 import sys
 from functools import wraps
-from typing import Any, Awaitable, Callable, Optional, Type, TypeVar
+from inspect import Parameter, Signature, isawaitable, iscoroutinefunction
+from typing import (
+    Awaitable,
+    Callable,
+    List,
+    Optional,
+    Type,
+    TypeVar,
+    Union,
+    cast,
+)
 
 if sys.version_info >= (3, 10):
     from typing import ParamSpec
@@ -9,24 +19,81 @@ else:
     from typing_extensions import ParamSpec
 
 from fastapi.concurrency import run_in_threadpool
+from fastapi.dependencies.utils import (
+    get_typed_return_annotation,
+    get_typed_signature,
+)
 from starlette.requests import Request
 from starlette.responses import Response
+from starlette.status import HTTP_304_NOT_MODIFIED
 
 from fastapi_cache import FastAPICache
 from fastapi_cache.coder import Coder
+from fastapi_cache.types import KeyBuilder
 
+logger: logging.Logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
 P = ParamSpec("P")
 R = TypeVar("R")
 
 
+def _augment_signature(signature: Signature, *extra: Parameter) -> Signature:
+    if not extra:
+        return signature
+
+    parameters = list(signature.parameters.values())
+    variadic_keyword_params: List[Parameter] = []
+    while parameters and parameters[-1].kind is Parameter.VAR_KEYWORD:
+        variadic_keyword_params.append(parameters.pop())
+
+    return signature.replace(parameters=[*parameters, *extra, *variadic_keyword_params])
+
+
+def _locate_param(
+    sig: Signature, dep: Parameter, to_inject: List[Parameter]
+) -> Parameter:
+    """Locate an existing parameter in the decorated endpoint
+
+    If not found, returns the injectable parameter, and adds it to the to_inject list.
+
+    """
+    param = next(
+        (p for p in sig.parameters.values() if p.annotation is dep.annotation), None
+    )
+    if param is None:
+        to_inject.append(dep)
+        param = dep
+    return param
+
+
+def _uncacheable(request: Optional[Request]) -> bool:
+    """Determine if this request should not be cached
+
+    Returns true if:
+    - Caching has been disabled globally
+    - This is not a GET request
+    - The request has a Cache-Control header with a value of "no-store"
+
+    """
+    if not FastAPICache.get_enable():
+        return True
+    if request is None:
+        return False
+    if request.method != "GET":
+        return True
+    return request.headers.get("Cache-Control") == "no-store"
+
+
 def cache(
     expire: Optional[int] = None,
     coder: Optional[Type[Coder]] = None,
-    key_builder: Optional[Callable[..., Any]] = None,
+    key_builder: Optional[KeyBuilder] = None,
-    namespace: Optional[str] = "",
+    namespace: str = "",
-) -> Callable[[Callable[P, Awaitable[R]]], Callable[P, Awaitable[R]]]:
+    injected_dependency_namespace: str = "__fastapi_cache",
+) -> Callable[[Callable[P, Awaitable[R]]], Callable[P, Awaitable[Union[R, Response]]]]:
     """
     cache all function
+    :param injected_dependency_namespace:
     :param namespace:
     :param expire:
     :param coder:
@@ -35,53 +102,42 @@ def cache(
     :return:
     """
 
-    def wrapper(func: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[R]]:
+    injected_request = Parameter(
-        signature = inspect.signature(func)
+        name=f"{injected_dependency_namespace}_request",
-        request_param = next(
-            (param for param in signature.parameters.values() if param.annotation is Request),
-            None,
-        )
-        response_param = next(
-            (param for param in signature.parameters.values() if param.annotation is Response),
-            None,
-        )
-        parameters = [*signature.parameters.values()]
-        if not request_param:
-            parameters.append(
-                inspect.Parameter(
-                    name="request",
         annotation=Request,
-                    kind=inspect.Parameter.KEYWORD_ONLY,
+        kind=Parameter.KEYWORD_ONLY,
-                ),
     )
-        if not response_param:
+    injected_response = Parameter(
-            parameters.append(
+        name=f"{injected_dependency_namespace}_response",
-                inspect.Parameter(
-                    name="response",
         annotation=Response,
-                    kind=inspect.Parameter.KEYWORD_ONLY,
+        kind=Parameter.KEYWORD_ONLY,
-                ),
     )
-        if parameters:
+
-            signature = signature.replace(parameters=parameters)
+    def wrapper(
-        func.__signature__ = signature
+        func: Callable[P, Awaitable[R]]
+    ) -> Callable[P, Awaitable[Union[R, Response]]]:
+        # get_typed_signature ensures that any forward references are resolved first
+        wrapped_signature = get_typed_signature(func)
+        to_inject: List[Parameter] = []
+        request_param = _locate_param(wrapped_signature, injected_request, to_inject)
+        response_param = _locate_param(wrapped_signature, injected_response, to_inject)
+        return_type = get_typed_return_annotation(func)
 
         @wraps(func)
-        async def inner(*args: P.args, **kwargs: P.kwargs) -> R:
+        async def inner(*args: P.args, **kwargs: P.kwargs) -> Union[R, Response]:
             nonlocal coder
             nonlocal expire
             nonlocal key_builder
 
             async def ensure_async_func(*args: P.args, **kwargs: P.kwargs) -> R:
                 """Run cached sync functions in thread pool just like FastAPI."""
-                # if the wrapped function does NOT have request or response in its function signature,
+                # if the wrapped function does NOT have request or response in
-                # make sure we don't pass them in as keyword arguments
+                # its function signature, make sure we don't pass them in as
-                if not request_param:
+                # keyword arguments
-                    kwargs.pop("request", None)
+                kwargs.pop(injected_request.name, None)
-                if not response_param:
+                kwargs.pop(injected_response.name, None)
-                    kwargs.pop("response", None)
 
-                if inspect.iscoroutinefunction(func):
+                if iscoroutinefunction(func):
                     # async, return as is.
                     # unintuitively, we have to await once here, so that caller
                     # does not have to await twice. See
@@ -90,76 +146,85 @@ def cache(
                 else:
                     # sync, wrap in thread and return async
                     # see above why we have to await even although caller also awaits.
-                    return await run_in_threadpool(func, *args, **kwargs)
+                    return await run_in_threadpool(func, *args, **kwargs)  # type: ignore[arg-type]
 
             copy_kwargs = kwargs.copy()
-            request: Optional[Request] = copy_kwargs.pop("request", None)
+            request: Optional[Request] = copy_kwargs.pop(request_param.name, None)  # type: ignore[assignment]
-            response: Optional[Response] = copy_kwargs.pop("response", None)
+            response: Optional[Response] = copy_kwargs.pop(response_param.name, None)  # type: ignore[assignment]
-            if (
+
-                request and request.headers.get("Cache-Control") in ("no-store", "no-cache")
+            if _uncacheable(request):
-            ) or not FastAPICache.get_enable():
                 return await ensure_async_func(*args, **kwargs)
 
+            prefix = FastAPICache.get_prefix()
             coder = coder or FastAPICache.get_coder()
             expire = expire or FastAPICache.get_expire()
             key_builder = key_builder or FastAPICache.get_key_builder()
             backend = FastAPICache.get_backend()
+            cache_status_header = FastAPICache.get_cache_status_header()
 
-            if inspect.iscoroutinefunction(key_builder):
-                cache_key = await key_builder(
-                    func,
-                    namespace,
-                    request=request,
-                    response=response,
-                    args=args,
-                    kwargs=copy_kwargs,
-                )
-            else:
             cache_key = key_builder(
                 func,
-                    namespace,
+                f"{prefix}:{namespace}",
                 request=request,
                 response=response,
                 args=args,
                 kwargs=copy_kwargs,
             )
+            if isawaitable(cache_key):
+                cache_key = await cache_key
+            assert isinstance(cache_key, str)  # noqa: S101  # assertion is a type guard
+
             try:
-                ttl, ret = await backend.get_with_ttl(cache_key)
+                ttl, cached = await backend.get_with_ttl(cache_key)
-            except ConnectionError:
+            except Exception:
-                ttl, ret = 0, None
+                logger.warning(
-            if not request:
+                    f"Error retrieving cache key '{cache_key}' from backend:",
-                if ret is not None:
+                    exc_info=True,
-                    return coder.decode(ret)
-                ret = await ensure_async_func(*args, **kwargs)
-                try:
-                    await backend.set(
-                        cache_key, coder.encode(ret), expire or FastAPICache.get_expire()
                 )
-                except ConnectionError:
+                ttl, cached = 0, None
-                    pass
-                return ret
 
-            if request.method != "GET":
+            if cached is None  or (request is not None and request.headers.get("Cache-Control") == "no-cache") :  # cache miss
-                return await ensure_async_func(request, *args, **kwargs)
+                result = await ensure_async_func(*args, **kwargs)
-
+                to_cache = coder.encode(result)
-            if_none_match = request.headers.get("if-none-match")
-            if ret is not None:
-                if response:
-                    response.headers["Cache-Control"] = f"max-age={ttl}"
-                    etag = f"W/{hash(ret)}"
-                    if if_none_match == etag:
-                        response.status_code = 304
-                        return response
-                    response.headers["ETag"] = etag
-                return coder.decode(ret)
-
-            ret = await ensure_async_func(*args, **kwargs)
 
                 try:
-                await backend.set(cache_key, coder.encode(ret), expire or FastAPICache.get_expire())
+                    await backend.set(cache_key, to_cache, expire)
-            except ConnectionError:
+                except Exception:
-                pass
+                    logger.warning(
-            return ret
+                        f"Error setting cache key '{cache_key}' in backend:",
+                        exc_info=True,
+                    )
+
+                if response:
+                    response.headers.update(
+                        {
+                            "Cache-Control": f"max-age={expire}",
+                            "ETag": f"W/{hash(to_cache)}",
+                            cache_status_header: "MISS",
+                        }
+                    )
+
+            else:  # cache hit
+                if response:
+                    etag = f"W/{hash(cached)}"
+                    response.headers.update(
+                        {
+                            "Cache-Control": f"max-age={ttl}",
+                            "ETag": etag,
+                            cache_status_header: "HIT",
+                        }
+                    )
+
+                    if_none_match = request and request.headers.get("if-none-match")
+                    if if_none_match == etag:
+                        response.status_code = HTTP_304_NOT_MODIFIED
+                        return response
+
+                result = cast(R, coder.decode_as_type(cached, type_=return_type))
+
+            return result
+
+        inner.__signature__ = _augment_signature(wrapped_signature, *to_inject)  # type: ignore[attr-defined]
 
         return inner
 

fastapi_cache/key_builder.py

@@ -1,25 +1,20 @@
 import hashlib
-from typing import Callable, Optional
+from typing import Any, Callable, Dict, Optional, Tuple
 
 from starlette.requests import Request
 from starlette.responses import Response
 
 
 def default_key_builder(
-    func: Callable,
+    func: Callable[..., Any],
-    namespace: Optional[str] = "",
+    namespace: str = "",
+    *,
     request: Optional[Request] = None,
     response: Optional[Response] = None,
-    args: Optional[tuple] = None,
+    args: Tuple[Any, ...],
-    kwargs: Optional[dict] = None,
+    kwargs: Dict[str, Any],
 ) -> str:
-    from fastapi_cache import FastAPICache
+    cache_key = hashlib.md5(  # noqa: S324
-
-    prefix = f"{FastAPICache.get_prefix()}:{namespace}:"
-    cache_key = (
-        prefix
-        + hashlib.md5(  # nosec:B303
         f"{func.__module__}:{func.__name__}:{args}:{kwargs}".encode()
     ).hexdigest()
-    )
+    return f"{namespace}:{cache_key}"
-    return cache_key

fastapi_cache/types.py

@@ -0,0 +1,40 @@
+import abc
+from typing import Any, Awaitable, Callable, Dict, Optional, Tuple, Union
+
+from starlette.requests import Request
+from starlette.responses import Response
+from typing_extensions import Protocol
+
+_Func = Callable[..., Any]
+
+
+class KeyBuilder(Protocol):
+    def __call__(
+        self,
+        __function: _Func,
+        __namespace: str = ...,
+        *,
+        request: Optional[Request] = ...,
+        response: Optional[Response] = ...,
+        args: Tuple[Any, ...],
+        kwargs: Dict[str, Any],
+    ) -> Union[Awaitable[str], str]:
+        ...
+
+
+class Backend(abc.ABC):
+    @abc.abstractmethod
+    async def get_with_ttl(self, key: str) -> Tuple[int, Optional[bytes]]:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def get(self, key: str) -> Optional[bytes]:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def set(self, key: str, value: bytes, expire: Optional[int] = None) -> None:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def clear(self, namespace: Optional[str] = None, key: Optional[str] = None) -> int:
+        raise NotImplementedError

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "fastapi-cache2"
-version = "0.2.0"
+version = "0.2.2"
 description = "Cache for FastAPI"
 authors = ["long2ice <long2ice@gmail.com>"]
 license = "Apache-2.0"
@@ -15,27 +15,39 @@ packages = [
 include = ["LICENSE", "README.md"]
 
 [tool.poetry.dependencies]
-python = "^3.7"
+python = "^3.8"
 fastapi = "*"
 uvicorn = "*"
-redis = { version = "^4.2.0rc1", optional = true }
+typing-extensions = { version = ">=4.1.0" }
-aiomcache = { version = "*", optional = true }
+importlib-metadata = { version = "^6.6.0", python = "<3.8" }
-pendulum = "*"
+pendulum = "^3.0.0"
-aiobotocore = { version = "^1.4.1", optional = true }
+aiomcache = { version = "^0.8.2", optional = true }
-typing-extensions = { version = ">=4.1.0", markers = "python_version < \"3.10\"" }
+aiobotocore = {version = "^2.13.1", optional = true}
-aiohttp = { version = ">=3.8.3", markers = "python_version >= \"3.11\"" }
+redis = {version = "^5.0.8", extras = ["redis"]}
 
-[tool.poetry.dev-dependencies]
+[tool.poetry.group.linting]
-flake8 = "*"
+optional = true
-isort = "*"
+
-black = "*"
+[tool.poetry.group.linting.dependencies]
+mypy = { version = "^1.2.0", python = "^3.10" }
+pyright = { version = "^1.1.373", python = "^3.10" }
+types-aiobotocore = { extras = ["dynamodb"], version = "^2.5.0.post2", python = "^3.10" }
+types-redis = { version = "^4.5.4.2", python = "^3.10" }
+ruff = { version = ">=0.0.267,<0.1.2", python = "^3.10" }
+
+[tool.poetry.group.dev.dependencies]
 pytest = "*"
 requests = "*"
-coverage = "^6.5.0"
+coverage = ">=6.5,<8.0"
+httpx = "*"
+tox = "^4.5.1"
+towncrier = ">=22.12,<25.0"
 
-[build-system]
+[tool.poetry.group.distributing]
-requires = ["poetry>=0.12"]
+optional = true
-build-backend = "poetry.masonry.api"
+
+[tool.poetry.group.distributing.dependencies]
+twine = { version = "^4.0.2", python = "^3.10" }
 
 [tool.poetry.extras]
 redis = ["redis"]
@@ -43,6 +55,61 @@ memcache = ["aiomcache"]
 dynamodb = ["aiobotocore"]
 all = ["redis", "aiomcache", "aiobotocore"]
 
-[tool.black]
+[tool.mypy]
-line-length = 100
+files = ["."]
-target-version = ['py36', 'py37', 'py38', 'py39']
+python_version = "3.8"
+# equivalent of --strict
+warn_unused_configs = true
+disallow_any_generics = true
+disallow_subclassing_any = true
+disallow_untyped_calls = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_return_any = true
+no_implicit_reexport = true
+strict_equality = true
+extra_checks = true
+
+[[tool.mypy.overrides]]
+module = "examples.*.main"
+ignore_errors = true
+
+[tool.towncrier]
+directory = "changelog.d"
+filename = "CHANGELOG.md"
+package = "fastapi_cache"
+start_string = "<!-- towncrier release notes start -->\n"
+underlines = ["", "", ""]
+template = "changelog.d/changelog_template.jinja"
+title_format = "## [{version}](https://github.com/long2ice/fastapi-cache/tree/{version}) - {project_date}"
+issue_format = "[#{issue}](https://github.com/long2ice/fastapi-cache/issues/{issue})"
+
+[tool.pyright]
+strict = ["fastapi_cache", "tests"]
+pythonVersion = "3.8"
+
+[tool.pytest.ini_options]
+addopts = "-p no:warnings"
+
+[tool.ruff]
+ignore = ["E501"]
+line-length = 80
+select = [
+    "B", # flake8-bugbear
+    "C4", # flake8-comprehensions
+    "E", # pycodestyle errors
+    "F", # pyflakes
+    "I", # isort
+    "S", # flake8-bandit
+    "W", # pycodestyle warnings
+    "UP", # pyupgrade
+]
+target-version = "py38"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

setup.cfg

@@ -1,5 +0,0 @@
-[flake8]
-ignore = E501,W503
-
-[tool:pytest]
-addopts = -p no:warnings

tests/pyproject.toml

@@ -0,0 +1,10 @@
+[tool.ruff]
+extend = "../pyproject.toml"
+extend-select = [
+    "PT", # flake8-pytest-style
+]
+ignore = ["S101"]
+
+[tool.ruff.isort]
+known-first-party = ["examples", "fastapi_cache"]
+

tests/test_codecs.py

@@ -0,0 +1,66 @@
+from dataclasses import dataclass
+from typing import Any, Optional, Tuple, Type
+
+import pytest
+from pydantic import BaseModel, ValidationError
+
+from fastapi_cache.coder import JsonCoder, PickleCoder
+
+
+@dataclass
+class DCItem:
+    name: str
+    price: float
+    description: Optional[str] = None
+    tax: Optional[float] = None
+
+
+class PDItem(BaseModel):
+    name: str
+    price: float
+    description: Optional[str] = None
+    tax: Optional[float] = None
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        1,
+        "some_string",
+        (1, 2),
+        [1, 2, 3],
+        {"some_key": 1, "other_key": 2},
+        DCItem(name="foo", price=42.0, description="some dataclass item", tax=0.2),
+        PDItem(name="foo", price=42.0, description="some pydantic item", tax=0.2),
+    ],
+)
+def test_pickle_coder(value: Any) -> None:
+    encoded_value = PickleCoder.encode(value)
+    assert isinstance(encoded_value, bytes)
+    decoded_value = PickleCoder.decode(encoded_value)
+    assert decoded_value == value
+
+
+@pytest.mark.parametrize(
+    ("value", "return_type"),
+    [
+        (1, None),
+        ("some_string", None),
+        ((1, 2), Tuple[int, int]),
+        ([1, 2, 3], None),
+        ({"some_key": 1, "other_key": 2}, None),
+        (DCItem(name="foo", price=42.0, description="some dataclass item", tax=0.2), DCItem),
+        (PDItem(name="foo", price=42.0, description="some pydantic item", tax=0.2), PDItem),
+    ],
+)
+def test_json_coder(value: Any, return_type: Type[Any]) -> None:
+    encoded_value = JsonCoder.encode(value)
+    assert isinstance(encoded_value, bytes)
+    decoded_value = JsonCoder.decode_as_type(encoded_value, type_=return_type)
+    assert decoded_value == value
+
+
+def test_json_coder_validation_error() -> None:
+    invalid = b'{"name": "incomplete"}'
+    with pytest.raises(ValidationError):
+        JsonCoder.decode_as_type(invalid, type_=PDItem)

tests/test_decorator.py

@@ -1,5 +1,5 @@
 import time
-from typing import Generator
+from typing import Any, Generator
 
 import pendulum
 import pytest
@@ -11,7 +11,7 @@ from fastapi_cache.backends.inmemory import InMemoryBackend
 
 
 @pytest.fixture(autouse=True)
-def init_cache() -> Generator:
+def _init_cache() -> Generator[Any, Any, None]:  # pyright: ignore[reportUnusedFunction]
     FastAPICache.init(InMemoryBackend())
     yield
     FastAPICache.reset()
@@ -20,36 +20,41 @@ def init_cache() -> Generator:
 def test_datetime() -> None:
     with TestClient(app) as client:
         response = client.get("/datetime")
+        assert response.headers.get("X-FastAPI-Cache") == "MISS"
         now = response.json().get("now")
-        now_ = pendulum.now().replace(microsecond=0)
+        now_ = pendulum.now()
-        assert pendulum.parse(now).replace(microsecond=0) == now_
+        assert pendulum.parse(now) == now_
         response = client.get("/datetime")
+        assert response.headers.get("X-FastAPI-Cache") == "HIT"
         now = response.json().get("now")
-        assert pendulum.parse(now).replace(microsecond=0) == now_
+        assert pendulum.parse(now) == now_
         time.sleep(3)
         response = client.get("/datetime")
         now = response.json().get("now")
-        now = pendulum.parse(now).replace(microsecond=0)
+        assert response.headers.get("X-FastAPI-Cache") == "MISS"
+        now = pendulum.parse(now)
         assert now != now_
-        assert now == pendulum.now().replace(microsecond=0)
+        assert now == pendulum.now()
 
 
 def test_date() -> None:
     """Test path function without request or response arguments."""
     with TestClient(app) as client:
-
         response = client.get("/date")
+        assert response.headers.get("X-FastAPI-Cache") == "MISS"
         assert pendulum.parse(response.json()) == pendulum.today()
 
         # do it again to test cache
         response = client.get("/date")
+        assert response.headers.get("X-FastAPI-Cache") == "HIT"
         assert pendulum.parse(response.json()) == pendulum.today()
 
         # now test with cache disabled, as that's a separate code path
-        FastAPICache._enable = False
+        FastAPICache._enable = False  # pyright: ignore[reportPrivateUsage]
         response = client.get("/date")
+        assert "X-FastAPI-Cache" not in response.headers
         assert pendulum.parse(response.json()) == pendulum.today()
-        FastAPICache._enable = True
+        FastAPICache._enable = True # pyright: ignore[reportPrivateUsage]
 
 
 def test_sync() -> None:
@@ -67,3 +72,66 @@ def test_cache_response_obj() -> None:
         assert get_cache_response.json() == {"a": 1}
         assert get_cache_response.headers.get("cache-control")
         assert get_cache_response.headers.get("etag")
+
+
+def test_kwargs() -> None:
+    with TestClient(app) as client:
+        name = "Jon"
+        response = client.get("/kwargs", params={"name": name})
+        assert "X-FastAPI-Cache" not in response.headers
+        assert response.json() == {"name": name}
+
+
+def test_method() -> None:
+    with TestClient(app) as client:
+        response = client.get("/method")
+        assert response.json() == 17
+
+
+def test_pydantic_model() -> None:
+    with TestClient(app) as client:
+        r1 = client.get("/pydantic_instance")
+        assert r1.headers.get("X-FastAPI-Cache") == "MISS"
+        r2 = client.get("/pydantic_instance")
+        assert r2.headers.get("X-FastAPI-Cache") == "HIT"
+        assert r1.json() == r2.json()
+
+
+def test_non_get() -> None:
+    with TestClient(app) as client:
+        response = client.put("/cached_put")
+        assert "X-FastAPI-Cache" not in response.headers
+        assert response.json() == {"value": 1}
+        response = client.put("/cached_put")
+        assert "X-FastAPI-Cache" not in response.headers
+        assert response.json() == {"value": 2}
+
+
+def test_alternate_injected_namespace() -> None:
+    with TestClient(app) as client:
+        response = client.get("/namespaced_injection")
+        assert response.headers.get("X-FastAPI-Cache") == "MISS"
+        assert response.json() == {"__fastapi_cache_request": 42, "__fastapi_cache_response": 17}
+
+def test_cache_control() -> None:
+    with TestClient(app) as client:
+        response = client.get("/cached_put")
+        assert response.json() == {"value": 1}
+
+        # HIT
+        response = client.get("/cached_put")
+        assert response.json() == {"value": 1}
+
+        # no-cache
+        response = client.get("/cached_put", headers={"Cache-Control": "no-cache"})
+        assert response.json() == {"value": 2}
+
+        response = client.get("/cached_put")
+        assert response.json() == {"value": 2}
+
+        # no-store
+        response = client.get("/cached_put", headers={"Cache-Control": "no-store"})
+        assert response.json() == {"value": 3}
+
+        response = client.get("/cached_put")
+        assert response.json() == {"value": 2}

tox.ini

@@ -0,0 +1,51 @@
+[tox]
+env_list = py38,py39,py310,py311
+minversion = 4.5.1
+
+[gh-actions]
+# Map Github Actions Python version to environment factors
+# Requires tox-gh-actions 3.x is installed in the GitHub action
+python =
+    3.8: py38
+    3.9: py39
+    3.10: py310
+    3.11: py311
+
+[testenv]
+description = Run the tests with pytest
+package = wheel
+extras = all
+set_env =
+    # trick poetry into adopting the tox virtualenv
+    POETRY_VIRTUALENVS_PATH = {[tox]work_dir}
+allowlist_externals = poetry
+commands_pre =
+    poetry install --no-root --sync --all-extras
+commands =
+    python -X dev -m pytest {tty:--color=yes} {posargs}
+
+[testenv:lint]
+description = Run the linters
+skip_install = true
+commands_pre =
+    poetry install --no-root --with=linting --sync --all-extras
+commands =
+    ruff check --show-source .
+    mypy
+    pyright
+
+[testenv:format]
+description = Format the code
+skip_install = true
+commands_pre =
+    poetry install --no-root --sync --with=linting
+commands =
+    ruff check --fix .
+
+[testenv:lint_distributions]
+description = Lint distribution files with Twine
+skip_install = true
+commands_pre =
+    poetry install --no-root --sync --only=distributing
+commands =
+    twine check dist/*