docs: 3442 response cache (#3514)

* fix: adjust response cache

* docs: move code into examples

---------

Co-authored-by: Jacob Coffee <[email protected]>

docs/examples/caching/cache.py

@@ -0,0 +1,22 @@
+from litestar import Litestar, get
+from litestar.config.response_cache import CACHE_FOREVER
+
+
+@get("/cached", cache=True)
+async def my_cached_handler() -> str:
+    return "cached"
+
+
+@get("/cached-seconds", cache=120)  # seconds
+async def my_cached_handler_seconds() -> str:
+    return "cached for 120 seconds"
+
+
+@get("/cached-forever", cache=CACHE_FOREVER)
+async def my_cached_handler_forever() -> str:
+    return "cached forever"
+
+
+app = Litestar(
+    [my_cached_handler, my_cached_handler_seconds, my_cached_handler_forever],
+)

docs/examples/caching/key_builder.py

@@ -0,0 +1,9 @@
+from litestar import Litestar, Request
+from litestar.config.response_cache import ResponseCacheConfig
+
+
+def key_builder(request: Request) -> str:
+    return request.url.path + request.headers.get("my-header", "")
+
+
+app = Litestar([], response_cache_config=ResponseCacheConfig(key_builder=key_builder))

docs/examples/caching/key_builder_for_route_handler.py

@@ -0,0 +1,13 @@
+from litestar import Litestar, Request, get
+
+
+def key_builder(request: Request) -> str:
+    return request.url.path + request.headers.get("my-header", "")
+
+
+@get("/cached-path", cache=True, cache_key_builder=key_builder)
+async def cached_handler() -> str:
+    return "cached"
+
+
+app = Litestar([cached_handler])

docs/examples/caching/redis_store.py

@@ -0,0 +1,20 @@
+import asyncio
+
+from litestar import Litestar, get
+from litestar.config.response_cache import ResponseCacheConfig
+from litestar.stores.redis import RedisStore
+
+
+@get(cache=10)
+async def something() -> str:
+    await asyncio.sleep(1)
+    return "something"
+
+
+redis_store = RedisStore.with_client(url="redis://localhost/", port=6379, db=0)
+cache_config = ResponseCacheConfig(store="redis_backed_store")
+app = Litestar(
+    [something],
+    stores={"redis_backed_store": redis_store},
+    response_cache_config=cache_config,
+)

docs/usage/caching.rst

@@ -7,13 +7,9 @@ Caching responses
 Sometimes it's desirable to cache some responses, especially if these involve expensive calculations, or when polling is
 expected. Litestar comes with a simple mechanism for caching:
 
-.. code-block:: python
-
-   from litestar import get
-
-
-   @get("/cached-path", cache=True)
-   def my_cached_handler() -> str: ...
+.. literalinclude:: /examples/caching/cache.py
+    :language: python
+    :lines: 1, 4-8
 
 By setting :paramref:`~litestar.handlers.HTTPRouteHandler.cache` to ``True``, the response from the handler
 will be cached. If no ``cache_key_builder`` is set in the route handler, caching for the route handler will be
@@ -25,31 +21,22 @@ enabled for the :attr:`~.config.response_cache.ResponseCacheConfig.default_expir
 
 Alternatively you can specify the number of seconds to cache the responses from the given handler like so:
 
-.. code-block:: python
+.. literalinclude:: /examples/caching/cache.py
+    :language: python
     :caption: Caching the response for 120 seconds by setting the :paramref:`~litestar.handlers.HTTPRouteHandler.cache`
       parameter to the number of seconds to cache the response.
+    :lines: 1, 9-13
     :emphasize-lines: 4
 
-    from litestar import get
-
-
-    @get("/cached-path", cache=120)  # seconds
-    def my_cached_handler() -> str: ...
-
-
 If you want the response to be cached indefinitely, you can pass the :class:`~.config.response_cache.CACHE_FOREVER`
 sentinel instead:
 
-.. code-block:: python
+.. literalinclude:: /examples/caching/cache.py
+    :language: python
     :caption: Caching the response indefinitely by setting the :paramref:`~litestar.handlers.HTTPRouteHandler.cache`
       parameter to :class:`~litestar.config.response_cache.CACHE_FOREVER`.
-
-    from litestar import get
-    from litestar.config.response_cache import CACHE_FOREVER
-
-
-    @get("/cached-path", cache=CACHE_FOREVER)
-    def my_cached_handler() -> str: ...
+    :lines: 1, 3, 14-18
+    :emphasize-lines: 5
 
 Configuration
 -------------
@@ -63,45 +50,20 @@ Changing where data is stored
 By default, caching will use the :class:`~.stores.memory.MemoryStore`, but it can be configured with
 any :class:`~.stores.base.Store`, for example :class:`~.stores.redis.RedisStore`:
 
-.. code-block:: python
+.. literalinclude:: /examples/caching/redis_store.py
+    :language: python
     :caption: Using Redis as the cache store.
 
-    from litestar.config.cache import ResponseCacheConfig
-    from litestar.stores.redis import RedisStore
-
-    redis_store = RedisStore(url="redis://localhost/", port=6379, db=0)
-
-    cache_config = ResponseCacheConfig(store=redis_store)
-
-
 Specifying a cache key builder
 ++++++++++++++++++++++++++++++
 
 Litestar uses the request's path + sorted query parameters as the cache key. This can be adjusted by providing a
 "key builder" function, either at application or route handler level.
 
-.. code-block:: python
+.. literalinclude:: /examples/caching/key_builder.py
+    :language: python
     :caption: Using a custom cache key builder.
 
-    from litestar import Litestar, Request
-    from litestar.config.cache import ResponseCacheConfig
-
-
-    def key_builder(request: Request) -> str:
-        return request.url.path + request.headers.get("my-header", "")
-
-
-    app = Litestar([], cache_config=ResponseCacheConfig(key_builder=key_builder))
-
-.. code-block:: python
+.. literalinclude:: /examples/caching/key_builder_for_route_handler.py
+    :language: python
     :caption: Using a custom cache key builder for a specific route handler.
-
-    from litestar import Litestar, Request, get
-
-
-    def key_builder(request: Request) -> str:
-        return request.url.path + request.headers.get("my-header", "")
-
-
-    @get("/cached-path", cache=True, cache_key_builder=key_builder)
-    def cached_handler() -> str: ...