| 1 |
Data Transfer Object Tutorial |
| 2 |
============================= |
| 3 |
|
| 4 |
.. admonition:: Who is this tutorial for? |
| 5 |
:class: info |
| 6 |
|
| 7 |
This tutorial is intended to familiarize you with the basic concepts of Litestar's |
| 8 |
Data Transfer Objects (DTOs). It is assumed that you are already familiar with |
| 9 |
Litestar and fundamental concepts such as route handlers. If not, it is recommended |
| 10 |
to first follow the |
| 11 |
`Developing a basic TODO application <../todo-app>`_ tutorial. |
| 12 |
|
| 13 |
In this tutorial, we will walk through the process of modelling a simple data structure, and demonstrate how Litestar's |
| 14 |
DTO factories can be used to help us build flexible applications. Lets get started! |
| 15 |
|
| 16 |
.. literalinclude:: /examples/data_transfer_objects/factory/tutorial/initial_pattern.py |
| 17 |
:language: python |
| 18 |
:caption: ``app.py`` |
| 19 |
|
| 20 |
In this script, we define a data model, a route handler and an application instance. |
| 21 |
|
| 22 |
Our data model is a Python :func:`dataclass <dataclasses.dataclass>` called ``Person`` which has three attributes: |
| 23 |
``name``, ``age``, and ``email``. |
| 24 |
|
| 25 |
The function called ``get_person`` that is decorated with :class:`@get() <litestar.handlers.get>` is a route handler |
| 26 |
with path ``/person/{name:str}``, that serves `GET <https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET>`_ |
| 27 |
requests. In the path, ``{name:str}`` represents a path parameter called ``name`` with a string type. The route handler |
| 28 |
receives the name from the path parameter and returns a ``Person`` object. |
| 29 |
|
| 30 |
Finally, we create an application instance and register the route handler with it. |
| 31 |
|
| 32 |
In Litestar, this pattern works "out-of-the-box" - that is, returning :func:`dataclass <dataclasses.dataclass>` |
| 33 |
instances from handlers is natively supported. Litestar will take that dataclass instance, and transform it into |
| 34 |
:class:`bytes` that can be sent over the network. |
| 35 |
|
| 36 |
Lets run it and see for ourselves! |
| 37 |
|
| 38 |
Save the above script as ``app.py``, run it using the ``litestar run`` command, and then visit |
| 39 |
`<http://localhost:8000/person/peter>`_ in your browser. You should see the |
| 40 |
following: |
| 41 |
|
| 42 |
.. image:: images/initial_pattern.png |
| 43 |
:align: center |
| 44 |
|
| 45 |
However, real-world applications are rarely this simple. What if we want to restrict the information about users that we |
| 46 |
expose after they have been created? For example, we may want to hide the user's email address from the response. This |
| 47 |
is where Data Transfer Objects come in. |
| 48 |
|
| 49 |
.. toctree:: |
| 50 |
:hidden: |
| 51 |
|
| 52 |
01-simple-dto-exclude |
| 53 |
02-nested-exclude |
| 54 |
03-nested-collection-exclude |
| 55 |
04-max-nested-depth |
| 56 |
05-renaming-fields |
| 57 |
06-receiving-data |
| 58 |
07-read-only-fields |
| 59 |
08-dto-data |
| 60 |
09-updating |
| 61 |
10-layered-dto-declarations |