Debian Codegraph @

docs/usage/lifecycle-hooks.rst

raw
1 Life Cycle Hooks
2 ================
3
4 Life cycle hooks allow the execution of a callable at a certain point during the request-response
5 cycle. The hooks available are:
6
7 +--------------------------------------+------------------------------------+
8 | Name | Runs |
9 +======================================+====================================+
10 | `before_request`_ | Before the router handler function |
11 +--------------------------------------+------------------------------------+
12 | `after_request`_ | After the route handler function |
13 +--------------------------------------+------------------------------------+
14 | `after_response`_ | After the response has been sent |
15 +--------------------------------------+------------------------------------+
16
17 .. _before_request:
18
19 Before Request
20 --------------
21
22 The ``before_request`` hook runs immediately before calling the route handler function. It
23 can be any callable accepting a :class:`~litestar.connection.Request` as its first parameter
24 and returns either ``None`` or a value that can be used in a response.
25 If a value is returned, the router handler for this request will be bypassed.
26
27 .. literalinclude:: /examples/lifecycle_hooks/before_request.py
28 :language: python
29
30
31 .. _after_request:
32
33 After Request
34 -------------
35
36 The ``after_request`` hook runs after the route handler returned and the response object
37 has been resolved. It can be any callable which takes a :class:`~litestar.response.Response`
38 instance as its first parameter, and returns a ``Response`` instance. The ``Response``
39 instance returned does not necessarily have to be the one that was received.
40
41 .. literalinclude:: /examples/lifecycle_hooks/after_request.py
42 :language: python
43
44
45 .. _after_response:
46
47 After Response
48 --------------
49
50 The ``after_response`` hook runs after the response has been returned by the server.
51 It can be any callable accepting a :class:`~litestar.connection.Request` as its first parameter
52 and does not return any value.
53
54 This hook is meant for data post-processing, transmission of data to third party
55 services, gathering of metrics, etc.
56
57 .. literalinclude:: /examples/lifecycle_hooks/after_response.py
58 :language: python
59
60
61 .. note::
62
63 Since the request has already been returned by the time the ``after_response`` is called,
64 the updated state of ``COUNTER`` is not reflected in the response.
65
66
67 Layered hooks
68 -------------
69
70 .. admonition:: Layered architecture
71
72 Life cycle hooks are part of Litestar's layered architecture, which means you can
73 set them on every layer of the application. If you set hooks on multiple layers,
74 the layer closest to the route handler will take precedence.
75
76 You can read more about this here:
77 :ref:`Layered architecture <usage/applications:layered architecture>`
78
79
80 .. literalinclude:: /examples/lifecycle_hooks/layered_hooks.py
81 :language: python