Debian Codegraph @

docs/usage/databases/sqlalchemy/plugins/sqlalchemy_serialization_plugin.rst

raw
1 SQLAlchemy Serialization Plugin
2 -------------------------------
3
4 The SQLAlchemy Serialization Plugin allows Litestar to do the work of transforming inbound and outbound data to and from
5 SQLAlchemy models. The plugin takes no arguments, simply instantiate it and pass it to your application.
6
7 Example
8 =======
9
10 .. tab-set::
11
12 .. tab-item:: Async
13
14 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_async_serialization_plugin.py
15 :caption: SQLAlchemy Async Serialization Plugin
16 :language: python
17 :linenos:
18
19 .. tab-item:: Sync
20
21 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_sync_serialization_plugin.py
22 :caption: SQLAlchemy Sync Serialization Plugin
23 :language: python
24 :linenos:
25
26 How it works
27 ============
28
29 The plugin works by defining a :class:`SQLAlchemyDTO <advanced_alchemy.extensions.litestar.dto.SQLAlchemyDTO>` class for each
30 handler ``data`` or return annotation that is a SQLAlchemy model, or collection of SQLAlchemy models, that isn't
31 otherwise managed by an explicitly defined DTO class.
32
33 The following two examples are functionally equivalent:
34
35 .. tab-set::
36
37 .. tab-item:: Serialization Plugin
38
39 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_async_serialization_plugin.py
40 :language: python
41 :linenos:
42
43 .. tab-item:: Data Transfer Object
44
45 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_async_serialization_dto.py
46 :language: python
47 :linenos:
48
49 During registration, the application recognizes that there is no DTO class explicitly defined and determines that the
50 handler annotations are supported by the SQLAlchemy Serialization Plugin. The plugin is then used to generate a DTO
51 class for both the ``data`` keyword argument and the return annotation.
52
53 Configuring data transfer
54 #########################
55
56 As the serialization plugin merely defines DTOs for the handler, we can
57 :ref:`mark the model fields <dto-marking-fields>` to control the data that we allow in and out of
58 our application.
59
60 .. tab-set::
61
62 .. tab-item:: Async
63
64 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_async_serialization_plugin_marking_fields.py
65 :caption: SQLAlchemy Async Marking Fields
66 :language: python
67 :linenos:
68 :emphasize-lines: 9,23,28
69
70 .. tab-item:: Sync
71
72 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_sync_serialization_plugin_marking_fields.py
73 :caption: SQLAlchemy Sync Marking Fields
74 :language: python
75 :linenos:
76 :emphasize-lines: 9,23,28
77
78 In the above example, a new attribute called ``super_secret_value`` has been added to the model, and a value set for it
79 in the handler. However, due to "marking" the field as "private", when the model is serialized, the value is not present
80 in the response.