Litestar is a performant ASGI API framework. pip install litestar[full]. Route: from litestar import get, post, Litestar. Handler: @get("/users") async def list_users() -> list[User]: return []. App: app = Litestar(route_handlers=[list_users]). Run: uvicorn app:app. Path params: @get("/users/{user_id:int}"). Query params: async def fn(page: int = 1, limit: int = 20). Request body: @post("/users") async def create(data: CreateUserDTO) -> UserDTO. DTOs: from litestar.dto import DataclassDTO, SQLAlchemyDTO. Dependency injection: from litestar.di import Provide. @get("/", dependencies={"repo": Provide(get_repo)}). Guard: class AuthGuard(Guard): async def __call__(self, connection, handler): if not connection.user: raise NotAuthorizedException(). @get("/admin", guards=[AuthGuard()]). Middleware: from litestar.middleware import AbstractMiddleware. Router: Router(path="/api/v1", route_handlers=[users_router, orders_router]). Exception handler: @app.exception_handler(ValidationException). Response: Response(content=data, status_code=201, headers={...}). Status codes: @get(status_code=200). OpenAPI: auto-generated at /schema. @get(summary="List users", operation_id="listUsers"). Pagination: from litestar.pagination import CursorPagination, OffsetPagination. AbstractRepository: class UserRepo(AbstractRepository[User]): async def get(self, id): .... SQLAlchemyAsyncRepository(model_type=User, session=session). Params: field_definitions = {FieldDefinition.from_annotation(str, name="email")}. Testing: from litestar.testing import AsyncTestClient. async with AsyncTestClient(app) as client: resp = await client.get("/users"). Lifespan events: @on_startup, @on_shutdown. app.on_startup.append(init_db). Claude Code generates Litestar route handlers, DTO definitions, Guard implementations, and test suites.
CLAUDE.md for Litestar
## Litestar Stack
- Version: litestar >= 2.9 | pip install "litestar[full]"
- Route: @get @post @put @patch @delete decorators with path + type hints
- DI: dependencies={"name": Provide(factory_fn)} per route or router
- DTO: DataclassDTO[ModelClass] | from_encodable for custom serialization
- Guard: class G(Guard): async def __call__(connection, handler): raise if denied
- Router: Router(path="/api/v1", route_handlers=[...]) for modular groups
- Test: AsyncTestClient(app) — full ASGI test client, no server neededLitestar API Pipeline
# app/litestar_app.py — Litestar API with routing, DI, DTOs, guards, and tests
from __future__ import annotations
import logging
from dataclasses import dataclass, field
from datetime import datetime
from typing import Annotated, Optional
from uuid import UUID, uuid4
from litestar import Litestar, MediaType, Router, delete, get, patch, post, put
from litestar.connection import ASGIConnection
from litestar.datastructures import State
from litestar.di import Provide
from litestar.dto import DataclassDTO
from litestar.exceptions import (
HTTPException,
NotAuthorizedException,
NotFoundException,
ValidationException,
)
from litestar.handlers import BaseRouteHandler
from litestar.middleware import AbstractMiddleware
from litestar.openapi.config import OpenAPIConfig
from litestar.openapi.spec import Contact
from litestar.pagination import OffsetPagination
from litestar.params import Parameter
from litestar.response import Response
from litestar.security.abstract import AbstractSecurityConfig
from litestar.status_codes import HTTP_201_CREATED, HTTP_204_NO_CONTENT
from litestar.testing import AsyncTestClient
from litestar.types import Guard
logger = logging.getLogger(__name__)
# ─────────────────────────────────────────────────────────────────────────────
# Data models (dataclasses — DTO works with plain dataclasses)
# ─────────────────────────────────────────────────────────────────────────────
@dataclass
class Address:
street: str
city: str
state: str
postal_code: str
@dataclass
class User:
id: UUID
email: str
first_name: str
last_name: str
role: str = "user"
is_active: bool = True
address: Optional[Address] = None
created_at: datetime = field(default_factory=datetime.utcnow)
@dataclass
class CreateUserRequest:
email: str
first_name: str
last_name: str
password: str
role: str = "user"
@dataclass
class UpdateUserRequest:
first_name: Optional[str] = None
last_name: Optional[str] = None
role: Optional[str] = None
# ─────────────────────────────────────────────────────────────────────────────
# DTO classes — control which fields are exposed
# ─────────────────────────────────────────────────────────────────────────────
class UserResponseDTO(DataclassDTO[User]):
"""Response DTO — exposes all fields except those excluded below."""
config = DataclassDTO.generate_config(exclude=frozenset())
class CreateUserDTO(DataclassDTO[CreateUserRequest]):
"""Request DTO for creating users — excludes password from response."""
pass
# ─────────────────────────────────────────────────────────────────────────────
# In-memory repository (replace with SQLAlchemy in production)
# ─────────────────────────────────────────────────────────────────────────────
class UserRepository:
def __init__(self) -> None:
self._store: dict[UUID, User] = {}
# Seed some data
for name, email in [("Alice Smith", "[email protected]"),
("Bob Jones", "[email protected]")]:
first, last = name.split()
u = User(id=uuid4(), email=email, first_name=first, last_name=last)
self._store[u.id] = u
def list(self, page: int = 1, page_size: int = 20) -> tuple[list[User], int]:
all_users = list(self._store.values())
total = len(all_users)
start = (page - 1) * page_size
return all_users[start: start + page_size], total
def get(self, user_id: UUID) -> User:
user = self._store.get(user_id)
if user is None:
raise NotFoundException(detail=f"User {user_id} not found")
return user
def create(self, data: CreateUserRequest) -> User:
if any(u.email == data.email for u in self._store.values()):
raise HTTPException(status_code=409, detail="Email already in use")
user = User(
id=uuid4(),
email=data.email,
first_name=data.first_name,
last_name=data.last_name,
role=data.role,
)
self._store[user.id] = user
return user
def update(self, user_id: UUID, updates: UpdateUserRequest) -> User:
user = self.get(user_id)
if updates.first_name: user.first_name = updates.first_name
if updates.last_name: user.last_name = updates.last_name
if updates.role: user.role = updates.role
return user
def delete(self, user_id: UUID) -> None:
self.get(user_id) # raises NotFoundException if absent
del self._store[user_id]
# Singleton for demo (use DI factory in production)
_REPO = UserRepository()
def get_user_repo() -> UserRepository:
return _REPO
# ─────────────────────────────────────────────────────────────────────────────
# Guards
# ─────────────────────────────────────────────────────────────────────────────
async def require_authenticated(
connection: ASGIConnection,
handler: BaseRouteHandler,
) -> None:
"""Check that the request carries a valid token (header-based for demo)."""
auth_header = connection.headers.get("authorization", "")
if not auth_header.startswith("Bearer "):
raise NotAuthorizedException(detail="Bearer token required")
async def require_admin(
connection: ASGIConnection,
handler: BaseRouteHandler,
) -> None:
"""Check the token encodes admin role (simplified — use JWT in production)."""
auth_header = connection.headers.get("authorization", "")
if "admin-token" not in auth_header:
raise NotAuthorizedException(detail="Admin access required")
# ─────────────────────────────────────────────────────────────────────────────
# Route handlers
# ─────────────────────────────────────────────────────────────────────────────
@get("/")
async def health() -> dict:
return {"status": "ok", "version": "1.0"}
@get(
"/users",
return_dto=UserResponseDTO,
)
async def list_users(
repo: UserRepository,
page: Annotated[int, Parameter(ge=1, default=1)],
page_size: Annotated[int, Parameter(ge=1, le=100, default=20)],
) -> OffsetPagination[User]:
items, total = repo.list(page=page, page_size=page_size)
return OffsetPagination[User](
items=items,
total=total,
limit=page_size,
offset=(page - 1) * page_size,
)
@get(
"/users/{user_id:uuid}",
return_dto=UserResponseDTO,
)
async def get_user(user_id: UUID, repo: UserRepository) -> User:
return repo.get(user_id)
@post(
"/users",
dto=CreateUserDTO,
return_dto=UserResponseDTO,
status_code=HTTP_201_CREATED,
guards=[require_authenticated],
)
async def create_user(data: CreateUserRequest, repo: UserRepository) -> User:
return repo.create(data)
@patch(
"/users/{user_id:uuid}",
return_dto=UserResponseDTO,
guards=[require_authenticated],
)
async def update_user(
user_id: UUID,
data: UpdateUserRequest,
repo: UserRepository,
) -> User:
return repo.update(user_id, data)
@delete(
"/users/{user_id:uuid}",
status_code=HTTP_204_NO_CONTENT,
guards=[require_admin],
)
async def delete_user(user_id: UUID, repo: UserRepository) -> None:
repo.delete(user_id)
# ─────────────────────────────────────────────────────────────────────────────
# Router — group related handlers
# ─────────────────────────────────────────────────────────────────────────────
users_router = Router(
path="/api/v1",
route_handlers=[list_users, get_user, create_user, update_user, delete_user],
dependencies={"repo": Provide(get_user_repo, sync_to_thread=False)},
tags=["Users"],
)
# ─────────────────────────────────────────────────────────────────────────────
# Application
# ─────────────────────────────────────────────────────────────────────────────
app = Litestar(
route_handlers=[health, users_router],
openapi_config=OpenAPIConfig(
title="Demo API",
version="1.0.0",
contact=Contact(name="Engineering", email="[email protected]"),
),
debug=False,
)
# ─────────────────────────────────────────────────────────────────────────────
# Tests
# ─────────────────────────────────────────────────────────────────────────────
async def run_tests() -> None:
async with AsyncTestClient(app=app) as client:
# Health check
response = await client.get("/")
assert response.status_code == 200
assert response.json()["status"] == "ok"
# List users
response = await client.get("/api/v1/users")
assert response.status_code == 200
users = response.json()
assert users["total"] >= 2
# Get specific user
user_id = users["items"][0]["id"]
response = await client.get(f"/api/v1/users/{user_id}")
assert response.status_code == 200
# Create user without auth — should fail
response = await client.post("/api/v1/users", json={
"email": "[email protected]", "first_name": "New",
"last_name": "User", "password": "pass123"})
assert response.status_code == 401
# Create user with auth token
response = await client.post(
"/api/v1/users",
json={"email": "[email protected]", "first_name": "New",
"last_name": "User", "password": "pass123"},
headers={"Authorization": "Bearer some-token"},
)
assert response.status_code == 201
new_id = response.json()["id"]
# Delete without admin — should fail
response = await client.delete(
f"/api/v1/users/{new_id}",
headers={"Authorization": "Bearer some-token"},
)
assert response.status_code == 401
# Delete with admin token
response = await client.delete(
f"/api/v1/users/{new_id}",
headers={"Authorization": "Bearer admin-token"},
)
assert response.status_code == 204
print("All tests passed.")
if __name__ == "__main__":
import asyncio, uvicorn # noqa: E401
asyncio.run(run_tests())
uvicorn.run("app.litestar_app:app", host="0.0.0.0", port=8000, reload=True)For the FastAPI alternative — FastAPI uses Pydantic models in function signatures for both validation and OpenAPI schema generation, while Litestar’s DTO layer separates the ORM/dataclass from what is serialized: DataclassDTO.generate_config(exclude=frozenset({"password"})) strips the password from the response without a separate response model class, annotations.Guard guards execute before the handler and raise NotAuthorizedException or PermissionDeniedException with structured error payloads, and OffsetPagination returns a standard {"items": [...], "total": N, "limit": N, "offset": N} shape from any handler returning a list. For the Django REST Framework alternative — DRF is synchronous and requires Serializer, ViewSet, permissions.IsAuthenticated, and a router.register() call for each resource, while Litestar’s @get("/users/{user_id:uuid}") handles path parameter parsing, Parameter(ge=1, le=100) validates query params, and Provide(get_repo, sync_to_thread=False) injects the repository without a class-based view — async all the way. The Claude Skills 360 bundle includes Litestar skill sets covering get/post/put/patch/delete decorators, DataclassDTO for request and response shaping, Provide dependency injection, Guard for route authorization, Router for modular grouping, Parameter for query param validation, OffsetPagination, AsyncTestClient for testing, OpenAPIConfig schema generation, and middleware integration. Start with the free tier to try high-performance API code generation.