Repository files navigation

fastapi-cache is a tool to cache FastAPI endpoint and function results, withbackends supporting Redis, Memcached, and Amazon DynamoDB.

• Supportsredis,memcache,dynamodb, andin-memory backends.
• Easy integration withFastAPI.
• Support for HTTP cache headers likeETag andCache-Control, as well as conditionalIf-Match-None requests.

• FastAPI
• redis when usingRedisBackend.
• memcache when usingMemcacheBackend.
• aiobotocore when usingDynamoBackend.

> pip install fastapi-cache2

or

> pip install"fastapi-cache2[redis]"

or

> pip install"fastapi-cache2[memcache]"

or

> pip install"fastapi-cache2[dynamodb]"

fromcollections.abcimportAsyncIteratorfromcontextlibimportasynccontextmanagerfromfastapiimportFastAPIfromstarlette.requestsimportRequestfromstarlette.responsesimportResponsefromfastapi_cacheimportFastAPICachefromfastapi_cache.backends.redisimportRedisBackendfromfastapi_cache.decoratorimportcachefromredisimportasyncioasaioredis@asynccontextmanagerasyncdeflifespan(_:FastAPI)->AsyncIterator[None]:redis=aioredis.from_url("redis://localhost")FastAPICache.init(RedisBackend(redis),prefix="fastapi-cache")yieldapp=FastAPI(lifespan=lifespan)@cache()asyncdefget_cache():return1@app.get("/")@cache(expire=60)asyncdefindex():returndict(hello="world")

First you must callFastAPICache.init during startup FastAPI startup; this is where you set global configuration.

If you want cache a FastAPI response transparently, you can use the@cachedecorator between the router decorator and the view function.

You can also use the@cache decorator on regular functions to cache their result.

Thecache decorator injects dependencies for theRequest andResponseobjects, so that it can add cache control headers to the outgoing response, andreturn a 304 Not Modified response when the incoming request has a matchingIf-Non-Match header. This only happens if the decorated endpoint doesn't alreadylist these dependencies already.

The keyword arguments for these extra dependencies are named__fastapi_cache_request and__fastapi_cache_response to minimize collisions.Use theinjected_dependency_namespace argument to@cache to change theprefix used if those names would clash anyway.

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. Anannotation is not needed if the return type is a standard JSON-supported Pythontype such as a dictionary or a list.

E.g. for an endpoint that returns a Pydantic model namedSomeModel, the return annotation is used to ensure that the cached result is converted back to the correct class:

from .modelsimportSomeModel,create_some_model@app.get("/foo")@cache(expire=60)asyncdeffoo()->SomeModel:returncreate_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 thefastapi_cache.coder.PickleCoder or implement a custom coder (see below).

By default useJsonCoder, you can write custom coder to encode and decode cache result, just needinheritfastapi_cache.coder.Coder.

fromtypingimportAnyimportorjsonfromfastapi.encodersimportjsonable_encoderfromfastapi_cacheimportCoderclassORJsonCoder(Coder):@classmethoddefencode(cls,value:Any)->bytes:returnorjson.dumps(value,default=jsonable_encoder,option=orjson.OPT_NON_STR_KEYS|orjson.OPT_SERIALIZE_NUMPY,        )@classmethoddefdecode(cls,value:bytes)->Any:returnorjson.loads(value)@app.get("/")@cache(expire=60,coder=ORJsonCoder)asyncdefindex():returndict(hello="world")

By default thedefault_key_builder builtin key builder is used; this creates acache key from the function module and name, and the positional and keywordarguments converted to theirrepr() representations, encoded as a MD5 hash.You can provide your own by passing a key builder in to@cache(), or toFastAPICache.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:

defrequest_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)asyncdefindex():returndict(hello="world")

TheInMemoryBackend stores cache data in memory and only deletes when anexpired key is accessed. This means that if you don't access a function afterdata has been cached, the data will not be removed automatically.

When using the Redis backend, please make sure you pass in a redis client that doesnot decode responses (decode_responsesmust beFalse, which is the default). Cached data is stored asbytes (binary), decoding these in the Redis client would break caching.

coverage run -m pytestcoverage htmlxdg-open htmlcov/index.html

This project is licensed under theApache-2.0 License.