Debian Codegraph @

docs/usage/caching.rst

raw
1 Caching
2 =======
3
4 Caching responses
5 ------------------
6
7 Sometimes it's desirable to cache some responses, especially if these involve expensive calculations, or when polling is
8 expected. Litestar comes with a simple mechanism for caching:
9
10 .. literalinclude:: /examples/caching/cache.py
11 :language: python
12 :lines: 1, 4-8
13
14 By setting :paramref:`~litestar.handlers.HTTPRouteHandler.cache` to ``True``, the response from the handler
15 will be cached. If no ``cache_key_builder`` is set in the route handler, caching for the route handler will be
16 enabled for the :attr:`~.config.response_cache.ResponseCacheConfig.default_expiration`.
17
18 .. note:: If the default :paramref:`~litestar.config.response_cache.ResponseCacheConfig.default_expiration` is set to
19 ``None``, setting up the route handler with :paramref:`~litestar.handlers.HTTPRouteHandler.cache` set to ``True``
20 will keep the response in cache indefinitely.
21
22 Alternatively you can specify the number of seconds to cache the responses from the given handler like so:
23
24 .. literalinclude:: /examples/caching/cache.py
25 :language: python
26 :caption: Caching the response for 120 seconds by setting the :paramref:`~litestar.handlers.HTTPRouteHandler.cache`
27 parameter to the number of seconds to cache the response.
28 :lines: 1, 9-13
29 :emphasize-lines: 4
30
31 If you want the response to be cached indefinitely, you can pass the :class:`~.config.response_cache.CACHE_FOREVER`
32 sentinel instead:
33
34 .. literalinclude:: /examples/caching/cache.py
35 :language: python
36 :caption: Caching the response indefinitely by setting the :paramref:`~litestar.handlers.HTTPRouteHandler.cache`
37 parameter to :class:`~litestar.config.response_cache.CACHE_FOREVER`.
38 :lines: 1-3, 14-18
39 :emphasize-lines: 5
40
41 Configuration
42 -------------
43
44 You can configure caching behaviour on the application level by passing an instance of
45 :class:`~.config.response_cache.ResponseCacheConfig` to the :class:`Litestar instance <.app.Litestar>`.
46
47 Changing where data is stored
48 +++++++++++++++++++++++++++++
49
50 By default, caching will use the :class:`~.stores.memory.MemoryStore`, but it can be configured with
51 any :class:`~.stores.base.Store`, for example :class:`~.stores.redis.RedisStore`:
52
53 .. literalinclude:: /examples/caching/redis_store.py
54 :language: python
55 :caption: Using Redis as the cache store.
56
57 Specifying a cache key builder
58 ++++++++++++++++++++++++++++++
59
60 Litestar uses the request's path + sorted query parameters as the cache key. This can be adjusted by providing a
61 "key builder" function, either at application or route handler level.
62
63 .. literalinclude:: /examples/caching/key_builder.py
64 :language: python
65 :caption: Using a custom cache key builder.
66
67 .. literalinclude:: /examples/caching/key_builder_for_route_handler.py
68 :language: python
69 :caption: Using a custom cache key builder for a specific route handler.
70
71 Using the cache_response_filter
72 +++++++++++++++++++++++++++++++
73
74 The :attr:`~.config.response_cache.ResponseCacheConfig.cache_response_filter` can be customized to implement any caching logic based on the application's needs.
75 For example, you might want to cache only successful responses, or cache responses based on certain headers or content.
76
77 .. literalinclude:: /examples/caching/cache_response_filter.py
78 :language: python
79 :caption: Using the cache_response_filter to customize caching behavior.
80
81 In this example, the `custom_cache_response_filter` function caches only successful (2xx) responses.