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