Debian Codegraph @

docs/usage/dto/0-basic-use.rst

raw
1 Basic Use
2 =========
3
4 Here we demonstrate how to declare DTO types to your route handlers. For demonstration purposes, we assume that we
5 are working with a data model ``User``, and already have two DTO types created in our application, ``UserDTO``, and
6 ``UserReturnDTO``.
7
8 DTO layer parameters
9 ~~~~~~~~~~~~~~~~~~~~
10
11 On every :ref:`Layer <layered-architecture>` of the Litestar application there are two parameters that control the DTOs
12 that will take responsibility for the data received and returned from handlers:
13
14 - ``dto``: This parameter describes the DTO that will be used to parse inbound data to be injected as the ``data``
15 keyword argument for a handler. Additionally, if no ``return_dto`` is declared on the handler, this will also be used
16 to encode the return data for the handler.
17 - ``return_dto``: This parameter describes the DTO that will be used to encode data returned from the handler. If not
18 provided, the DTO described by the ``dto`` parameter is used.
19
20 The object provided to both of these parameters must be a class that conforms to the
21 :class:`AbstractDTO <litestar.dto.base_dto.AbstractDTO>` protocol.
22
23 Defining DTOs on handlers
24 ~~~~~~~~~~~~~~~~~~~~~~~~~
25
26 The ``dto`` parameter
27 ---------------------
28
29 .. literalinclude:: /examples/data_transfer_objects/the_dto_parameter.py
30 :caption: Using the ``dto`` Parameter
31 :language: python
32
33 In this example, ``UserDTO`` performs decoding of client data into the ``User`` type, and encoding of the returned
34 ``User`` instance into a type that Litestar can encode into bytes.
35
36 The ``return_dto`` parameter
37 ----------------------------
38
39 .. literalinclude:: /examples/data_transfer_objects/the_return_dto_parameter.py
40 :caption: Using the ``return_dto`` Parameter
41 :language: python
42
43 In this example, ``UserDTO`` performs decoding of client data into the ``User`` type, and ``UserReturnDTO`` is
44 responsible for converting the ``User`` instance into a type that Litestar can encode into bytes.
45
46 Overriding implicit ``return_dto``
47 ----------------------------------
48
49 If a ``return_dto`` type is not declared for a handler, the type declared for the ``dto`` parameter is used for both
50 decoding and encoding request and response data. If this behavior is undesirable, it can be disabled by explicitly
51 setting the ``return_dto`` to ``None``.
52
53 .. literalinclude:: /examples/data_transfer_objects/overriding_implicit_return_dto.py
54 :caption: Disable implicit ``return_dto`` behavior
55 :language: python
56
57 In this example, we use ``UserDTO`` to decode request data, and convert it into the ``User`` type, but we want to manage
58 encoding the response data ourselves, and so we explicitly declare the ``return_dto`` as ``None``.
59
60 Defining DTOs on layers
61 ~~~~~~~~~~~~~~~~~~~~~~~
62
63 DTOs can be defined on any :ref:`Layer <layered-architecture>` of the application. The DTO type applied is the one
64 defined in the ownership chain, closest to the handler in question.
65
66 .. literalinclude:: /examples/data_transfer_objects/defining_dtos_on_layers.py
67 :caption: Controller defined DTOs
68 :language: python
69
70 In this example, the ``User`` instance received by any handler that declares a ``data`` kwarg, is converted by the
71 ``UserDTO`` type, and all handler return values are converted into an encodable type by ``UserReturnDTO`` (except for
72 the ``delete()`` route, which has the ``return_dto`` disabled).
73
74 DTOs can similarly be defined on :class:`Routers <litestar.router.Router>` and
75 :class:`The application <litestar.app.Litestar>` itself.
76
77
78 Improving performance with the codegen backend
79 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
80
81 .. note::
82
83 This feature was introduced in ``2.2.0`` and was hidden behind the ``DTO_CODEGEN``
84 feature flag. As of ``2.8.0`` it is considered stable and is enabled by default.
85 It can still be disabled selectively by using the
86 ``DTOConfig(experimental_codegen_backend=False)`` override.
87
88 The DTO backend is the part that does the heavy lifting for all the DTO features. It
89 is responsible for the transforming, validation and parsing. Because of this,
90 it is also the part with the most significant performance impact. To reduce the overhead
91 introduced by the DTOs, the DTO codegen backend was introduced; A DTO backend that
92 increases efficiency by generating optimized Python code at runtime to perform all the
93 necessary operations.
94
95 Disabling the backend
96 ---------------------
97
98 You can use ``experimental_codegen_backend=False``
99 to disable the codegen backend selectively:
100
101 .. code-block:: python
102
103 from dataclasses import dataclass
104 from litestar.dto import DTOConfig, DataclassDTO
105
106
107 @dataclass
108 class Foo:
109 name: str
110
111
112 class FooDTO(DataclassDTO[Foo]):
113 config = DTOConfig(experimental_codegen_backend=False)
114
115 Enabling the backend
116 --------------------
117
118 .. note:: This is a historical document meant for Litestar versions prior to 2.8.0
119 This backend was enabled by default since 2.8.0
120
121 .. warning:: ``ExperimentalFeatures.DTO_CODEGEN`` is deprecated and will be removed in 3.0.0
122
123 .. dropdown:: Enabling DTO codegen backend
124 :icon: git-pull-request-closed
125
126 You can enable this backend globally for all DTOs by passing the appropriate feature
127 flag to your Litestar application:
128
129 .. code-block:: python
130
131 from litestar import Litestar
132 from litestar.config.app import ExperimentalFeatures
133
134 app = Litestar(experimental_features=[ExperimentalFeatures.DTO_CODEGEN])
135
136
137 or selectively for individual DTOs:
138
139 .. code-block:: python
140
141 from dataclasses import dataclass
142 from litestar.dto import DTOConfig, DataclassDTO
143
144
145 @dataclass
146 class Foo:
147 name: str
148
149
150 class FooDTO(DataclassDTO[Foo]):
151 config = DTOConfig(experimental_codegen_backend=True)
152
153 The same flag can be used to disable the backend selectively:
154
155 .. code-block:: python
156
157 from dataclasses import dataclass
158 from litestar.dto import DTOConfig, DataclassDTO
159
160
161 @dataclass
162 class Foo:
163 name: str
164
165
166 class FooDTO(DataclassDTO[Foo]):
167 config = DTOConfig(experimental_codegen_backend=False)
168
169
170 Performance improvements
171 ------------------------
172
173 These are some preliminary numbers showing the performance increase for certain
174 operations:
175
176 =================================== ===========
177 operation improvement
178 =================================== ===========
179 JSON to Python ~2.5x
180 JSON to Python (collection) ~3.5x
181 Python to Python ~2.5x
182 Python to Python (collection) ~5x
183 Python to JSON ~5.3x
184 Python to JSON (collection) ~5.4x
185 =================================== ===========
186
187
188 .. seealso::
189 If you are interested in technical details, check out
190 https://github.com/litestar-org/litestar/pull/2388