Data Transfer Object (DTO)

In Litestar, a Data Transfer Object (DTO) is a class that is used to control the flow of data from the client into a useful form for the developer to use in their handler, and then back again.

The following diagram demonstrates how the DTO is used within the context of an individual request in Litestar:

sequenceDiagram autonumber actor Client participant Litestar participant DTO participant Handler Client->>Litestar: Data as encoded bytes activate Litestar Litestar->>DTO: Encoded data deactivate Litestar activate DTO Note over DTO: Perform primitive type validation<br>and conversion into data model DTO->>Handler: Data injected into handler deactivate DTO activate Handler Note over Handler: Handler receives data as type<br>declared in handler signature<br>and performs business logic Handler->>DTO: Data returned from handler deactivate Handler activate DTO Note over DTO: Data returned from the handler<br>is converted into a type that <br>Litestar can encode into bytes DTO->>Litestar: Litestar encodable type deactivate DTO activate Litestar Note over Litestar: Data received from DTO<br>is encoded into bytes Litestar->>Client: Data as encoded bytes deactivate Litestar

Data movement

The following is a short summary of the interaction between each of the participants in the above diagram.

Data moves between each of the participants in the DTO chart, and as it does so, different actions are performed on the data, and it takes different forms depending on the direction of data transfer, and the participants on either end of the transfer. Lets take a look at each of these data movements:

Client → Litestar → DTO

• Data is received from the client as encoded bytes

• In most cases, the unencoded bytes are passed directly to the DTO

• Exception is multipart and URL encoded data, which is decoded into python built-in types before being passed to the DTO

DTO → Handler

• DTO receives data from client

• Performs primitive type validation

• Marshals the data into the data type declared in the handler annotation

Handler → DTO

• Handler receives data as type declared in handler signature

• Developer performs business logic and returns data from handler

DTO → Litestar

• DTO receives data from handler

• Marshals the data into a type that can be encoded into bytes by Litestar

Litestar → Client

• Data is received from the DTO as a type that Litestar can encode into bytes

• Data is encoded into bytes and sent to the client

Contents

• Basic Use
  • DTO layer parameters
  • Defining DTOs on handlers
    • The dto parameter
    • The return_dto parameter
    • Overriding implicit return_dto
  • Defining DTOs on layers
  • Improving performance with the codegen backend
    • Enabling the backend
    • Performance improvements
• AbstractDTO
  • Using DTO Factories
  • Marking fields
  • Excluding fields
  • Renaming fields
  • Type checking
  • Nested fields
  • Handling unknown fields
  • DTO Data
    • Providing values for nested data
  • DTO Factory and PATCH requests
  • Implicit Private Fields
  • Wrapping Return Data
  • Working with Litestar’s Pagination Types
  • Using Litestar’s Response Type with DTO Factory
• Implementing Custom DTO Classes
  • Abstract Methods
    • generate_field_definitions
    • detect_nested_field