Litestar

Warnings

• breaking Project Rebranding (Starlite to Litestar): With the release of v2.0, the framework was renamed from 'Starlite' to 'Litestar'. All import paths must be updated accordingly (e.g., `from starlite import ...` becomes `from litestar import ...`).
  Fix: Update all `starlite` imports to `litestar`. Review the official v2 migration guide for a complete list of changes.
• breaking Pydantic Integration Changes: Pydantic was removed from Litestar's core in v2.0, making it an optional dependency. While Pydantic models are still fully supported via a plugin, the framework's internal data handling switched to `msgspec` for performance. If you were implicitly relying on Pydantic for non-Pydantic types, behavior might differ.
  Fix: Explicitly install `pydantic` if you need to use Pydantic models. For non-Pydantic types (dataclasses, attrs, msgspec structs), ensure they are correctly typed; Litestar will handle them directly, potentially improving performance.
• breaking Middleware API Evolution: The `MiddlewareProtocol` and `AbstractMiddleware` classes were deprecated around v2.15 in favor of the `ASGIMiddleware` abstract base class. This change simplifies middleware configuration and dispatching.
  Fix: Migrate custom middleware implementations to extend `litestar.middleware.ASGIMiddleware` instead of `AbstractMiddleware`.
• gotcha Strict Type Hinting Enforcement: Litestar rigorously uses and enforces Python type hints for data validation, parsing, serialization, and OpenAPI schema generation. Failing to provide accurate type hints (e.g., return types for route handlers) can lead to runtime exceptions.
  Fix: Always use precise type hints for function arguments and return values in route handlers, dependencies, and DTOs. Ensure Pydantic models, dataclasses, or other data structures are correctly defined.
• gotcha Event Loop Management in Async Tests: When using `httpx.AsyncClient` or the synchronous `TestClient` with async testing frameworks like `pytest-asyncio`, running the Litestar application in a different event loop than the test/fixture can lead to `RuntimeError: Event loop is closed`. This is a common pitfall in async Python testing.
  Fix: Prefer `litestar.testing.AsyncTestClient` for asynchronous tests, as it's designed to manage event loops correctly within the test context. Ensure your test setup respects the asynchronous nature of the client and application.
• gotcha Exception Handler Scope for 404/405 Errors: `NotFoundException` (404) and `MethodNotAllowedException` (405) are raised by Litestar's ASGI Router before the middleware stack is fully invoked. Consequently, these exceptions can only be handled by exception handlers registered directly on the `Litestar` application instance, not by handlers defined on specific controllers or route handlers.
  Fix: If you need to customize responses for 404 or 405 errors, ensure their exception handlers are passed directly to the `Litestar` constructor when initializing your application.

Install

• pip install 'litestar[standard]' Recommended installation including Uvicorn

Imports

• Litestar

  from litestar import Litestar

• get

  from litestar import get

• post

  from litestar import post

• Controller

  from litestar import Controller

• ASGIMiddleware

  from litestar.middleware import ASGIMiddleware

  The `AbstractMiddleware` class was deprecated in Litestar v2.15, favoring `ASGIMiddleware` for creating custom middleware.
• AsyncTestClient

  from litestar.testing import AsyncTestClient

  `TestClient` can cause event loop issues with async fixtures; `AsyncTestClient` is recommended for async testing.
• ASGIConnection

  from litestar.connection import ASGIConnection

  Following the rebranding from Starlite to Litestar in v2.0, all top-level imports and sub-package paths changed.

Quickstart

This minimal example demonstrates how to create a Litestar application with a single GET endpoint. It uses an environment variable for a customizable greeting. The 'litestar run' command requires 'uvicorn', which is included with the 'standard' extra.

from litestar import Litestar, get
import os

@get("/")
async def hello_world() -> str:
    return f"Hello, {os.environ.get('NAME', 'World')}!"

app = Litestar(route_handlers=[hello_world])

# To run this application:
# 1. Save it as app.py
# 2. Run in terminal: litestar run --reload
# 3. Access at http://127.0.0.1:8000/