# fastapi-cache
[](https://pypi.org/p/fastapi-cache2)
[](https://github.com/Yolley/fastapi-cache/blob/main/LICENSE)
[](https://github.com/Yolley/fastapi-cache/actions/workflows/ci-cd.yml)
## Introduction
`fastapi-cache` is a tool to cache FastAPI endpoint and function results, with
backends supporting Redis, Memcached, and Amazon DynamoDB.
## Features
- Supports `redis`, `memcache`, `dynamodb`, and `in-memory` backends.
- Easy integration with [FastAPI](https://fastapi.tiangolo.com/).
- Support for HTTP cache headers like `ETag` and `Cache-Control`, as well as conditional `If-Match-None` requests.
## Requirements
- FastAPI
- `redis` when using `RedisBackend`.
- `memcache` when using `MemcacheBackend`.
- `aiobotocore` when using `DynamoBackend`.
## Install
```shell
> pip install fastapi-cache2
```
or
```shell
> pip install "fastapi-cache2[redis]"
```
or
```shell
> pip install "fastapi-cache2[memcache]"
```
or
```shell
> pip install "fastapi-cache2[dynamodb]"
```
## Usage
### Quick Start
```python
from collections.abc import AsyncGenerator
from contextlib import asynccontextmanager
from fastapi import FastAPI
from starlette.requests import Request
from starlette.responses import Response
from fastapi_cache import FastAPICache
from fastapi_cache.backends.redis import RedisBackend
from fastapi_cache.decorator import cache
import redis.asyncio as redis
from redis.asyncio.connection import ConnectionPool
@asynccontextmanager
async def lifespan(_app: FastAPI) -> AsyncGenerator[None, None]:
pool = ConnectionPool.from_url(url="redis://localhost")
r = redis.Redis(connection_pool=pool)
FastAPICache.init(RedisBackend(r), prefix="fastapi-cache")
yield
app = FastAPI(lifespan=lifespan)
@cache()
async def get_cache():
return 1
@app.get("/")
@cache(expire=60)
async def index():
return dict(hello="world")
```
### Initialization
First you must call `FastAPICache.init` during startup FastAPI startup; this is where you set global configuration.
### Use the `@cache` decorator
If you want cache a FastAPI response transparently, you can use the `@cache`
decorator between the router decorator and the view function.
| 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 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`.
```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=ORJsonCoder)
async def index():
return dict(hello="world")
```
### Custom key builder
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 request_key_builder(
func,
namespace: str = "",
*,
request: Request = None,
response: Response = None,
*args,
**kwargs,
):
return ":".join([
namespace,
request.method.lower(),
request.url.path,
repr(sorted(request.query_params.items()))
])
@app.get("/")
@cache(expire=60, key_builder=request_key_builder)
async def index():
return dict(hello="world")
```
## Backend notes
### InMemoryBackend
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/Yolley/fastapi-cache/blob/master/LICENSE) License.
Raw data
{
"_id": null,
"home_page": "https://github.com/Yolley/fastapi-cache",
"name": "fastapi-cache2-fork",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11,<4.0",
"maintainer_email": "",
"keywords": "fastapi,cache,caching",
"author": "long2ice",
"author_email": "long2ice@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d7/21/f35143afb0ea197c54ed7aa12f00cd8b6aa80f4380272f67bca1ab4ff557/fastapi_cache2_fork-0.3.1.tar.gz",
"platform": null,
"description": "# fastapi-cache\n\n[](https://pypi.org/p/fastapi-cache2)\n[](https://github.com/Yolley/fastapi-cache/blob/main/LICENSE)\n[](https://github.com/Yolley/fastapi-cache/actions/workflows/ci-cd.yml)\n\n## Introduction\n\n`fastapi-cache` is a tool to cache FastAPI endpoint and function results, with\nbackends supporting Redis, Memcached, and Amazon DynamoDB.\n\n## Features\n\n- Supports `redis`, `memcache`, `dynamodb`, and `in-memory` backends.\n- Easy integration with [FastAPI](https://fastapi.tiangolo.com/).\n- Support for HTTP cache headers like `ETag` and `Cache-Control`, as well as conditional `If-Match-None` requests.\n\n## Requirements\n\n- FastAPI\n- `redis` when using `RedisBackend`.\n- `memcache` when using `MemcacheBackend`.\n- `aiobotocore` when using `DynamoBackend`.\n\n## Install\n\n```shell\n> pip install fastapi-cache2\n```\n\nor\n\n```shell\n> pip install \"fastapi-cache2[redis]\"\n```\n\nor\n\n```shell\n> pip install \"fastapi-cache2[memcache]\"\n```\n\nor\n\n```shell\n> pip install \"fastapi-cache2[dynamodb]\"\n```\n\n## Usage\n\n### Quick Start\n\n```python\nfrom collections.abc import AsyncGenerator\nfrom contextlib import asynccontextmanager\n\nfrom fastapi import FastAPI\nfrom starlette.requests import Request\nfrom starlette.responses import Response\n\nfrom fastapi_cache import FastAPICache\nfrom fastapi_cache.backends.redis import RedisBackend\nfrom fastapi_cache.decorator import cache\n\nimport redis.asyncio as redis\nfrom redis.asyncio.connection import ConnectionPool\n\n@asynccontextmanager\nasync def lifespan(_app: FastAPI) -> AsyncGenerator[None, None]:\n pool = ConnectionPool.from_url(url=\"redis://localhost\")\n r = redis.Redis(connection_pool=pool)\n FastAPICache.init(RedisBackend(r), prefix=\"fastapi-cache\")\n yield\n\n\napp = FastAPI(lifespan=lifespan)\n\n\n@cache()\nasync def get_cache():\n return 1\n\n\n@app.get(\"/\")\n@cache(expire=60)\nasync def index():\n return dict(hello=\"world\")\n\n```\n\n### Initialization\n\nFirst you must call `FastAPICache.init` during startup FastAPI startup; this is where you set global configuration.\n\n### Use the `@cache` decorator\n\nIf you want cache a FastAPI response transparently, you can use the `@cache`\ndecorator between the router decorator and the view function.\n\n| Parameter | type | default | description |\n| ------------------------------- | --------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------ |\n| `expire` | `int` | | sets the caching time in seconds |\n| `namespace` | `str` | `\"\"` | namespace to use to store certain cache items |\n| `coder` | `Coder` | `JsonCoder` | which coder to use, e.g. `JsonCoder` |\n| `key_builder` | `KeyBuilder` callable | `default_key_builder` | which key builder to use |\n| `injected_dependency_namespace` | `str` | `__fastapi_cache` | prefix for injected dependency keywords. |\n| `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`. |\n\nYou can also use the `@cache` decorator on regular functions to cache their result.\n\n### Injected Request and Response dependencies\n\nThe `cache` decorator injects dependencies for the `Request` and `Response`\nobjects, so that it can add cache control headers to the outgoing response, and\nreturn a 304 Not Modified response when the incoming request has a matching\n`If-Non-Match` header. This only happens if the decorated endpoint doesn't already\nlist these dependencies already.\n\nThe keyword arguments for these extra dependencies are named\n`__fastapi_cache_request` and `__fastapi_cache_response` to minimize collisions.\nUse the `injected_dependency_namespace` argument to `@cache` to change the\nprefix used if those names would clash anyway.\n\n### Supported data types\n\nWhen using the (default) `JsonCoder`, the cache can store any data type that FastAPI can convert to JSON, including Pydantic models and dataclasses,\n_provided_ that your endpoint has a correct return type annotation. An\nannotation is not needed if the return type is a standard JSON-supported Python\ntype such as a dictionary or a list.\n\nE.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:\n\n```python\nfrom .models import SomeModel, create_some_model\n\n@app.get(\"/foo\")\n@cache(expire=60)\nasync def foo() -> SomeModel:\n return create_some_model()\n```\n\nIt 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.\n\nFor broader type support, use the `fastapi_cache.coder.PickleCoder` or implement a custom coder (see below).\n\n### Custom coder\n\nBy default use `JsonCoder`, you can write custom coder to encode and decode cache result, just need\ninherit `fastapi_cache.coder.Coder`.\n\n```python\nfrom typing import Any\nimport orjson\nfrom fastapi.encoders import jsonable_encoder\nfrom fastapi_cache import Coder\n\nclass ORJsonCoder(Coder):\n @classmethod\n def encode(cls, value: Any) -> bytes:\n return orjson.dumps(\n value,\n default=jsonable_encoder,\n option=orjson.OPT_NON_STR_KEYS | orjson.OPT_SERIALIZE_NUMPY,\n )\n\n @classmethod\n def decode(cls, value: bytes) -> Any:\n return orjson.loads(value)\n\n\n@app.get(\"/\")\n@cache(expire=60, coder=ORJsonCoder)\nasync def index():\n return dict(hello=\"world\")\n```\n\n### Custom key builder\n\nBy default the `default_key_builder` builtin key builder is used; this creates a\ncache key from the function module and name, and the positional and keyword\narguments converted to their `repr()` representations, encoded as a MD5 hash.\nYou can provide your own by passing a key builder in to `@cache()`, or to\n`FastAPICache.init()` to apply globally.\n\nFor 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:\n\n```python\ndef request_key_builder(\n func,\n namespace: str = \"\",\n *,\n request: Request = None,\n response: Response = None,\n *args,\n **kwargs,\n):\n return \":\".join([\n namespace,\n request.method.lower(),\n request.url.path,\n repr(sorted(request.query_params.items()))\n ])\n\n\n@app.get(\"/\")\n@cache(expire=60, key_builder=request_key_builder)\nasync def index():\n return dict(hello=\"world\")\n```\n\n## Backend notes\n\n### InMemoryBackend\n\nThe `InMemoryBackend` stores cache data in memory and only deletes when an\nexpired key is accessed. This means that if you don't access a function after\ndata has been cached, the data will not be removed automatically.\n\n### RedisBackend\n\nWhen 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.\n\n[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\n\n## Tests and coverage\n\n```shell\ncoverage run -m pytest\ncoverage html\nxdg-open htmlcov/index.html\n```\n\n## License\n\nThis project is licensed under the [Apache-2.0](https://github.com/Yolley/fastapi-cache/blob/master/LICENSE) License.\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Cache for FastAPI. An opinionated fork of fastapi-cache library that uses msgspec for json encoding/decoding where possible",
"version": "0.3.1",
"project_urls": {
"Documentation": "https://github.com/Yolley/fastapi-cache",
"Homepage": "https://github.com/Yolley/fastapi-cache",
"Repository": "https://github.com/Yolley/fastapi-cache.git"
},
"split_keywords": [
"fastapi",
"cache",
"caching"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "84e63773da291c9f95534324d1c38ac86053bbeabf39e09d90a2837b5c829b8b",
"md5": "f74daf76c509104949163b4bddfcacf2",
"sha256": "9d7bbbb1aac6f599c13aa72f34adab8e40f1b773d7a5eb7c815a483a865c6c9b"
},
"downloads": -1,
"filename": "fastapi_cache2_fork-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f74daf76c509104949163b4bddfcacf2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11,<4.0",
"size": 25317,
"upload_time": "2023-11-28T08:52:19",
"upload_time_iso_8601": "2023-11-28T08:52:19.267057Z",
"url": "https://files.pythonhosted.org/packages/84/e6/3773da291c9f95534324d1c38ac86053bbeabf39e09d90a2837b5c829b8b/fastapi_cache2_fork-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d721f35143afb0ea197c54ed7aa12f00cd8b6aa80f4380272f67bca1ab4ff557",
"md5": "6a5da5cbb473c9eaa3561aaf9135399c",
"sha256": "9888b67f6d379a10fa96b808bee230d32f0dd8e5e3d030681f177e7d849d2d45"
},
"downloads": -1,
"filename": "fastapi_cache2_fork-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "6a5da5cbb473c9eaa3561aaf9135399c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11,<4.0",
"size": 17726,
"upload_time": "2023-11-28T08:52:20",
"upload_time_iso_8601": "2023-11-28T08:52:20.846629Z",
"url": "https://files.pythonhosted.org/packages/d7/21/f35143afb0ea197c54ed7aa12f00cd8b6aa80f4380272f67bca1ab4ff557/fastapi_cache2_fork-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-28 08:52:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Yolley",
"github_project": "fastapi-cache",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "fastapi-cache2-fork"
}
JSON
