Litestar

https://docs.litestar.dev/2
Admin
Litestar is a powerful, flexible, and highly performant ASGI framework that provides dependency...
Tokens:613,053
Snippets:5,122
Trust Score:8.4
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Synchronous repository example imports and model setup

Source: https://docs.litestar.dev/2/tutorials/repository-tutorial/03-repository-controller.html

Starts the synchronous version of the repository example, showing imports and the BaseModel and AuthorModel definitions. This is the beginning of the synchronous implementation that mirrors the async example.

```python
from __future__ import annotations

from datetime import date
from typing import TYPE_CHECKING, Annotated
from uuid import UUID

from pydantic import BaseModel as _BaseModel
from pydantic import TypeAdapter
from sqlalchemy import ForeignKey, select
from sqlalchemy.orm import Mapped, mapped_column, relationship, selectinload

from litestar import Litestar, get
from litestar.controller import Controller
from litestar.di import Provide
from litestar.handlers.http_handlers.decorators import delete, patch, post
from litestar.pagination import OffsetPagination
from litestar.params import PathParameter, QueryParameter
from litestar.plugins.sqlalchemy import (
    SQLAlchemyInitPlugin,
    SQLAlchemySyncConfig,
    base,
    repository,
)
from litestar.repository.filters import LimitOffset

if TYPE_CHECKING:
    from sqlalchemy.orm import Session


class BaseModel(_BaseModel):
    """Extend Pydantic's BaseModel to enable ORM mode"""

    model_config = {"from_attributes": True}


# The SQLAlchemy base includes a declarative model for you to use in your models.
# The `UUIDBase` class includes a `UUID` based primary key (`id`)
class AuthorModel(base.UUIDBase):
```

--------------------------------

### Example update command

Source: https://docs.litestar.dev/2/topics/deployment/supervisor.html

Extends the exampleapp function with an update command that stops the service, pulls latest code, updates symlinks, reloads Supervisor, installs dependencies, and prompts to start the service.

```bash
exampleapp() {
  case $1 in
    # ... other cases ... #

    update)
      echo "Updating exampleapp..."

      # Stop the service
      echo " > Stopping service..."
      sudo supervisorctl stop exampleapp

      # Update application files
      echo " > Pulling latest changes from repository..."
      cd /opt/exampleapp
      git fetch --all
      git reset --hard origin/master

      # Update Supervisor configuration and alias
      echo " > Updating Supervisor and shell configurations..."
      sudo ln -sf /opt/exampleapp/server/service.conf /etc/supervisor/conf.d/exampleapp.conf
      sudo ln -sf /opt/exampleapp/server/alias.sh /etc/profile.d/exampleapp.sh
      source /etc/profile.d/exampleapp.sh

      # Update Supervisor to apply new configurations
      echo " > Reloading Supervisor configuration..."
      sudo supervisorctl reread
      sudo supervisorctl update

      # Update Python dependencies using requirements.txt
      # Here you could replace with poetry, pdm, etc., alleviating the need for
      # a requirements.txt file and virtual environment activation.
      source venv/bin/activate
      echo " > Installing updated dependencies..."
      python3 -m pip install -r requirements.txt
      deactivate

      # ... other update processes like docs building, cleanup, etc. ... #

      echo "Update process complete."

      # Prompt to start the service
      read -p "Start the service? (y/n) " -n 1 -r
      echo
      if [[ $REPLY =~ ^[Yy]$ ]]
      then
          echo " > Starting service..."
          sudo supervisorctl start exampleapp
      fi
      ;;

    # ... #
  esac
}

```

--------------------------------

### Example commands provided by the alias file

Source: https://docs.litestar.dev/2/topics/deployment/supervisor.html

Shows the commands made available by the alias file: start, stop, restart, status, and watch.

```bash
exampleapp start
exampleapp stop
exampleapp restart
exampleapp status
exampleapp watch

```

--------------------------------

### Run it - curl command

Source: https://docs.litestar.dev/2/usage/plugins/index.html

Command to test the example by sending a GET request with a query parameter. Expected output is 'hello'.

```bash
> curl http://127.0.0.1:8000/?param=hello
hello

```

--------------------------------

### Using StaticFilesConfig (before)

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Previous approach for static file serving using StaticFilesConfig. This is shown as the 'instead of' example.

```python
app = Litestar(
    static_files_config=[StaticFilesConfig(path="/static", directories=["some_dir"])]
)

```

--------------------------------

### Correct OpenAPI examples rendering

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Shows the correct rendering of OpenAPI examples after the fix. The examples are placed as a sibling of the schema object.

```json
{
  "parameters": [
    {
      "schema": {
        "type": "string"
      },
      "examples": {
        "example1": {
          "summary": "example summary"
          "value": "example value"
        }
      }
    }
  ]
}

```

--------------------------------

### JSON schema examples format (correct)

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Shows the correct JSON schema examples format, which is an array of values. This format should be used in JSON schema objects instead of the OpenAPI example format.

```json
"examples": [
  "the real beef"
]

```

--------------------------------

### OpenAPI examples format before fix

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Shows the model definition and the generated OpenAPI example before the fix, which wrapped the value in an object with 'description' and 'value' keys.

```python
@dataclass
class Foo:
    foo: int

```

```json
{
    "description": "Example value",
    "value": {
        "foo": 7906
    }
}

```

--------------------------------

### OpenAPI examples format after fix

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Shows the corrected OpenAPI example format after the fix, where the wrapping object is removed and the value is directly the object.

```json
{
    "foo": 7906
}

```

--------------------------------

### Incorrect OpenAPI examples rendering

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Shows the incorrect rendering of OpenAPI examples before the fix. The examples are placed inside the schema object instead of being a sibling of it.

```json
{
  "parameters": [
    {
      "schema": {
        "type": "string",
        "examples": [
          {
            "summary": "example summary",
            "value": "example value"
          }
        ]
      }
    }
  ]
}

```

--------------------------------

### OpenAPI example format (incorrect for JSON schema)

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Shows the OpenAPI example format that was incorrectly used in JSON schema objects. This format is not valid for JSON schema and must be avoided.

```json
"examples": {
  "some-id": {
    "description": "Lorem ipsum",
    "value": "the real beef"
  }
}

```

--------------------------------

### ResponseSpec examples JSON structure

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Shows the JSON structure for defining custom examples in OpenAPI responses via ResponseSpec. The examples are generated locally for each response and cannot be set within the schema definition.

```json
{
"paths": {
    "/": {
    "get": {
        "responses": {
        "200": {
            "content": {
            "application/json": {
                "schema": {},
                "examples": "..."}}
            }}
        }}
    }
}

}
```

--------------------------------

### Explicit parameter markers example

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Shows the new way using FromQuery and FromPath markers to explicitly declare parameter sources, making the code clearer and allowing errors to be caught earlier.

```python
@get("/")
async def handler(one: FromQuery[str], two: FromPath[str]) -> None:
    pass

router = Router("/{two:str}", route_handlers=[handler])

```

--------------------------------

### Route handler with Parameter annotation

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Example of using Parameter directly in a route handler annotation to specify field constraints.

```python
@get("/")
def index(param: int = Parameter(gt=5)) -> dict[str, int]: ...
```

--------------------------------

### Validation error response before change

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Example of a validation error response before the change, showing keys without full path and no 'source' key.

```json
{
  "status_code": 400,
  "detail": "Validation failed for POST http://localhost:8000/some-route",
  "extra": [
    {"key": "int_param", "message": "value is not a valid integer"},
    {"key": "int_header", "message": "value is not a valid integer"},
    {"key": "int_cookie", "message": "value is not a valid integer"},
    {"key": "my_value", "message": "value is not a valid integer"}
  ]
}
```

--------------------------------

### Implicit parameter declaration example

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Shows the old way of declaring parameters where 'one' is implicitly a query parameter and 'two' is a path parameter from the router. This can lead to ambiguity when the handler is used in different contexts.

```python
@get("/")
async def handler(one: str, two: str) -> None:
    pass

router = Router("/{two:str}", route_handlers=[handler])

```

--------------------------------

### ServerSentEvent usage with async generator

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Example of using the new ServerSentEvent with an async generator that yields count values. The handler returns a ServerSentEvent instance.

```python
async def my_generator() -> AsyncGenerator[bytes, None]:
    count = 0
    while count < 10:
        await sleep(0.01)
        count += 1
        yield str(count)


@get(path="/count")
def sse_handler() -> ServerSentEvent:
    return ServerSentEvent(my_generator())

```

--------------------------------

### RedisChannelsPubSubBackend.on_startup()

Source: https://docs.litestar.dev/2/reference/channels/backends/redis.html

Performs startup tasks for the pub/sub backend.

```APIDOC
## RedisChannelsPubSubBackend.on_startup()

### Description
Performs startup tasks for the pub/sub backend.

### Method
Async method

### Signature
`async on_startup(self) -> None`

```

--------------------------------

### Correctly handle single file upload validation when multiple files are specified

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Example of a file upload endpoint that expects a list of files. Previously, uploading a single file caused a ValidationException; now it is handled correctly.

```python
class FileUpload(Struct):
    files: list[UploadFile]


@post(path="/")
async def upload_files_object(
    data: Annotated[FileUpload, Body(media_type=RequestEncodingType.MULTI_PART)]
) -> list[str]:
    pass

```

--------------------------------

### Run example app with curl

Source: https://docs.litestar.dev/2/contribution-guide.html

Run the example app and observe the output of the curl request.

```bash
> curl http://127.0.0.1:8000/
{"hello": "world"}

```

--------------------------------

### Function with default parameter value

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Example of a function with a default parameter value, used to illustrate a bug where the default was not set on the schema when no metadata was provided via Annotated.

```python
def get_foo(foo_id: int = 10) -> None:
    ...

```

--------------------------------

### Useful Docker commands

Source: https://docs.litestar.dev/2/topics/deployment/docker.html

Commands to build, run, stop, start, and remove a Docker container named exampleapp.

```bash
# Build the container
docker build -t exampleapp .

# Run the container
docker run -d -p 80:80 --name exampleapp exampleapp

# Stop the container
docker stop exampleapp

# Start the container
docker start exampleapp

# Remove the container
docker rm exampleapp

```

--------------------------------

### GET /test

Source: https://docs.litestar.dev/2/reference/testing.html

Example of retrieving session data using a GET endpoint.

```APIDOC
## [GET] /test

### Description
Retrieves session data from the session store. The session data is returned as a JSON object.

### Method
GET

### Endpoint
/test

### Parameters
#### Request Body
- **request** (Request) - Required - The request object containing the session data.

### Request Example
```python
from litestar import Litestar, get
from litestar.middleware.session.memory_backend import MemoryBackendConfig

session_config = MemoryBackendConfig()

@get(path="/test")
def get_session_data(request: Request) -> Dict[str, Any]:
    return request.session

app = Litestar(route_handlers=[get_session_data], middleware=[session_config.middleware])

with TestClient(app=app, session_config=session_config) as client:
    client.set_session_data({"foo": "bar"})
    assert client.get("/test").json() == {"foo": "bar"}
```

### Response
#### Success Response (200)
- **session** (dict) - The session data.

#### Response Example
```json
{"foo": "bar"}
```
```

--------------------------------

### Pydantic 2 model with extra='ignore' config

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Example of a Pydantic 2 model with `model_config = ConfigDict(extra='ignore')`. This configuration is used to demonstrate how `forbid_unknown_fields` is set to `True` by default for Pydantic models with `extra='forbid'`.

```python
class User(BaseModel):
    model_config = ConfigDict(extra='ignore')
    name: str

```

--------------------------------

### GET /page (MediaType.HTML)

Source: https://docs.litestar.dev/2/usage/responses.html

Example of a GET route handler that returns an HTML response using the MediaType.HTML enum.

```APIDOC
## [GET] /page

### Description
Returns an HTML response. The `media_type` is set to `MediaType.HTML`, and the route handler returns a string containing HTML.

### Method
GET

### Endpoint
/page

### Parameters
#### Query Parameters
- None

### Request Example
No request body.

### Response
#### Success Response (200)
- **body** (string) - The HTML content.

#### Response Example
"<html>\n    <body>\n        <div>\n            <span>Hello World!</span>\n        </div>\n    </body>\n</html>"
```

--------------------------------

### Run the example with curl

Source: https://docs.litestar.dev/2/usage/dto/1-abstract-dto.html

Runs the example server and sends a POST request to /users with a JSON body. The response echoes the created user, including the password and the client-supplied created_at value, illustrating the issues discussed next.

```bash
> curl http://127.0.0.1:8000/users -H Content-Type: application/json -d {"name":"Litestar User","password":"xyz","created_at":"2023-04-24T00:00:00Z"}
{"id":"8450b3ed-a1e8-4887-9355-b9a67f52a3ce","name":"Litestar User","password":"xyz","created_at":"2023-04-24T00:00:00Z"}

```

--------------------------------

### Middleware with greedy exclude pattern

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Example of a middleware class with an `exclude` list containing `"/"` and `"/home"`. This configuration triggers a warning at application startup because the pattern `"/"` greedily matches all paths, silently disabling the middleware for every route.

```python
from litestar.middlewares

class MyMiddleware(AbstractMiddleware):
    exclude = ["/", "/home"]

    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
        await self.app(scope, receive, send)

```

--------------------------------

### ExceptionHandler typing for Exception subclasses

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Example of a custom exception handler that accepts a subclass of Exception. This code demonstrates the fix for ExceptionHandler typing to properly support Exception subclasses.

```python
from litestar import Request, Response


class CustomException(Exception): ...


def handle_exc(req: Request, exc: CustomException) -> Response: ...

```

--------------------------------

### Validation error response after change

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Example of a validation error response after the change, showing keys with full path and an optional 'source' key indicating the origin (body, query, header, cookie).

```json
{
  "status_code": 400,
  "detail": "Validation failed for POST http://localhost:8000/some-route",
  "extra": [
    {"key": "child.my_value", "message": "value is not a valid integer", "source": "body"},
    {"key": "int_param", "message": "value is not a valid integer", "source": "query"},
    {"key": "int_header", "message": "value is not a valid integer", "source": "header"},
    {"key": "int_cookie", "message": "value is not a valid integer", "source": "cookie"},
  ]
}
```

--------------------------------

### GET /health-check (MediaType.MESSAGEPACK)

Source: https://docs.litestar.dev/2/usage/responses.html

Example of a GET route handler that returns a MessagePack response using the MediaType.MESSAGEPACK enum.

```APIDOC
## [GET] /health-check

### Description
Returns a MessagePack response. The `media_type` is set to `MediaType.MESSAGEPACK`, which serializes the response in MessagePack format.

### Method
GET

### Endpoint
/health-check

### Parameters
#### Query Parameters
- None

### Request Example
No request body.

### Response
#### Success Response (200)
- **hello** (string) - A greeting message.

#### Response Example
{
  "hello": "world"
}
```

--------------------------------

### Example of data declared in dependency only

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Shows a Litestar handler where `data` is declared only in a dependency function, causing the request body to be missing from the OpenAPI schema. The bugfix ensures `data` is always documented and that annotations are compatible between dependencies and handlers.

```python
from litestar import post, Litestar

async def some_dependency(data: list[str]) -> list[str]:
    return data

@post("/", dependencies={"some_data": some_dependency})
async def handler(some_data: list[str]) -> None:

```

--------------------------------

### ProblemDetailsPlugin.on_app_init() example

Source: https://docs.litestar.dev/2/reference/plugins/problem_details.html

Example for ProblemDetailsPlugin.on_app_init() showing how to add a dependency and a route handler in a custom InitPluginProtocol implementation.

```python
from litestar import Litestar, get
from litestar.di import Provide
from litestar.plugins import InitPluginProtocol


def get_name() -> str:
    return "world"


@get("/my-path")
def my_route_handler(name: str) -> dict[str, str]:
    return {"hello": name}


class MyPlugin(InitPluginProtocol):
    def on_app_init(self, app_config: AppConfig) -> AppConfig:
        app_config.dependencies["name"] = Provide(get_name)
        app_config.route_handlers.append(my_route_handler)
        return app_config


app = Litestar(plugins=[MyPlugin()])

```

--------------------------------

### GET /health-check (MediaType.TEXT)

Source: https://docs.litestar.dev/2/usage/responses.html

Example of a GET route handler that returns a plain text response using the MediaType.TEXT enum.

```APIDOC
## [GET] /health-check

### Description
Returns a plain text response. The `media_type` is set to `MediaType.TEXT`, and the route handler returns a string.

### Method
GET

### Endpoint
/health-check

### Parameters
#### Query Parameters
- None

### Request Example
No request body.

### Response
#### Success Response (200)
- **body** (string) - The plain text response.

#### Response Example
"healthy"
```

--------------------------------

### Custom JWT payload class with Python 3.8+

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Example for Python 3.8+ showing how to extend the default `Token` class with a custom payload class. It defines a `CustomToken` dataclass, a `retrieve_user_handler`, and configures `JWTAuth` with `token_cls=CustomToken`. The handler returns a dictionary with `id` and `token_flag`.

```python
import dataclasses
import secrets
from typing import Any, Dict

from litestar import Request, get
from litestar.connection import ASGIConnection
from litestar.security.jwt import JWTAuth, Token

@dataclasses.dataclass
class CustomToken(Token):
    token_flag: bool = False

@dataclasses.dataclass
class User:
    id: str

async def retrieve_user_handler(token: CustomToken, connection: ASGIConnection) -> User:
    return User(id=token.sub)

TOKEN_SECRET = secrets.token_hex()

jwt_auth = JWTAuth[User](
    token_secret=TOKEN_SECRET,
    retrieve_user_handler=retrieve_user_handler,
    token_cls=CustomToken,
)

@get("/")
def handler(request: Request[User, CustomToken, Any]) -> Dict[str, Any]:
    return {"id": request.user.id, "token_flag": request.auth.token_flag}

```

--------------------------------

### Custom JWT payload class with Python 3.9+

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Example for Python 3.9+ showing how to extend the default `Token` class with a custom payload class. It defines a `CustomToken` dataclass, a `retrieve_user_handler`, and configures `JWTAuth` with `token_cls=CustomToken`. The handler returns a dictionary with `id` and `token_flag`.

```python
import dataclasses
import secrets
from typing import Any

from litestar import Request, get
from litestar.connection import ASGIConnection
from litestar.security.jwt import JWTAuth, Token

@dataclasses.dataclass
class CustomToken(Token):
    token_flag: bool = False

@dataclasses.dataclass
class User:
    id: str

async def retrieve_user_handler(token: CustomToken, connection: ASGIConnection) -> User:
    return User(id=token.sub)

TOKEN_SECRET = secrets.token_hex()

jwt_auth = JWTAuth[User](
    token_secret=TOKEN_SECRET,
    retrieve_user_handler=retrieve_user_handler,
    token_cls=CustomToken,
)

@get("/")
def handler(request: Request[User, CustomToken, Any]) -> dict[str, Any]:
    return {"id": request.user.id, "token_flag": request.auth.token_flag}

```

--------------------------------

### MsgspecDTO with msgspec.Meta constraint

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Example showing a request with an Annotated field using msgspec.Meta(min_length=3) and a POST endpoint with MsgspecDTO. Before the fix, the min_length constraint was ignored; now it is transferred. Note that with DTOConfig(partial=True) length constraints cannot be transferred, and PiccoloDTO drops length constraints for non-required fields with a warning.

```python
from typing import Annotated

import msgspec
from litestar import post
from litestar.dto import MsgspecDTO

class Request(msgspec.Struct):
    foo: Annotated[str, msgspec.Meta(min_length=3)]

@post("/example/", dto=MsgspecDTO[Request])
async def example(data: Request) -> Request:
    return data
```

--------------------------------

### GET /resources (MediaType.TEXT)

Source: https://docs.litestar.dev/2/usage/responses.html

Example of a GET route handler that returns a plain text response using the MediaType.TEXT enum.

```APIDOC
## [GET] /resources

### Description
Returns a plain text response. The `media_type` kwarg is set to `MediaType.TEXT`, which causes Litestar to serialize the response as a simple bytes string with a `Content-Type` header value of `text/plain`.

### Method
GET

### Endpoint
/resources

### Parameters
#### Query Parameters
- None

### Request Example
No request body.

### Response
#### Success Response (200)
- **body** (string) - The plain text response.

#### Response Example
"The rumbling rabbit ran around the rock"
```

--------------------------------

### ValkeyStore.__init__()

Source: https://docs.litestar.dev/2/reference/stores/valkey.html

Constructor for ValkeyStore.

```APIDOC
## ValkeyStore.__init__()

### Description
Initializes a `ValkeyStore` instance with a Valkey client, optional namespace, and client shutdown handling.

### Method
Constructor

### Parameters
- **valkey** (Valkey) - Required - An `valkey.asyncio.Valkey` instance
- **namespace** (str | None | Literal[_EmptyEnum.EMPTY]) - Optional - A key prefix to simulate a namespace in valkey. Defaults to `LITESTAR`. Passing `None` disables namespacing and makes `delete_all()` unavailable.
- **handle_client_shutdown** (bool) - Optional - If `True`, handle the shutdown of the valkey instance automatically during the store's lifespan. Defaults to `False`.

### Returns
None
```

--------------------------------

### Set up plugin and app (Async)

Source: https://docs.litestar.dev/2/usage/databases/sqlalchemy/plugins/sqlalchemy_plugin.html

Sets up the SQLAlchemy plugin and the Litestar app. Uses SQLAlchemyAsyncConfig with a SQLite connection string, create_all=True, and metadata. The app is configured with the add_item route handler and the plugin.

```python
from litestar import Litestar
config = SQLAlchemyAsyncConfig(
    connection_string="sqlite+aiosqlite:///todo_async.sqlite", create_all=True, metadata=Base.metadata
)
plugin = SQLAlchemyPlugin(config=config)
app = Litestar(route_handlers=[add_item], plugins=[plugin])

```

--------------------------------

### Install the standard extra for Litestar CLI

Source: https://docs.litestar.dev/2/usage/cli.html

Install the `standard` extra to get uvicorn and jsbeautifier, enabling `litestar run` and TypeScript beautification.

```bash
pip install 'litestar[standard]'

```

--------------------------------

### Pydantic 1 model with extra='ignore' config

Source: https://docs.litestar.dev/2/release-notes/changelog.html

Example of a Pydantic 1 model using a `Config` inner class with `extra = "ignore"`. This configuration is used to demonstrate how `forbid_unknown_fields` is set to `True` by default for Pydantic models with `extra='forbid'`.

```python
class User(BaseModel):
    class Config:
        extra = "ignore"
    name: str

```
Tokens:
Raw