| 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 |