Debian Codegraph @

docs/usage/dto/index.rst

raw
1 Data Transfer Object (DTO)
2 ==========================
3
4 In Litestar, a Data Transfer Object (DTO) is a class that is used to control the flow of data from the client into a
5 useful form for the developer to use in their handler, and then back again.
6
7 The following diagram demonstrates how the DTO is used within the context of an individual request in Litestar:
8
9
10 .. mermaid::
11
12 sequenceDiagram
13 autonumber
14 actor Client
15 participant Litestar
16 participant DTO
17 participant Handler
18 Client->>Litestar: Data as encoded bytes
19 activate Litestar
20 Litestar->>DTO: Encoded data
21 deactivate Litestar
22 activate DTO
23 Note over DTO: Perform primitive type validation<br>and conversion into data model
24 DTO->>Handler: Data injected into handler
25 deactivate DTO
26 activate Handler
27 Note over Handler: Handler receives data as type<br>declared in handler signature<br>and performs business logic
28 Handler->>DTO: Data returned from handler
29 deactivate Handler
30 activate DTO
31 Note over DTO: Data returned from the handler<br>is converted into a type that <br>Litestar can encode into bytes
32 DTO->>Litestar: Litestar encodable type
33 deactivate DTO
34 activate Litestar
35 Note over Litestar: Data received from DTO<br>is encoded into bytes
36 Litestar->>Client: Data as encoded bytes
37 deactivate Litestar
38
39 Data movement
40 -------------
41
42 The following is a short summary of the interaction between each of the participants in the above diagram.
43
44 Data moves between each of the participants in the DTO chart, and as it does so, different actions are performed on the
45 data, and it takes different forms depending on the direction of data transfer, and the participants on either end of
46 the transfer. Lets take a look at each of these data movements:
47
48 Client → Litestar → DTO
49 ~~~~~~~~~~~~~~~~~~~~~~~~~
50 - Data is received from the client as encoded bytes
51 - In most cases, the unencoded bytes are passed directly to the DTO
52 - Exception is multipart and URL encoded data, which is decoded into python built-in types before being passed to the
53 DTO
54
55 DTO → Handler
56 ~~~~~~~~~~~~~~~~
57 - DTO receives data from client
58 - Performs primitive type validation
59 - Marshals the data into the data type declared in the handler annotation
60
61 Handler → DTO
62 ~~~~~~~~~~~~~~~~
63 - Handler receives data as type declared in handler signature
64 - Developer performs business logic and returns data from handler
65
66 DTO → Litestar
67 ~~~~~~~~~~~~~~~~~~~~~~~~~
68 - DTO receives data from handler
69 - Marshals the data into a type that can be encoded into bytes by Litestar
70
71 Litestar → Client
72 ~~~~~~~~~~~~~~~~~~
73 - Data is received from the DTO as a type that Litestar can encode into bytes
74 - Data is encoded into bytes and sent to the client
75
76 Contents
77 --------
78
79 .. toctree::
80
81 0-basic-use
82 1-abstract-dto
83 2-creating-custom-dto-classes