Debian Codegraph @

docs/usage/dto/1-abstract-dto.rst

raw
1 AbstractDTO
2 ===========
3
4 Litestar maintains a suite of DTO factory types that can be used to create DTOs for use with popular data modelling
5 libraries, such as ORMs. These take a model type as a generic type argument, and create subtypes of
6 :class:`AbstractDTO <litestar.dto.base_dto.AbstractDTO>` that support conversion of that model type to
7 and from raw bytes.
8
9 The following factories are currently available:
10
11 - :class:`DataclassDTO <litestar.dto.dataclass_dto.DataclassDTO>`
12 - :class:`MsgspecDTO <litestar.dto.msgspec_dto.MsgspecDTO>`
13 - :class:`PydanticDTO <litestar.plugins.pydantic.PydanticDTO>`
14 - :class:`SQLAlchemyDTO <advanced_alchemy.extensions.litestar.dto.SQLAlchemyDTO>`
15
16 Using DTO Factories
17 -------------------
18
19 DTO factories are used to create DTOs for use with a particular data modelling library. The following example creates
20 a DTO for use with a SQLAlchemy model:
21
22 .. literalinclude:: /examples/data_transfer_objects/factory/simple_dto_factory_example.py
23 :caption: A SQLAlchemy model DTO
24 :language: python
25
26 Here we see that a SQLAlchemy model is used as both the ``data`` and return annotation for the handler, and while
27 Litestar does not natively support encoding/decoding to/from SQLAlchemy models, through
28 :class:`SQLAlchemyDTO <advanced_alchemy.extensions.litestar.dto.SQLAlchemyDTO>` we can do this.
29
30 However, we do have some issues with the above example. Firstly, the user's password has been returned to them in the
31 response from the handler. Secondly, the user is able to set the ``created_at`` field on the model, which should only
32 ever be set once, and defined internally.
33
34 Let's explore how we can configure DTOs to manage scenarios like these.
35
36 .. _dto-marking-fields:
37
38 Marking fields
39 --------------
40
41 The :func:`dto_field <litestar.dto.field.dto_field>` function can be used to mark model attributes with DTO-based
42 configuration.
43
44 Fields marked as ``"private"`` or ``"read-only"`` will not be parsed from client data into the user model, and
45 ``"private"`` fields are never serialized into return data.
46
47 .. literalinclude:: /examples/data_transfer_objects/factory/marking_fields.py
48 :caption: Marking fields
49 :language: python
50 :emphasize-lines: 6,14,15
51 :linenos:
52
53 Note that ``id`` field is the primary key and is handled specially by the defined SQLAlchemy base.
54
55 .. note:
56
57 The procedure for "marking" a model field will vary depending on the library. For example,
58 :class:`DataclassDTO <.dto.DataclassDTO>` expects that the mark is made in the ``metadata``
59 parameter to ``dataclasses.field``.
60
61 Excluding fields
62 ----------------
63
64 Fields can be explicitly excluded using :class:`DTOConfig <litestar.dto.config.DTOConfig>`.
65
66 The following example demonstrates excluding attributes from the serialized response, including excluding fields from
67 nested models.
68
69 .. literalinclude:: /examples/data_transfer_objects/factory/excluding_fields.py
70 :caption: Excluding fields
71 :language: python
72 :emphasize-lines: 6,10,37-46,49
73 :linenos:
74
75 Here, the config is created with the exclude parameter, which is a set of strings. Each string represents the path to a
76 field in the ``User`` object that should be excluded from the output DTO.
77
78 .. code-block:: python
79
80 config = DTOConfig(
81 exclude={
82 "id",
83 "address.id",
84 "address.street",
85 "pets.0.id",
86 "pets.0.user_id",
87 }
88 )
89
90 In this example, ``"id"`` represents the id field of the ``User`` object, ``"address.id"`` and ``"address.street"``
91 represent fields of the ``Address`` object nested inside the ``User`` object, and ``"pets.0.id"`` and
92 ``"pets.0.user_id"`` represent fields of the ``Pets`` objects nested within the list of ``User.pets``.
93
94 .. note::
95
96 Given a generic type, with an arbitrary number of type parameters (e.g., ``GenericType[Type0, Type1, ..., TypeN]``),
97 we use the index of the type parameter to indicate which type the exclusion should refer to. For example, ``a.0.b``,
98 excludes the ``b`` field from the first type parameter of ``a``, ``a.1.b`` excludes the ``b`` field from the second
99 type parameter of ``a``, and so on.
100
101 Renaming fields
102 ---------------
103
104 Fields can be renamed using :class:`DTOConfig <litestar.dto.config.DTOConfig>`. The following example uses the name
105 ``userName`` client-side, and ``user`` internally.
106
107 .. literalinclude:: /examples/data_transfer_objects/factory/renaming_fields.py
108 :caption: Renaming fields
109 :language: python
110 :emphasize-lines: 4,8,19,20,24
111 :linenos:
112
113 Fields can also be renamed using a renaming strategy that will be applied to all fields. The following example uses a pre-defined rename strategy that will convert all field names to camel case on client-side.
114
115 .. literalinclude:: /examples/data_transfer_objects/factory/renaming_all_fields.py
116 :caption: Renaming fields
117 :language: python
118 :emphasize-lines: 4,8,19,20,21,22,24
119 :linenos:
120
121 Fields that are directly renamed using `rename_fields` mapping will be excluded from `rename_strategy`.
122
123 The rename strategy either accepts one of the pre-defined strategies: "camel", "pascal", "upper", "lower", "kebab", or it can be provided a callback that accepts the field name as a string argument and should return a string.
124
125 Type checking
126 -------------
127
128 Factories check that the types to which they are assigned are a subclass of the type provided as the generic type to the
129 DTO factory. This means that if you have a handler that accepts a ``User`` model, and you assign a ``UserDTO`` factory
130 to it, the DTO will only accept ``User`` types for "data" and return types.
131
132 .. literalinclude:: /examples/data_transfer_objects/factory/type_checking.py
133 :caption: Type checking
134 :language: python
135 :emphasize-lines: 25,26,31
136 :linenos:
137
138 In the above example, the handler is declared to use ``UserDTO`` which has been type-narrowed with the ``User`` type.
139 However, we annotate the handler with the ``Foo`` type. This will raise an error such as this at runtime:
140
141 litestar.exceptions.dto.InvalidAnnotationException: DTO narrowed with
142 '<class 'docs.examples.data_transfer_objects.factory.type_checking.User'>', handler type is
143 '<class 'docs.examples.data_transfer_objects.factory.type_checking.Foo'>'
144
145 Nested fields
146 -------------
147
148 The depth of related items parsed from client data and serialized into return data can be controlled using the
149 ``max_nested_depth`` parameter to :class:`DTOConfig <litestar.dto.config.DTOConfig>`.
150
151 In this example, we set ``max_nested_depth=0`` for the DTO that handles inbound client data, and leave it at the default
152 of ``1`` for the return DTO.
153
154 .. literalinclude:: /examples/data_transfer_objects/factory/related_items.py
155 :caption: Type checking
156 :language: python
157 :emphasize-lines: 25,35,39
158 :linenos:
159
160 When the handler receives the client data, we can see that the ``b`` field has not been parsed into the ``A`` model that
161 is injected for our data parameter (line 35).
162
163 We then add a ``B`` instance to the data (line 39), which includes a reference back to ``a``, and from inspection of the
164 return data can see that ``b`` is included in the response data, however ``b.a`` is not, due to the default
165 ``max_nested_depth`` of ``1``.
166
167 Handling unknown fields
168 -----------------------
169
170 By default, DTOs will silently ignore unknown fields in the source data. This behaviour
171 can be configured using the ``forbid_unknown_fields`` parameter of the
172 :class:`DTOConfig <litestar.dto.config.DTOConfig>`. When set to ``True`` a validation
173 error response will be returned if the data contains a field not defined on the model:
174
175 .. literalinclude:: /examples/data_transfer_objects/factory/unknown_fields.py
176 :caption: Type checking
177 :language: python
178 :linenos:
179
180
181 DTO Data
182 --------
183
184 Sometimes we need to be able to access the data that has been parsed and validated by the DTO, but not converted into
185 an instance of our data model.
186
187 In the following example, we create a ``User`` model, that is a :func:`dataclass <dataclasses.dataclass>` with 3
188 required fields: ``id``, ``name``, and ``age``.
189
190 We also create a DTO that doesn't allow clients to set the ``id`` field on the ``User`` model and set it on the
191 handler.
192
193 .. literalinclude:: /examples/data_transfer_objects/factory/dto_data_problem_statement.py
194 :language: python
195 :emphasize-lines: 18-21,27
196 :linenos:
197
198 Notice that our `User` model has a model-level ``default_factory=uuid4``
199 for ``id`` field. That's why we can decode the client data into this model.
200
201 However, in some cases there's no clear way to provide a default this way.
202
203 One way to handle this is to create different models, e.g., we might create a ``UserCreate`` model that has no ``id``
204 field, and decode the client data into that. However, this method can become quite cumbersome when we have a lot of
205 variability in the data that we accept from clients, for example,
206 `PATCH <https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH>`_ requests.
207
208 This is where the :class:`DTOData <litestar.dto.data_structures.DTOData>` class comes in. It is a generic class that accepts the
209 type of the data that it will contain, and provides useful methods for interacting with that data.
210
211 .. literalinclude:: /examples/data_transfer_objects/factory/dto_data_usage.py
212 :language: python
213 :emphasize-lines: 5,23,25
214 :linenos:
215
216 In the above example, we've injected an instance of :class:`DTOData <litestar.dto.data_structures.DTOData>` into our handler,
217 and have used that to create our ``User`` instance, after augmenting the client data with a server generated ``id``
218 value.
219
220 Consult the :class:`Reference Docs <litestar.dto.data_structures.DTOData>` for more information on the methods available.
221
222 .. _dto-create-instance-nested-data:
223
224 Providing values for nested data
225 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
226
227 To augment data used to instantiate our model instances, we can provide keyword arguments to the
228 :meth:`create_instance() <litestar.dto.data_structures.DTOData.create_instance>` method.
229
230 Sometimes we need to provide values for nested data, for example, when creating a new instance of a model that has a
231 nested model with excluded fields.
232
233 .. literalinclude:: /examples/data_transfer_objects/factory/providing_values_for_nested_data.py
234 :language: python
235 :emphasize-lines: 9-12,20,28,34
236 :linenos:
237
238 The double-underscore syntax ``address__id`` passed as a keyword argument to the
239 :meth:`create_instance() <litestar.dto.data_structures.DTOData.create_instance>` method call is used to specify a value for a
240 nested attribute. In this case, it's used to provide a value for the ``id`` attribute of the ``Address`` instance nested
241 within the ``Person`` instance.
242
243 This is a common convention in Python for dealing with nested structures. The double underscore can be interpreted as
244 "traverse through", so ``address__id`` means "traverse through address to get to its id".
245
246 In the context of this script, ``create_instance(id=1, address__id=2)`` is saying "create a new ``Person`` instance from
247 the client data given an id of ``1``, and supplement the client address data with an id of ``2``".
248
249 DTO Factory and PATCH requests
250 ------------------------------
251
252 `PATCH <https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH>`_ requests are a special case when it comes to
253 data transfer objects. The reason for this is that we need to be able to accept and validate any subset of the model
254 attributes in the client payload, which requires some special handling internally.
255
256 .. literalinclude:: /examples/data_transfer_objects/factory/patch_requests.py
257 :language: python
258 :emphasize-lines: 7,20,27,28,30
259 :linenos:
260
261 The ``PatchDTO`` class is defined for the ``Person`` class. The ``config`` attribute of ``PatchDTO`` is set to exclude the
262 ``id`` field, preventing clients from setting it when updating a person, and the ``partial`` attribute is set to ``True``,
263 which allows the DTO to accept a subset of the model attributes.
264
265 Inside the handler, the :meth:`DTOData.update_instance <litestar.dto.data_structures.DTOData.update_instance>` method is called
266 to update the instance of ``Person`` before returning it.
267
268 In our request, we update only the ``name`` property of the ``Person``, from ``"Peter"`` to ``"Peter Pan"`` and receive
269 the full object - with the modified name - back in the response.
270
271 Implicit Private Fields
272 -----------------------
273
274 Fields that are named with a leading underscore are considered "private" by default. This means that they will not be
275 parsed from client data, and will not be serialized into return data.
276
277 .. literalinclude:: /examples/data_transfer_objects/factory/leading_underscore_private.py
278 :language: python
279 :linenos:
280
281 This can be overridden by setting the
282 :attr:`DTOConfig.leading_underscore_private <litestar.dto.config.DTOConfig.underscore_fields_private>` attribute to
283 ``False``.
284
285 .. literalinclude:: /examples/data_transfer_objects/factory/leading_underscore_private_override.py
286 :language: python
287 :linenos:
288 :emphasize-lines: 14,15
289
290 Wrapping Return Data
291 --------------------
292
293 Litestar's DTO Factory types are versatile enough to manage your data, even when it's nested within generic wrappers.
294
295 The following example demonstrates a route handler that returns DTO managed data wrapped in a generic type. The
296 wrapper is used to deliver additional metadata about the response - in this case, a count of the number of items
297 returned. Read on for an explanation of how to do this yourself.
298
299 .. literalinclude:: /examples/data_transfer_objects/factory/enveloping_return_data.py
300 :caption: Enveloping Return Data
301 :language: python
302 :linenos:
303
304 First, create a generic dataclass to act as your wrapper. This type will contain your data and any additional
305 attributes you might need. In this example, we have a ``WithCount`` dataclass which has a ``count`` attribute.
306 The wrapper must be a python generic type with one or more type parameters, and at least one of those type parameters
307 should describe an instance attribute that will be populated with the data.
308
309 .. code-block:: python
310
311 from dataclasses import dataclass
312 from typing import Generic, TypeVar
313
314 T = TypeVar("T")
315
316
317 @dataclass
318 class WithCount(Generic[T]):
319 count: int
320 data: List[T]
321
322
323 Now, create a DTO for your data object and configure it using ``DTOConfig``. In this example, we're excluding
324 ``password`` and ``created_at`` from the final output.
325
326 .. code-block:: python
327
328 from advanced_alchemy.dto import SQLAlchemyDTO
329 from litestar.dto import DTOConfig
330
331
332 class UserDTO(SQLAlchemyDTO[User]):
333 config = DTOConfig(exclude={"password", "created_at"})
334
335 Then, set up your route handler. This example sets up a ``/users`` endpoint, where a list of ``User`` objects is
336 returned, wrapped in the ``WithCount`` dataclass.
337
338 .. code-block:: python
339
340 from litestar import get
341
342
343 @get("/users", dto=UserDTO, sync_to_thread=False)
344 def get_users() -> WithCount[User]:
345 return WithCount(
346 count=1,
347 data=[
348 User(
349 id=1,
350 name="Litestar User",
351 password="xyz",
352 created_at=datetime.now(),
353 ),
354 ],
355 )
356
357
358 This setup allows the DTO to manage the rendering of ``User`` objects into the response. The DTO Factory type will find
359 the attribute on the wrapper type that holds the data and perform its serialization operations upon it.
360
361 Returning enveloped data is subject to the following constraints:
362
363 #. The type returned from the handler must be a type that Litestar can natively encode.
364 #. There can be multiple type arguments to the generic wrapper type, but there must be exactly one type argument to the
365 generic wrapper that is a type supported by the DTO.
366
367 Working with Litestar's Pagination Types
368 ----------------------------------------
369
370 Litestar offers paginated response wrapper types, and DTO Factory types can handle this out of the box.
371
372 .. literalinclude:: /examples/data_transfer_objects/factory/paginated_return_data.py
373 :caption: Paginated Return Data
374 :language: python
375 :linenos:
376
377 The DTO is defined and configured, in our example, we're excluding ``password`` and ``created_at`` fields from the final
378 representation of our users.
379
380 .. code-block:: python
381
382 from advanced_alchemy.dto import SQLAlchemyDTO
383 from litestar.dto import DTOConfig
384
385
386 class UserDTO(SQLAlchemyDTO[User]):
387 config = DTOConfig(exclude={"password", "created_at"})
388
389 The example sets up a ``/users`` endpoint, where a paginated list of ``User`` objects is returned, wrapped in
390 :class:`ClassicPagination <.pagination.ClassicPagination>`.
391
392 .. code-block:: python
393
394 from litestar import get
395 from litestar.pagination import ClassicPagination
396
397
398 @get("/users", dto=UserDTO, sync_to_thread=False)
399 def get_users() -> ClassicPagination[User]:
400 return ClassicPagination(
401 page_size=10,
402 total_pages=1,
403 current_page=1,
404 items=[
405 User(
406 id=1,
407 name="Litestar User",
408 password="xyz",
409 created_at=datetime.now(),
410 ),
411 ],
412 )
413
414 The :class:`ClassicPagination <.pagination.ClassicPagination>` class contains ``page_size`` (number of items per page),
415 ``total_pages`` (total number of pages), ``current_page`` (current page number), and ``items`` (items for the current
416 page).
417
418 The DTO operates on the data contained in the ``items`` attribute, and the pagination wrapper is handled automatically
419 by Litestar's serialization process.
420
421 Using Litestar's Response Type with DTO Factory
422 -----------------------------------------------
423
424 Litestar's DTO (Data Transfer Object) Factory Types can handle data wrapped in a ``Response`` type.
425
426 .. literalinclude:: /examples/data_transfer_objects/factory/response_return_data.py
427 :caption: Response Wrapped Return Data
428 :language: python
429 :linenos:
430
431 We create a DTO for the ``User`` type and configure it using ``DTOConfig`` to exclude ``password`` and ``created_at``
432 from the serialized output.
433
434 .. code-block:: python
435
436 from advanced_alchemy.dto import SQLAlchemyDTO
437 from litestar.dto import DTOConfig
438
439
440 class UserDTO(SQLAlchemyDTO[User]):
441 config = DTOConfig(exclude={"password", "created_at"})
442
443
444 The example sets up a ``/users`` endpoint where a ``User`` object is returned wrapped in a ``Response`` type.
445
446 .. code-block:: python
447
448 from litestar import get, Response
449
450
451 @get("/users", dto=UserDTO, sync_to_thread=False)
452 def get_users() -> Response[User]:
453 return Response(
454 content=User(
455 id=1,
456 name="Litestar User",
457 password="xyz",
458 created_at=datetime.now(),
459 ),
460 headers={"X-Total-Count": "1"},
461 )
462
463 The ``Response`` object encapsulates the ``User`` object in its ``content`` attribute and allows us to configure the
464 response received by the client. In this case, we add a custom header.