Litestar library documentation#
Litestar is a powerful, flexible, highly performant and opinionated ASGI framework, offering first class typing support and a full Pydantic integration.
The Litestar framework supports Plugins, ships with dependency injection, security primitives, OpenAPI schema generation, MessagePack, middlewares and much more.
Installation#
pip install litestar
Extras
- Brotli Compression Middleware:
pip install litestar[brotli]
- Cookie Based Sessions
pip install litestar[cryptography]
- JWT Security Backends
pip install litestar[jwt]
- RedisStore
pip install litestar[redis]
- Picologging
pip install litestar[picologging]
- StructLog
pip install litestar[structlog]
- Open Telemetry Instrumentation
pip install litestar[openetelemetry]
- SQLAlchemy
pip install litestar[sqlalchemy]
- CLI
pip install litestar[cli]
- Jinja Templating
pip install litestar[jinja]
- Attrs
pip install litestar[attrs]
- Standard Installation (includes CLI and Jinja templating):
pip install litestar[standard]
- All Extras:
pip install litestar[full]
Minimal Example#
Define your data model using pydantic or any library based on it (for example ormar, beanie, SQLModel):
from pydantic import BaseModel, UUID4
class User(BaseModel):
first_name: str
last_name: str
id: UUID4
You can also use dataclasses (standard library and Pydantic),
typing.TypedDict
or msgspec.Struct
.
from uuid import UUID
# from pydantic.dataclasses import dataclass
from dataclasses import dataclass
@dataclass
class User:
first_name: str
last_name: str
id: UUID
Define a Controller for your data model:
from typing import List
from pydantic import UUID4
from litestar import Controller, get, post, put, patch, delete
from litestar.partial import Partial
from my_app.models import User
class UserController(Controller):
path = "/users"
@post()
async def create_user(self, data: User) -> User:
...
@get()
async def list_users(self) -> List[User]:
...
@patch(path="/{user_id:uuid}")
async def partial_update_user(self, user_id: UUID4, data: Partial[User]) -> User:
...
@put(path="/{user_id:uuid}")
async def update_user(self, user_id: UUID4, data: User) -> 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:
...
from pydantic import UUID4
from litestar import Controller, get, post, put, patch, delete
from litestar.partial import Partial
from my_app.models import User
class UserController(Controller):
path = "/users"
@post()
async def create_user(self, data: User) -> User:
...
@get()
async def list_users(self) -> list[User]:
...
@patch(path="/{user_id:uuid}")
async def partial_update_user(self, user_id: UUID4, data: Partial[User]) -> User:
...
@put(path="/{user_id:uuid}")
async def update_user(self, user_id: UUID4, data: User) -> 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:
...
When instantiating your app, import your controller into your application’s entry-point and pass it to Litestar:
from litestar import Litestar
from my_app.controllers.user import UserController
app = Litestar(route_handlers=[UserController])
To run your application, use an ASGI server such as uvicorn :
uvicorn my_app.main:app --reload
Philosophy#
Litestar is a community-driven project. This means not a single author, but rather a core team of maintainers is leading the project, supported by a community of contributors. Litestar currently has 5 maintainers and is being very actively developed.
Litestar draws inspiration from NestJS - a contemporary TypeScript framework - which places opinions and patterns at its core.
While still allowing for function-based endpoints, Litestar seeks to build on Python’s powerful and versatile OOP, by placing class-based controllers at its core.
Litestar is not a microframework. Unlike frameworks such as FastAPI, Starlette or Flask, Litestar includes a lot of functionalities out of the box needed for a typical modern web application, such as ORM integration, client- and server-side sessions, caching, OpenTelemetry integration and many more. It’s not aiming to be “the next Django” (for example, it will never feature its own ORM), but its scope is not micro either.
Feature comparison with similar frameworks#
Litestar |
FastAPI |
Starlette |
Sanic |
Quart |
|
---|---|---|---|---|---|
OpenAPI |
|||||
Automatic API documentation |
Swagger, ReDoc, Stoplight Elements |
Swagger, ReDoc |
|||
Data validation |
|||||
Dependency Injection |
|||||
Class based routing |
(Through extension) |
||||
ORM integration |
SQLAlchemy, Tortoise, Piccolo |
(Through extension) |
|||
Templating |
Jinja, Mako |
Jinja |
Jinja |
Jinja |
Jinja |
MessagePack |
|||||
CORS |
(Through extension) |
||||
CSRF |
|||||
Rate-limiting |
(Through extension) |
||||
JWT |
|||||
Sessions |
Client-side |
Client-side |
Client-side |
||
Authentication |
JWT / Session based |
||||
Caching |
Example Applications#
litestar-pg-redis-docker : In addition to Litestar, this demonstrates a pattern of application modularity, SQLAlchemy 2.0 ORM, Redis cache connectivity, and more. Like all Litestar projects, this application is open to contributions, big and small.
litestar-hello-world: A bare-minimum application setup. Great for testing and POC work.