| 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 |