litestar Documentation

File: README.md Copy Chapter

Litestar is a powerful, flexible yet opinionated ASGI framework, focused on
building APIs. It offers high-performance data validation, dependency injection,
first-class ORM integration, authorization primitives, a rich plugin API, middleware,
and much more that's needed to get applications up and running.

Check out the documentation 📚 for a detailed overview of
its features!

Additionally, the Litestar fullstack repository
can give you a good impression how a fully fledged Litestar application may look.

Table of Contents

• Installation
  • Quick Start
• Core Features
  • Example Applications
• Features
  • Class-based Controllers
  • Data Parsing, Type Hints, and Msgspec
  • Plugin System, ORM support, and DTOs
  • OpenAPI
  • Dependency Injection
  • Middleware
  • Route Guards
  • Request Life Cycle Hooks
• Performance
• Contributing

Installation Copy Chapter

pip install litestar

or to include the CLI and a server (uvicorn) for running your application:

pip install 'litestar[standard]'

Quick Start Copy Chapter

from litestar import Litestar, get

@get("/")
async def hello_world() -> dict[str, str]:
    """Keeping the tradition alive with hello world."""
    return {"hello": "world"}

app = Litestar(route_handlers=[hello_world])

And run it with

litestar run

Core Features Copy Chapter

• Class based controllers
• Dependency Injection
• Layered Middleware
• Plugin System
• OpenAPI 3.1 schema generation
• Life Cycle Hooks
• Route Guards based Authorization
• Support for dataclasses, TypedDict, msgspec, pydantic version 1 and version 2 (even within the same application) and (c)attrs
• Layered parameter declaration
• Support for RFC 9457 standardized "Problem Detail" error responses
• Automatic API documentation with:
  • Scalar
  • Redoc
  • Stoplight Elements
  • Swagger-UI
• Trio support (built-in, via AnyIO)
• Ultra-fast validation, serialization and deserialization using msgspec
• SQLAlchemy integration

Example Applications Copy Chapter

Pre-built Example Apps

• litestar-hello-world: A bare-minimum application setup. Great
  for testing and POC work.
• litestar-fullstack: A reference application that contains most of the boilerplate required for a web application.
  It features a Litestar app configured with best practices, SQLAlchemy 2.0 and SAQ, a frontend integrated with Vitejs and Jinja2 templates, Docker, and more. Like all
  Litestar projects, this application is open to contributions, big and small.

Sponsors Copy Chapter

Litestar is an open-source project, and we enjoy the support of our sponsors to help fund the exciting
work we do.

A huge thanks to our sponsors:

Check out our sponsors in the docs

If you would like to support the work that we do please consider becoming a sponsor
via Polar.sh (preferred), GitHub or Open Collective.

Also, exclusively with Polar, you can engage in pledge-based sponsorships.

Features Copy Chapter

Class-based Controllers Copy Section

While supporting function-based route handlers, Litestar also supports and promotes python OOP using class based
controllers:

Example for class-based controllers

from typing import List, Optional
from datetime import datetime

from litestar import Controller, get, post, put, patch, delete
from litestar.dto import DTOData
from pydantic import UUID4

from my_app.models import User, PartialUserDTO


class UserController(Controller):
    path = "/users"

    @post()
    async def create_user(self, data: User) -> User: ...

    @get()
    async def list_users(self) -> List[User]: ...

    @get(path="/{date:int}")
    async def list_new_users(self, date: datetime) -> List[User]: ...

    @patch(path="/{user_id:uuid}", dto=PartialUserDTO)
    async def partial_update_user(
        self, user_id: UUID4, data: DTOData[PartialUserDTO]
    ) -> User: ...

    @put(path="/{user_id:uuid}")
    async def update_user(self, user_id: UUID4, data: User) -> User: ...

    @get(path="/{user_name:str}")
    async def get_user_by_name(self, user_name: str) -> Optional[User]: ...

    @get(path="/{user_id:uuid}")
    async def get_user(self, user_id: UUID4) -> User: ...

    @delete(path="/{user_id:uuid}")
    async def delete_user(self, user_id: UUID4) -> None: ...

Data Parsing, Type Hints, and Msgspec Copy Section

Litestar is rigorously typed, and it enforces typing. For example, if you forget to type a return value for a route
handler, an exception will be raised. The reason for this is that Litestar uses typing data to generate OpenAPI specs,
as well as to validate and parse data. Thus, typing is essential to the framework.

Furthermore, Litestar allows extending its support using plugins.

Plugin System, ORM support, and DTOs Copy Section

Litestar has a plugin system that allows the user to extend serialization/deserialization, OpenAPI generation, and other
features.

It ships with a builtin plugin for SQL Alchemy, which allows the user to use SQLAlchemy declarative classes "natively"
i.e., as type parameters that will be serialized/deserialized and to return them as values from route
handlers.

Litestar also supports the programmatic creation of DTOs with a DTOFactory class, which also supports the use of
plugins.

OpenAPI Copy Section

Litestar has custom logic to generate OpenAPI 3.1.0 schema, include optional generation of examples using the
polyfactory library.

ReDoc, Swagger-UI and Stoplight Elements API Documentation

Litestar serves the documentation from the generated OpenAPI schema with:

• ReDoc
• Swagger-UI
• Stoplight Elements

All these are available and enabled by default.

Dependency Injection Copy Section

Litestar has a simple but powerful DI system inspired by pytest. You can define named dependencies - sync or async - at
different levels of the application, and then selective use or overwrite them.

Example for DI

from litestar import Litestar, get
from litestar.di import Provide


async def my_dependency() -> str: ...


@get("/")
async def index(injected: str) -> str:
    return injected


app = Litestar([index], dependencies={"injected": Provide(my_dependency)})

Middleware Copy Section

Litestar supports typical ASGI middleware and ships with middlewares to handle things such as

• CORS
• CSRF
• Rate limiting
• GZip, Brotli, and Zstd compression
• Client- and server-side sessions

Route Guards Copy Section

Litestar has an authorization mechanism called guards, which allows the user to define guard functions at different
level of the application (app, router, controller etc.) and validate the request before hitting the route handler
function.

Example for route guards

from litestar import Litestar, get

from litestar.connection import ASGIConnection
from litestar.handlers.base import BaseRouteHandler
from litestar.exceptions import NotAuthorizedException


async def is_authorized(connection: ASGIConnection, handler: BaseRouteHandler) -> None:
    # validate authorization
    # if not authorized, raise NotAuthorizedException
    raise NotAuthorizedException()


@get("/", guards=[is_authorized])
async def index() -> None: ...


app = Litestar([index])

Request Life Cycle Hooks Copy Section

Litestar supports request life cycle hooks, similarly to Flask - i.e. before_request and after_request

Performance Copy Chapter

Litestar is fast. It is on par with, or significantly faster than comparable ASGI frameworks.

You can see and run the benchmarks here,
or read more about it here in our documentation.

Contributing Copy Chapter

Litestar is open to contributions big and small. You can always join our discord server
or join our Matrix space
to discuss contributions and project maintenance. For guidelines on how to contribute, please
see the contribution guide.

Contributors ✨ Copy Chapter

Thanks goes to these wonderful people:
Emoji Key

This project follows the all-contributors specification.
Contributions of any kind welcome!

File: docs/admonitions/sync-to-thread-info.rst Copy Chapter

.. admonition:: Synchronous and asynchronous callables
:class: important

Both synchronous and asynchronous callables are supported. One important aspect of
this is that using a synchronous function which perform blocking operations, such
as I/O or computationally intensive tasks, can potentially block the main thread
running the event loop, and in turn block the whole application.

To mitigate this, the ``sync_to_thread`` parameter can be set to ``True``, which
will result in the function being run in a thread pool.

If a synchronous function is non-blocking, setting ``sync_to_thread`` to ``False``
will tell Litestar that the user is sure about its behavior
and the function can be treated as non-blocking.

If a synchronous function is passed, without setting an explicit ``sync_to_thread``
value, a warning will be raised.

.. seealso::

    :doc:`/topics/sync-vs-async`

File: docs/migration/fastapi.rst Copy Chapter

:orphan:

For FastAPI and Starlette users

This content has moved to :doc:/onboarding/fastapi

File: docs/migration/flask.rst Copy Chapter

:orphan:

From Flask

This content has moved to :doc:/onboarding/flask

File: docs/migration/index.rst Copy Chapter

:orphan:

Onboarding from other frameworks

This content has moved to :doc:/onboarding/index

File: docs/reference/channels/backends/asyncpg.rst Copy Chapter

asyncpg

.. automodule:: litestar.channels.backends.asyncpg
:members:

File: docs/reference/channels/backends/index.rst Copy Chapter

backends

.. toctree::

base
memory
redis
psycopg
asyncpg

File: docs/reference/channels/backends/psycopg.rst Copy Chapter

psycopg

.. automodule:: litestar.channels.backends.psycopg
:members: