Update README.md

fix #424, no-cache should store the result to cache

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+custom: ["https://sponsor.long2ice.io"]
+

.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,16 +0,0 @@
-name: ci
-on: [ push, pull_request ]
-jobs:
-  ci:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
-        with:
-          python-version: "3.x"
-      - name: Install and configure Poetry
-        uses: snok/install-poetry@v1.1.1
-        with:
-          virtualenvs-create: 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,21 +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: dschep/install-poetry-action@v1.3
-      - 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,66 @@
 # 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.
+- Add typing info to the `cache` decorator.
+- Support cache jinja2 template response.
+- Support cache `JSONResponse`
+- Add `py.typed` file and type hints
+- Add TestCase
+- Fix cache decorate sync function
+- Transparently handle backend connection failures.
+
 ## 0.1
 
+### 0.1.10
+
+- Add `Cache-Control:no-cache` support.
+
+### 0.1.9
+
+- Replace `aioredis` with `redis-py`.
+
+### 0.1.8
+
+- Support `dynamodb` backend.
+
+### 0.1.7
+
+- Fix default json coder for datetime.
+- Add `enable` param to `init`.
+
+### 0.1.6
+
+- Fix redis cache.
+- Encode key builder.
+
+### 0.1.5
+
+- Fix setting expire for redis (#24)
+- Update expire key
+
+### 0.1.4
+
+- Fix default expire for memcached. (#13)
+- Update default key builder. (#12)
+
 ### 0.1.3
 
 - Fix cache key builder.

Makefile

@@ -1,38 +1,28 @@
-checkfiles = fastapi_cache/ examples/ tests/
-black_opts = -l 100 -t py38
-py_warn = PYTHONDEVMODE=1
-
-help:
-	@echo "FastAPI-Cache development makefile"
-	@echo
-	@echo  "usage: make <target>"
-	@echo  "Targets:"
-	@echo  "    up			Ensure dev/test dependencies are updated"
-	@echo  "    deps		Ensure dev/test dependencies are installed"
-	@echo  "    check		Checks that build is sane"
-	@echo  "    test		Runs all tests"
-	@echo  "    style		Auto-formats the code"
-	@echo  "    build		Build package"
-
 up:
 	@poetry update
 
 deps:
-	@poetry install --no-root -E all
+	@poetry install --no-root --with=linting --all-extras
 
-style: deps
+format: deps
-	@isort -src $(checkfiles)
+	@poetry run tox run -e format
-	@black $(black_opts) $(checkfiles)
 
-check: deps
+lint: deps
-	@black --check $(black_opts) $(checkfiles) || (echo "Please run 'make style' to auto-fix style issues" && false)
+	@poetry run tox run -e lint
-	@flake8 $(checkfiles)
-	@bandit -r $(checkfiles)
 
 test: deps
-	$(py_warn) pytest
+	@poetry run tox
 
-build: deps
+test-parallel: deps
+	@poetry run tox run-parallel
+
+build: clean deps
 	@poetry build
+	@poetry run tox run -e lint_distributions
 
-ci: check test
+clean:
+	@rm -rf ./dist
+
+# aliases
+check: lint
+style: format

README.md

@@ -1,25 +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` and `memcache`.
+`fastapi-cache` is a tool to cache FastAPI endpoint and function results, with
+backends supporting Redis, Memcached, and Amazon DynamoDB.
 
 ## Features
 
-- Support `redis` and `memcache` 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` when using `DynamoBackend`.
 
 ## Install
 
@@ -30,13 +31,19 @@
 or
 
 ```shell
-> pip install fastapi-cache2[redis]
+> pip install "fastapi-cache2[redis]"
 ```
 
 or
 
 ```shell
-> pip install fastapi-cache2[memcache]
+> pip install "fastapi-cache2[memcache]"
+```
+
+or
+
+```shell
+> pip install "fastapi-cache2[dynamodb]"
 ```
 
 ## Usage
@@ -44,7 +51,9 @@ or
 ### Quick Start
 
 ```python
-import aioredis
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
 from fastapi import FastAPI
 from starlette.requests import Request
 from starlette.responses import Response
@@ -53,7 +62,17 @@ from fastapi_cache import FastAPICache
 from fastapi_cache.backends.redis import RedisBackend
 from fastapi_cache.decorator import cache
 
-app = FastAPI()
+from redis import asyncio as aioredis
+
+
+@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()
@@ -63,67 +82,157 @@ async def get_cache():
 
 @app.get("/")
 @cache(expire=60)
-async def index(request: Request, response: Response):
+async def index():
     return dict(hello="world")
-
-
-@app.on_event("startup")
-async def startup():
-    redis = await aioredis.create_redis_pool("redis://localhost", encoding="utf8")
-    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 function and must pass `request` as param of view function.
+If you want cache a FastAPI response transparently, you can use the `@cache`
+decorator between the router decorator and the view function.
 
-And if you want use `ETag` and `Cache-Control` features, you must pass `response` param also.
+Parameter | type | default | description
+------------ | ----| --------- | --------
+`expire` | `int` |  | sets the caching time in seconds
+`namespace` | `str` | `""` | namespace to use to store certain cache items
+`coder` | `Coder` | `JsonCoder` | which coder to use, e.g. `JsonCoder`
+`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
 
-By default use `JsonCoder`, you can write custom coder to encode and decode cache result, just need inherit `fastapi_cache.coder.Coder`.
+By default use `JsonCoder`, you can write custom coder to encode and decode cache result, just need
+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(request: Request, response: Response):
+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 take effect globally.
+By default the `default_key_builder` builtin key builder is used; this creates a
+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(request: Request, response: Response):
+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 will not delete automatically.
+The `InMemoryBackend` stores cache data in memory and only deletes when an
+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
+
+```shell
+coverage run -m pytest
+coverage html
+xdg-open htmlcov/index.html
+```
 
 ## License
 
 This project is licensed under the [Apache-2.0](https://github.com/long2ice/fastapi-cache/blob/master/LICENSE) License.
+
+## Sponsor
+
+[![Powered by DartNode](https://dartnode.com/branding/DN-Open-Source-sm.png)](https://dartnode.com "Powered by DartNode - Free VPS for Open Source")

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

@@ -0,0 +1,140 @@
+# pyright: reportGeneralTypeIssues=false
+from contextlib import asynccontextmanager
+from typing import AsyncIterator, Dict, Optional
+
+import pendulum
+import uvicorn
+from fastapi import FastAPI
+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
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+    FastAPICache.init(InMemoryBackend())
+    yield
+
+
+app = FastAPI(lifespan=lifespan)
+
+ret = 0
+
+
+@cache(namespace="test", expire=1)
+async def get_ret():
+    global ret
+    ret = ret + 1
+    return ret
+
+
+@app.get("/")
+@cache(namespace="test", expire=10)
+async def index():
+    return {"ret": await get_ret()}
+
+
+@app.get("/clear")
+async def clear():
+    return await FastAPICache.clear(namespace="test")
+
+
+@app.get("/date")
+@cache(namespace="test", expire=10)
+async def get_date():
+    return pendulum.today()
+
+
+@app.get("/datetime")
+@cache(namespace="test", expire=2)
+async def get_datetime(request: Request, response: Response):
+    return {"now": pendulum.now()}
+
+
+@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.
+    return 42
+
+
+@app.get("/cache_response_obj")
+@cache(namespace="test", expire=5)
+async def cache_response_obj():
+    return JSONResponse({"a": 1})
+
+
+class SomeClass:
+    def __init__(self, value):
+        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", reload=True)

examples/main.py

@@ -1,39 +0,0 @@
-import uvicorn
-from fastapi import FastAPI
-from starlette.requests import Request
-from starlette.responses import Response
-
-from fastapi_cache import FastAPICache
-from fastapi_cache.backends.inmemory import InMemoryBackend
-from fastapi_cache.decorator import cache
-
-app = FastAPI()
-
-ret = 0
-
-
-@cache(namespace="test", expire=1)
-async def get_ret():
-    global ret
-    ret = ret + 1
-    return ret
-
-
-@app.get("/")
-@cache(namespace="test", expire=2)
-async def index(request: Request, response: Response):
-    return dict(ret=await get_ret())
-
-
-@app.get("/clear")
-async def clear():
-    return await FastAPICache.clear(namespace="test")
-
-
-@app.on_event("startup")
-async def startup():
-    FastAPICache.init(InMemoryBackend(), prefix="fastapi-cache")
-
-
-if __name__ == "__main__":
-    uvicorn.run("main:app", debug=True, reload=True)

examples/pyproject.toml

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

examples/redis/index.html

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Title</title>
+</head>
+<body>
+<h1>Cache HTML! {{ ret }} </h1>
+</body>
+</html>

examples/redis/main.py

@@ -0,0 +1,95 @@
+# pyright: reportGeneralTypeIssues=false
+import time
+from contextlib import asynccontextmanager
+from typing import AsyncIterator
+
+import pendulum
+import uvicorn
+from fastapi import FastAPI
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.templating import Jinja2Templates
+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
+
+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",
+    app=StaticFiles(directory="./"),
+    name="static",
+)
+templates = Jinja2Templates(directory="./")
+ret = 0
+
+
+@cache(namespace="test", expire=1)
+async def get_ret():
+    global ret
+    ret = ret + 1
+    return ret
+
+
+@app.get("/")
+@cache(namespace="test", expire=10)
+async def index():
+    return {"ret": await get_ret()}
+
+
+@app.get("/clear")
+async def clear():
+    return await FastAPICache.clear(namespace="test")
+
+
+@app.get("/date")
+@cache(namespace="test", expire=10)
+async def get_data(request: Request, response: Response):
+    return pendulum.today()
+
+
+# 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) # pyright: ignore[reportArgumentType]
+def blocking():
+    time.sleep(2)
+    return {"ret": 42}
+
+
+@app.get("/datetime")
+@cache(namespace="test", expire=2)
+async def get_datetime(request: Request, response: Response):
+    print(request, response)
+    return pendulum.now()
+
+
+@app.get("/html", response_class=HTMLResponse)
+@cache(expire=60, namespace="html", coder=PickleCoder)
+async def cache_html(request: Request):
+    return templates.TemplateResponse("index.html", {"request": request, "ret": await get_ret()})
+
+
+@app.get("/cache_response_obj")
+@cache(namespace="test", expire=5)
+async def cache_response_obj():
+    return JSONResponse({"a": 1})
+
+
+if __name__ == "__main__":
+    uvicorn.run("main:app", reload=True)

fastapi_cache/__init__.py

@@ -1,26 +1,42 @@
-from typing import Callable
+from importlib.metadata import version
+from typing import ClassVar, Optional, Type
 
 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 = None
+    _backend: ClassVar[Optional[Backend]] = None
-    _prefix = None
+    _prefix: ClassVar[Optional[str]] = None
-    _expire = None
+    _expire: ClassVar[Optional[int]] = None
-    _init = False
+    _init: ClassVar[bool] = False
-    _coder = None
+    _coder: ClassVar[Optional[Type[Coder]]] = None
-    _key_builder = None
+    _key_builder: ClassVar[Optional[KeyBuilder]] = None
+    _cache_status_header: ClassVar[Optional[str]] = None
+    _enable: ClassVar[bool] = True
 
     @classmethod
     def init(
         cls,
-        backend,
+        backend: Backend,
         prefix: str = "",
-        expire: int = None,
+        expire: Optional[int] = None,
-        coder: Coder = JsonCoder,
+        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:
             return
         cls._init = True
@@ -29,29 +45,59 @@ class FastAPICache:
         cls._expire = expire
         cls._coder = coder
         cls._key_builder = key_builder
+        cls._cache_status_header = cache_status_header
+        cls._enable = enable
 
     @classmethod
-    def get_backend(cls):
+    def reset(cls) -> None:
-        assert cls._backend, "You must call init first!"  # nosec: B101
+        cls._init = False
+        cls._backend = None
+        cls._prefix = None
+        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!"  # noqa: S101
         return cls._backend
 
     @classmethod
-    def get_prefix(cls):
+    def get_prefix(cls) -> str:
+        assert cls._prefix is not None, "You must call init first!"  # noqa: S101
         return cls._prefix
 
     @classmethod
-    def get_expire(cls):
+    def get_expire(cls) -> Optional[int]:
         return cls._expire
 
     @classmethod
-    def get_coder(cls):
+    def get_coder(cls) -> Type[Coder]:
+        assert cls._coder, "You must call init first!"  # noqa: S101
         return cls._coder
 
     @classmethod
-    def get_key_builder(cls):
+    def get_key_builder(cls) -> KeyBuilder:
+        assert cls._key_builder, "You must call init first!"  # noqa: S101
         return cls._key_builder
 
     @classmethod
-    async def clear(cls, namespace: str = None, key: str = None):
+    def get_cache_status_header(cls) -> str:
-        namespace = cls._prefix + ":" + namespace if namespace else None
+        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:
+        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 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, 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) -> 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: int = None):
+    from fastapi_cache.backends import redis
-        raise NotImplementedError
+except ImportError:
-
+    pass
-    @abc.abstractmethod
+else:
-    async def clear(self, namespace: str = None, key: str = None) -> int:
+    __all__ += ["redis"]
-        raise NotImplementedError

fastapi_cache/backends/dynamodb.py

@@ -0,0 +1,103 @@
+import datetime
+from typing import TYPE_CHECKING, Optional, Tuple
+
+from aiobotocore.client import AioBaseClient
+from aiobotocore.session import AioSession, get_session
+
+from fastapi_cache.types import Backend
+
+if TYPE_CHECKING:
+    from types_aiobotocore_dynamodb import DynamoDBClient
+else:
+    DynamoDBClient = AioBaseClient
+
+
+class DynamoBackend(Backend):
+    """
+    Amazon DynamoDB backend provider
+
+    This backend requires an existing table within your AWS environment to be passed during
+    backend init. If ttl is going to be used, this needs to be manually enabled on the table
+    using the `ttl` key. Dynamo will take care of deleting outdated objects, but this is not
+    instant so don't be alarmed when they linger around for a bit.
+
+    As with all AWS clients, credentials will be taken from the environment. Check the AWS SDK
+    for more information.
+
+    Usage:
+        >> dynamodb = DynamoBackend(table_name="your-cache", region="eu-west-1")
+        >> await dynamodb.init()
+        >> 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: AioSession = get_session()
+        self.table_name = table_name
+        self.region = region
+
+    async def init(self) -> None:
+        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, 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("B")
+            ttl = response["Item"].get("ttl", {}).get("N")
+
+            if not ttl:
+                return -1, value
+
+            # It's only eventually consistent so we need to check ourselves
+            expire = int(ttl) - int(datetime.datetime.now().timestamp())
+            if expire > 0:
+                return expire, value
+
+        return 0, None
+
+    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("B")
+        return None
+
+    async def set(self, key: str, value: bytes, expire: Optional[int] = None) -> None:
+        ttl = (
+            {
+                "ttl": {
+                    "N": str(
+                        int(
+                            (
+                                datetime.datetime.now() + datetime.timedelta(seconds=expire)
+                            ).timestamp()
+                        )
+                    )
+                }
+            }
+            if expire
+            else {}
+        )
+
+        await self.client.put_item(
+            TableName=self.table_name,
+            Item={
+                **{
+                    "key": {"S": key},
+                    "value": {"B": value},
+                },
+                **ttl,
+            },
+        )
+
+    async def clear(self, namespace: Optional[str] = None, key: Optional[str] = None) -> int:
+        raise NotImplementedError

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
 
 
@@ -20,32 +20,34 @@ class InMemoryBackend(Backend):
     def _now(self) -> int:
         return int(time.time())
 
-    def _get(self, key: str):
+    def _get(self, key: str) -> Optional[Value]:
         v = self._store.get(key)
         if v:
             if v.ttl_ts < self._now:
                 del self._store[key]
             else:
                 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) -> 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: int = 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)
+            self._store[key] = Value(value, self._now + (expire or 0))
 
-    async def clear(self, namespace: str = None, key: str = None) -> int:
+    async def clear(self, namespace: Optional[str] = None, key: Optional[str] = None) -> int:
         count = 0
         if namespace:
             keys = list(self._store.keys())

fastapi_cache/backends/memcached.py

@@ -1,22 +1,22 @@
-from typing import Tuple
+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, 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):
+    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: int = None):
+    async def set(self, key: str, value: bytes, expire: Optional[int] = None) -> None:
-        return await self.mcache.set(key.encode(), value.encode(), exptime=expire)
+        await self.mcache.set(key.encode(), value, exptime=expire or 0)
 
-    async def clear(self, namespace: str = None, key: str = None):
+    async def clear(self, namespace: Optional[str] = None, key: Optional[str] = None) -> int:
         raise NotImplementedError

fastapi_cache/backends/redis.py

@@ -1,29 +1,30 @@
-from typing import Tuple
+from typing import Optional, Tuple, Union
 
-from aioredis import Redis
+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]]:
-        p = self.redis.pipeline()
+        async with self.redis.pipeline(transaction=not self.is_cluster) as pipe:
-        p.ttl(key)
+            return await pipe.ttl(key).get(key).execute()  # type: ignore[union-attr,no-any-return]
-        p.get(key)
-        return await p.execute()
 
-    async def get(self, key) -> 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: int = None):
+    async def set(self, key: str, value: bytes, expire: Optional[int] = None) -> None:
-        return await self.redis.set(key, value, expire=expire)
+        await self.redis.set(key, value, ex=expire)  # type: ignore[union-attr]
 
-    async def clear(self, namespace: str = None, key: str = None) -> int:
+    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)
+            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,30 +2,52 @@ 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 dateutil.parser
+import pendulum
+from fastapi.encoders import jsonable_encoder
+from starlette.responses import JSONResponse
+from starlette.templating import (
+    _TemplateResponse as TemplateResponse,  # pyright: ignore[reportPrivateUsage]
+)
 
-CONVERTERS = {
+
-    "date": dateutil.parser.parse,
+class ModelField:
-    "datetime": dateutil.parser.parse,
+    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,
 }
 
 
 class JsonEncoder(json.JSONEncoder):
-    def default(self, obj):
+    def default(self, o: Any) -> Any:
-        if isinstance(obj, datetime.datetime):
+        if isinstance(o, datetime.datetime):
-            return {"val": obj.strftime("%Y-%m-%d %H:%M:%S"), "_spec_type": "datetime"}
+            return {"val": str(o), "_spec_type": "datetime"}
-        elif isinstance(obj, datetime.date):
+        elif isinstance(o, datetime.date):
-            return {"val": obj.strftime("%Y-%m-%d"), "_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 super().default(obj)
+            return jsonable_encoder(o)
 
 
-def object_hook(obj):
+def object_hook(obj: Any) -> Any:
     _spec_type = obj.get("_spec_type")
     if not _spec_type:
         return obj
@@ -33,34 +55,75 @@ def object_hook(obj):
     if _spec_type in CONVERTERS:
         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):
+    def encode(cls, value: Any) -> bytes:
         raise NotImplementedError
 
     @classmethod
-    def decode(cls, value: 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):
+    def encode(cls, value: Any) -> Any:
-        return json.dumps(value, cls=JsonEncoder)
+        if isinstance(value, JSONResponse):
+            return value.body
+        return json.dumps(value, cls=JsonEncoder).encode()
 
     @classmethod
-    def decode(cls, value: Any):
+    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):
+    def encode(cls, value: Any) -> bytes:
+        if isinstance(value, TemplateResponse):
+            value = value.body
         return pickle.dumps(value)
 
     @classmethod
-    def decode(cls, value: Any):
+    def decode(cls, value: bytes) -> Any:
-        return pickle.loads(value)  # nosec:B403
+        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,67 +1,230 @@
+import logging
+import sys
 from functools import wraps
-from typing import Callable, Optional, Type
+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
+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: int = None,
+    expire: Optional[int] = None,
-    coder: Type[Coder] = None,
+    coder: Optional[Type[Coder]] = None,
-    key_builder: Callable = None,
+    key_builder: Optional[KeyBuilder] = None,
-    namespace: Optional[str] = "",
+    namespace: str = "",
-):
+    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:
     :param key_builder:
+
     :return:
     """
 
-    def wrapper(func):
+    injected_request = Parameter(
+        name=f"{injected_dependency_namespace}_request",
+        annotation=Request,
+        kind=Parameter.KEYWORD_ONLY,
+    )
+    injected_response = Parameter(
+        name=f"{injected_dependency_namespace}_response",
+        annotation=Response,
+        kind=Parameter.KEYWORD_ONLY,
+    )
+
+    def wrapper(
+        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, **kwargs):
+        async def inner(*args: P.args, **kwargs: P.kwargs) -> Union[R, Response]:
             nonlocal coder
             nonlocal expire
             nonlocal key_builder
-            request = kwargs.get("request")
-            if request.headers.get("Cache-Control") == "no-store":
-                return await func(*args, **kwargs)
 
+            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, make sure we don't pass them in as
+                # keyword arguments
+                kwargs.pop(injected_request.name, None)
+                kwargs.pop(injected_response.name, None)
+
+                if iscoroutinefunction(func):
+                    # async, return as is.
+                    # unintuitively, we have to await once here, so that caller
+                    # does not have to await twice. See
+                    # https://stackoverflow.com/a/59268198/532513
+                    return await func(*args, **kwargs)
+                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)  # type: ignore[arg-type]
+
+            copy_kwargs = kwargs.copy()
+            request: Optional[Request] = copy_kwargs.pop(request_param.name, None)  # type: ignore[assignment]
+            response: Optional[Response] = copy_kwargs.pop(response_param.name, None)  # type: ignore[assignment]
+
+            if _uncacheable(request):
+                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()
-            request = kwargs.pop("request", None)
-            response = kwargs.pop("response", None)
             backend = FastAPICache.get_backend()
-            cache_key = key_builder(func, namespace, args=args, kwargs=kwargs)
+            cache_status_header = FastAPICache.get_cache_status_header()
-            ttl, ret = await backend.get_with_ttl(cache_key)
+
-            if not request:
+            cache_key = key_builder(
-                if ret is not None:
+                func,
-                    return coder.decode(ret)
+                f"{prefix}:{namespace}",
-                ret = await func(*args, **kwargs)
+                request=request,
-                await backend.set(cache_key, coder.encode(ret), expire or FastAPICache.get_expire())
+                response=response,
-                return ret
+                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, cached = await backend.get_with_ttl(cache_key)
+            except Exception:
+                logger.warning(
+                    f"Error retrieving cache key '{cache_key}' from backend:",
+                    exc_info=True,
+                )
+                ttl, cached = 0, None
+
+            if cached is None  or (request is not None and request.headers.get("Cache-Control") == "no-cache") :  # cache miss
+                result = await ensure_async_func(*args, **kwargs)
+                to_cache = coder.encode(result)
+
+                try:
+                    await backend.set(cache_key, to_cache, expire)
+                except Exception:
+                    logger.warning(
+                        f"Error setting cache key '{cache_key}' in backend:",
+                        exc_info=True,
+                    )
 
-            if request.method != "GET":
-                return await func(request, *args, **kwargs)
-            if_none_match = request.headers.get("if-none-match")
-            if ret is not None:
-                response = kwargs.get("response")
                 if response:
-                    response.headers["Cache-Control"] = f"max-age={ttl}"
+                    response.headers.update(
-                    etag = f"W/{hash(ret)}"
+                        {
-                    if if_none_match == etag:
+                            "Cache-Control": f"max-age={expire}",
-                        response.status_code = 304
+                            "ETag": f"W/{hash(to_cache)}",
-                        return response
+                            cache_status_header: "MISS",
-                    response.headers["ETag"] = etag
+                        }
-                return coder.decode(ret)
+                    )
 
-            ret = await func(*args, **kwargs)
+            else:  # cache hit
-            await backend.set(cache_key, coder.encode(ret), expire or FastAPICache.get_expire())
+                if response:
-            return ret
+                    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,19 +1,20 @@
-from typing import Optional
+import hashlib
+from typing import Any, Callable, Dict, Optional, Tuple
 
 from starlette.requests import Request
 from starlette.responses import Response
 
 
 def default_key_builder(
-    func,
+    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
-
+        f"{func.__module__}:{func.__name__}:{args}:{kwargs}".encode()
-    prefix = FastAPICache.get_prefix()
+    ).hexdigest()
-    cache_key = f"{prefix}:{namespace}:{func.__module__}:{func.__name__}:{args}:{kwargs}"
+    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.1.3"
+version = "0.2.2"
 description = "Cache for FastAPI"
 authors = ["long2ice <long2ice@gmail.com>"]
 license = "Apache-2.0"
@@ -15,25 +15,101 @@ packages = [
 include = ["LICENSE", "README.md"]
 
 [tool.poetry.dependencies]
-python = "^3.7"
+python = "^3.8"
 fastapi = "*"
 uvicorn = "*"
-aioredis = {version = "*", optional = true}
+typing-extensions = { version = ">=4.1.0" }
-aiomcache = {version = "*", optional = true}
+importlib-metadata = { version = "^6.6.0", python = "<3.8" }
-python-dateutil = "*"
+pendulum = "^3.0.0"
+aiomcache = { version = "^0.8.2", optional = true }
+aiobotocore = {version = "^2.13.1", optional = true}
+redis = {version = "^5.0.8", extras = ["redis"]}
 
-[tool.poetry.dev-dependencies]
+[tool.poetry.group.linting]
-flake8 = "*"
+optional = true
-isort = "*"
+
-black = "^19.10b0"
+[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 = "*"
-bandit = "*"
+requests = "*"
+coverage = ">=6.5,<8.0"
+httpx = "*"
+tox = "^4.5.1"
+towncrier = "^22.12.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 = ["aioredis"]
+redis = ["redis"]
 memcache = ["aiomcache"]
-all = ["aioredis","aiomcache"]
+dynamodb = ["aiobotocore"]
+all = ["redis", "aiomcache", "aiobotocore"]
+
+[tool.mypy]
+files = ["."]
+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,2 +1,137 @@
-def test_default_key_builder():
+import time
-    return 1
+from typing import Any, Generator
+
+import pendulum
+import pytest
+from starlette.testclient import TestClient
+
+from examples.in_memory.main import app
+from fastapi_cache import FastAPICache
+from fastapi_cache.backends.inmemory import InMemoryBackend
+
+
+@pytest.fixture(autouse=True)
+def _init_cache() -> Generator[Any, Any, None]:  # pyright: ignore[reportUnusedFunction]
+    FastAPICache.init(InMemoryBackend())
+    yield
+    FastAPICache.reset()
+
+
+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()
+        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) == now_
+        time.sleep(3)
+        response = client.get("/datetime")
+        now = response.json().get("now")
+        assert response.headers.get("X-FastAPI-Cache") == "MISS"
+        now = pendulum.parse(now)
+        assert now != now_
+        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  # 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 # pyright: ignore[reportPrivateUsage]
+
+
+def test_sync() -> None:
+    """Ensure that sync function support works."""
+    with TestClient(app) as client:
+        response = client.get("/sync-me")
+        assert response.json() == 42
+
+
+def test_cache_response_obj() -> None:
+    with TestClient(app) as client:
+        cache_response = client.get("cache_response_obj")
+        assert cache_response.json() == {"a": 1}
+        get_cache_response = client.get("cache_response_obj")
+        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/*