Debian Codegraph @

docs/tutorials/dto-tutorial/index.rst

raw
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