Application basics

First steps

Before we start building our TODO application, let us start with the basics.

Install Litestar

To install Litestar, run pip install 'litestar[standard]'. This will install Litestar as well as uvicorn - a web server to serve your application.

Note

You can use any ASGI-capable web server, but this tutorial will use - and Litestar recommends - Uvicorn.

Hello, world!

The most basic application you can implement - and a classic one at that - is of course one that prints "Hello, world!":

app.py

from litestar import Litestar, get


@get("/")
async def hello_world() -> str:
    return "Hello, world!"


app = Litestar([hello_world])

Now save the contents of this example in a file called app.py and type litestar run in your terminal. This will serve the application locally on your machine. Now visit http://127.0.0.1:8000/ in your browser:

Now that we have a working application, let us examine how we got here in a bit more detail.

Route handlers

Route handlers tell your Litestar application what to do when it gets a request. They are named this way because they typically handle a single URL path (or route), which is the part of the URL that’s specific to your application. In our current example, the only route handler we have is for hello_world, and it is using the / path.

Tip

For example, if your application has a route for handling requests to the /home URL path, you would create a route handler function that would be called when a request to that path is received.

The first argument to the route handler is the path, which in this example has been set to /. This means that the function hello_world will be called when a request is being made to the / path of your application. The name of the handler decorator - get - refers to the HTTP method to which you want to respond. Using get tells Litestar that you only want to use this function when a GET request is being made.

from litestar import Litestar, get


@get("/")
async def hello_world() -> str:
    return "Hello, world!"


app = Litestar([hello_world])

Note

The syntax used in this example (the @get notation) is called a decorator. It’s a function that takes another function as its argument (in this case hello_world) and replaces it with the return value of the decorator function. Without the decorator, the example would look like this:

async def hello_world() -> str:
    return "Hello, world!"


hello_world = get("/")(hello_world)

For an in-depth explanation of decorators, you can read this excellent Real Python article: Primer on Python Decorators

See also

• Route handlers

Type annotations

Type annotations play an important role in a Litestar application. They tell Litestar how you want your data to behave, and what you intend to do with it.

from litestar import Litestar, get


@get("/")
async def hello_world() -> str:
    return "Hello, world!"


app = Litestar([hello_world])

In this example, the hello_world function has a return annotation of -> str. This means that it will return a string, and lets Litestar know that you would like to send the return value as-is.

Note

While type annotations by default don’t have any influence on runtime behaviour, Litestar uses them for many things, for example to validate incoming request data.

If you are using a static type checker - such as mypy or pyright - this has the added benefit of making your applications easy to check and more type-safe.

Applications

After a route handler has been defined, it needs to be registered with an application in order to start serving requests. The application is an instance of the Litestar class. This is the entry point for everything, and can be used to register previously defined route handlers by passing a list of them as the first argument:

from litestar import Litestar, get


@get("/")
async def hello_world() -> str:
    return "Hello, world!"


app = Litestar([hello_world])

See also

• Applications

Running the application

The last step is to actually run the application. Litestar does not include its own HTTP server, but instead makes use of the ASGI protocol, which is a protocol Python objects can use in order to interact with application servers like uvicorn that actually implement the HTTP protocol and handle it for you.

If you installed Litestar with pip install litestar[standard], this will have included uvicorn, as well as the Litestar CLI. The CLI provides a convenient wrapper around uvicorn, allowing you to easily run applications without the need for much configuration.

When you run litestar run, it will recognise the app.py file and the Litestar instance within it without the need to specify this manually.

Tip

You can start the server in “reload mode”, which will reload the application each time you have made a change to the file. For this, simply pass the --reload flag as a command line argument: litestar run --reload.

See also

• CLI