Debian Codegraph @

docs/tutorials/todo-app/0-application-basics.rst

raw
1 Application basics
2 ==================
3
4 First steps
5 ------------
6
7 Before we start building our TODO application, let us start with the basics.
8
9
10 Install Litestar
11 ++++++++++++++++
12
13 To install Litestar, run ``pip install 'litestar[standard]'``. This will install Litestar
14 as well as `uvicorn <https://www.uvicorn.org/>`_ - a web server to serve your application.
15
16 .. note::
17 You can use any ASGI-capable web server, but this tutorial will use - and Litestar
18 recommends - Uvicorn.
19
20
21 Hello, world!
22 +++++++++++++
23
24 The most basic application you can implement - and a classic one at that - is of course
25 one that prints ``"Hello, world!"``:
26
27
28 .. literalinclude:: /examples/todo_app/hello_world.py
29 :language: python
30 :caption: ``app.py``
31
32
33 Now save the contents of this example in a file called ``app.py`` and type
34 ``litestar run`` in your terminal. This will serve the application locally on your
35 machine. Now visit http://127.0.0.1:8000/ in your browser:
36
37 .. image:: images/hello_world.png
38
39
40 Now that we have a working application, let us examine how we got here in a bit more detail.
41
42
43 Route handlers
44 ---------------
45
46 Route handlers tell your Litestar application what to do when it gets a request.
47 They are named this way because they typically handle a single URL path (or *route*),
48 which is the part of the URL that's specific to your application. In our current
49 example, the only route handler we have is for ``hello_world``, and it is using the
50 ``/`` path.
51
52 .. tip::
53 For example, if your application has a route for handling requests to the ``/home``
54 URL path, you would create a route handler function that would be called when a
55 request to that path is received.
56
57 The first argument to the route handler is the *path*, which in this example has been
58 set to ``/``. This means that the function ``hello_world`` will be called when a request
59 is being made to the ``/`` path of your application. The name of the handler decorator
60 - ``get`` - refers to the HTTP method to which you want to respond. Using ``get`` tells
61 Litestar that you only want to use this function when a ``GET`` request is being made.
62
63
64 .. literalinclude:: /examples/todo_app/hello_world.py
65 :language: python
66 :emphasize-lines: 4
67 :linenos:
68
69
70 .. note::
71
72 The syntax used in this example (the ``@get`` notation) is called a decorator. It's
73 a function that takes another function as its argument (in this case ``hello_world``)
74 and replaces it with the return value of the decorator function.
75 Without the decorator, the example would look like this:
76
77 .. code-block:: python
78
79 async def hello_world() -> str:
80 return "Hello, world!"
81
82
83 hello_world = get("/")(hello_world)
84
85 For an in-depth explanation of decorators, you can read this excellent Real Python
86 article: `Primer on Python Decorators <https://realpython.com/primer-on-python-decorators/>`_
87
88
89 .. seealso::
90
91 * :doc:`/usage/routing/handlers`
92
93
94 Type annotations
95 ----------------
96
97 Type annotations play an important role in a Litestar application. They tell Litestar
98 how you want your data to behave, and what you intend to do with it.
99
100
101 .. literalinclude:: /examples/todo_app/hello_world.py
102 :language: python
103 :emphasize-lines: 5
104 :linenos:
105
106
107 In this example, the ``hello_world`` function has a return annotation of ``-> str``.
108 This means that it will return a :class:`string <str>`, and lets Litestar know that
109 you would like to send the return value as-is.
110
111 .. note::
112 While type annotations by default don't have any influence on runtime behaviour,
113 Litestar uses them for many things, for example to validate incoming request data.
114
115 If you are using a static type checker - such as
116 `mypy <https://mypy.readthedocs.io/en/stable/>`_ or
117 `pyright <https://microsoft.github.io/pyright/#/>`_ - this has the added benefit of
118 making your applications easy to check and more type-safe.
119
120
121
122 Applications
123 ------------
124
125 After a route handler has been defined, it needs to be registered with an application
126 in order to start serving requests. The application is an instance of the
127 :class:`Litestar <litestar.app.Litestar>` class. This is the entry point for everything,
128 and can be used to register previously defined route handlers by passing a list of them
129 as the first argument:
130
131 .. literalinclude:: /examples/todo_app/hello_world.py
132 :language: python
133 :emphasize-lines: 9
134 :linenos:
135
136
137 .. seealso::
138
139 * :doc:`/usage/applications`
140
141
142
143 Running the application
144 -----------------------
145
146 The last step is to actually run the application. Litestar does not include its own HTTP
147 server, but instead makes use of the
148 `ASGI protocol <https://asgi.readthedocs.io>`_, which is a protocol Python objects can
149 use in order to interact with application servers like
150 `uvicorn <https://www.uvicorn.org/>`_ that actually implement the HTTP protocol and
151 handle it for you.
152
153 If you installed Litestar with ``pip install 'litestar[standard]'``, this will have
154 included *uvicorn*, as well as the Litestar CLI. The CLI provides a convenient wrapper
155 around uvicorn, allowing you to easily run applications without the need for much
156 configuration.
157
158 When you run ``litestar run``, it will recognise the ``app.py`` file and the
159 ``Litestar`` instance within it without the need to specify this manually.
160
161 .. tip::
162 You can start the server in "reload mode", which will reload the application each
163 time you have made a change to the file. For this, simply pass the ``--reload``
164 flag as a command line argument: ``litestar run --reload``.
165
166
167 .. seealso::
168
169 * :doc:`/usage/cli`