Debian Codegraph @

docs/tutorials/sqlalchemy/1-provide-session-with-di.rst

raw
1 Providing the session with DI
2 -----------------------------
3
4
5 In our original script, we had to repeat the logic to construct a session instance for every request type. This is not
6 very `DRY <https://en.wikipedia.org/wiki/Don%27t_repeat_yourself>`_.
7
8 In this section, we'll use dependency injection to centralize the session creation logic and make it available to all
9 handlers.
10
11 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/tutorial/full_app_with_session_di.py
12 :language: python
13 :linenos:
14 :emphasize-lines: 48-58,83-84,88-90,95-96,104
15
16 In the previous example, the database session is created within each HTTP route handler function. In this script we use
17 dependency injection to decouple creation of the session from the route handlers.
18
19 This script introduces a new async generator function called ``provide_transaction()`` that creates a new SQLAlchemy
20 session, begins a transaction, and handles any integrity errors that might raise from within the transaction.
21
22 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/tutorial/full_app_with_session_di.py
23 :language: python
24 :linenos:
25 :lines: 49-58
26
27 That function is declared as a dependency to the Litestar application, using the name ``transaction``.
28
29 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/tutorial/full_app_with_session_di.py
30 :language: python
31 :linenos:
32 :lines: 102-106
33 :emphasize-lines: 3
34
35 In the route handlers, the database session is injected by adding a parameter named ``transaction`` and marking it with
36 :data:`~litestar.di.NamedDependency`. The marker tells Litestar to supply the value from the ``transaction`` dependency
37 at runtime, matching the parameter name against the dependency key.
38
39
40 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/tutorial/full_app_with_session_di.py
41 :language: python
42 :linenos:
43 :lines: 82-85
44 :emphasize-lines: 2
45
46 One final improvement in this script is exception handling. In the previous version, a
47 :class:`litestar.exceptions.ClientException` is raised inside the ``add_item()`` handler if there's an integrity error
48 raised during the insertion of the new TODO item. In our latest revision, we've been able to centralize this handling
49 to occur inside the ``provide_transaction()`` function.
50
51 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/tutorial/full_app_with_session_di.py
52 :language: python
53 :linenos:
54 :lines: 48-58
55 :emphasize-lines: 3,6-10
56
57 This change broadens the scope of exception handling to any operation that uses the database session, not just the
58 insertion of new items.
59
60 Compare handlers before and after DI
61 ====================================
62
63 Just for fun, lets compare the sets of application handlers before and after we introduced dependency injection for our
64 session object:
65
66 .. tab-set::
67
68 .. tab-item:: After
69
70 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/tutorial/full_app_with_session_di.py
71 :language: python
72 :linenos:
73 :lines: 82-106
74
75 .. tab-item:: Before
76
77 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/tutorial/full_app_no_plugins.py
78 :language: python
79 :linenos:
80 :lines: 69-100
81
82 Much better!
83
84 Next steps
85 ==========
86
87 One of the niceties that we've lost is the ability to receive and return data to/from our handlers as instances of our
88 data model. In the original TODO application, we modelled with Python dataclasses which are natively supported for
89 (de)serialization by Litestar. In the next section, we will look at how we can get this functionality back!