handlers¶

class litestar.handlers.ASGIRouteHandler¶

Bases: BaseRouteHandler

Route handler for ASGI routes.

Parameters:

path¶ – A path fragment for the route handler function or a list of path fragments. If not given defaults to /.
fn¶ –
The handler function.

New in version 3.0.
exception_handlers¶ – A mapping of status codes and/or exception types to handler functions.
guards¶ – A sequence of Guard callables.
name¶ – A string identifying the route handler.
opt¶ – A string key mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
is_mount¶ – A boolean dictating whether the handler’s paths should be regarded as mount paths. Mount path accept any arbitrary paths that begin with the defined prefixed path. For example, a mount with the path /some-path/ will accept requests for /some-path/ and any sub path under this, e.g. /some-path/sub-path/ etc.
signature_namespace¶ – A mapping of names to types for use in forward reference resolution during signature modelling.
type_encoders¶ – A mapping of types to callables that transform them into types supported for serialization.
copy_scope¶ – Copy the ASGI ‘scope’ before calling the mounted application. Should be set to ‘True’ unless side effects via scope mutations by the mounted ASGI application are intentional
parameters¶ – A mapping of Parameter definitions
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

on_registration(route: BaseRoute, app: Litestar) → None¶

Called once per handler when the app object is instantiated.

Parameters:

route¶ – The route this handler is being registered on
app¶ – The application instance

Returns:

None

async handle(connection: ASGIConnection[ASGIRouteHandler, Any, Any, Any]) → None¶

ASGI app that authorizes the connection and then awaits the handler function.

Parameters:: connection¶ – The ASGI connection
Returns:: None

class litestar.handlers.BaseRouteHandler¶

Bases: object

Base route handler.

Serves as a subclass for all route handlers

Initialize HTTPRouteHandler.

Parameters:

path¶ – A path fragment for the route handler function or a sequence of path fragments. If not given defaults to /
fn¶ –
The handler function

New in version 3.0.
dependencies¶ – A string keyed mapping of dependency Provider instances.
dto¶ – AbstractDTO to use for (de)serializing and validation of request data.
exception_handlers¶ – A mapping of status codes and/or exception types to handler functions.
guards¶ – A sequence of Guard callables.
middleware¶ – A sequence of Middleware.
name¶ – A string identifying the route handler.
opt¶ – A string keyed mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
return_dto¶ – AbstractDTO to use for serializing outbound response data.
signature_namespace¶ – A mapping of names to types for use in forward reference resolution during signature modelling.
signature_types¶ – A sequence of types for use in forward reference resolution during signature modelling. These types will be added to the signature namespace using their __name__ attribute.
type_decoders¶ – A sequence of tuples, each composed of a predicate testing for type identity and a msgspec hook for deserialization.
type_encoders¶ – A mapping of types to callables that transform them into types supported for serialization.
parameters¶ – A mapping of Parameter definitions
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

property handler_id: str¶: A unique identifier used for generation of DTOs.

property default_deserializer: Callable[[Any, Any], Any]¶

Get a default deserializer for the route handler.

Returns:: A default deserializer for the route handler.

property default_serializer: Callable[[Any], Any]¶

Get a default serializer for the route handler.

Returns:: A default serializer for the route handler.

property signature_model: type[litestar._signature.model.SignatureModel]¶

Get the signature model for the route handler.

Returns:: A signature model for the route handler.

property parsed_fn_signature: ParsedSignature¶

Return the parsed signature of the handler function.

This method is memoized so the computation occurs only once.

Returns:: A ParsedSignature instance

property handler_name: str¶

Get the name of the handler function.

Raises:: ImproperlyConfiguredException – if handler fn is not set.
Returns:: Name of the handler function

resolve_type_encoders() → TypeEncodersMap¶

Return a merged type_encoders mapping.

Returns:: A dict of type encoders

resolve_type_decoders() → TypeDecodersSequence¶

Return a merged type_encoders mapping.

Returns:: A dict of type encoders

property parameter_field_definitions: dict[str, litestar.typing.FieldDefinition]¶: Return all parameters declared above the handler.

resolve_guards() → tuple[Guard, ...]¶: Return all guards in the handlers scope, starting from highest to current layer.

resolve_dependencies() → dict[str, litestar.di.Provide]¶: Return all dependencies correlating to handler function’s kwargs that exist in the handler’s scope.

resolve_middleware() → tuple[Middleware, ...]¶: Return registered middlewares

resolve_exception_handlers() → ExceptionHandlersMap¶

Resolve the exception_handlers by starting from the route handler and moving up.

This method is memoized so the computation occurs only once.

resolve_signature_namespace() → dict[str, Any]¶: Build the route handler signature namespace dictionary by going from top to bottom

async authorize_connection(connection: ASGIConnection) → None¶: Ensure the connection is authorized by running all the route guards in scope.

on_registration(route: BaseRoute, app: Litestar) → None¶

Called once per handler when the app object is instantiated.

Parameters:

route¶ – The route this handler is being registered on
app¶ – The application instance

Returns:

None

__str__() → str¶

Return a unique identifier for the route handler.

Returns:: A string

class litestar.handlers.HTTPRouteHandler¶

Bases: BaseRouteHandler

Route handler for HTTP routes.

Parameters:

path¶ – A path fragment for the route handler function or a sequence of path fragments. If not given defaults to /
fn¶ – The handler function
after_request¶ – A sync or async function executed before a Request is passed to any route handler. If this function returns a value, the request will not reach the route handler, and instead this value will be used.
after_response¶ – A sync or async function called after the response has been awaited. It receives the Request object and should not return any values.
background¶ – A BackgroundTask instance or BackgroundTasks to execute after the response is finished. Defaults to None.
before_request¶ – A sync or async function called immediately before calling the route handler. Receives the Request instance and any non-None return value is used for the response, bypassing the route handler.
cache¶ – Enables response caching if configured on the application level. Valid values are True or a number of seconds (e.g. 120) to cache the response.
cache_control¶ – A cache-control header of type CacheControlHeader that will be added to the response.
cache_key_builder¶ – A cache-key builder function. Allows for customization of the cache key if caching is configured on the application level.
dependencies¶ – A string keyed mapping of dependency Provider instances.
dto¶ – AbstractDTO to use for (de)serializing and validation of request data.
etag¶ – An etag header of type ETag that will be added to the response.
exception_handlers¶ – A mapping of status codes and/or exception types to handler functions.
guards¶ – A sequence of Guard callables.
http_method¶ – An http method string, a member of the enum HttpMethod or a list of these that correlates to the methods the route handler function should handle.
media_type¶ – A member of the MediaType enum or a string with a valid IANA Media-Type.
middleware¶ – A sequence of Middleware.
name¶ – A string identifying the route handler.
opt¶ – A string keyed mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
request_class¶ – A custom subclass of Request to be used as route handler’s default request.
request_max_body_size¶ – Maximum allowed size of the request body in bytes. If this size is exceeded, a ‘413 - Request Entity Too Large’ error response is returned.
response_class¶ – A custom subclass of Response to be used as route handler’s default response.
response_cookies¶ – A sequence of Cookie instances.
response_headers¶ – A string keyed mapping of ResponseHeader instances.
responses¶ – A mapping of additional status codes and a description of their expected content. This information will be included in the OpenAPI schema
return_dto¶ – AbstractDTO to use for serializing outbound response data.
signature_namespace¶ – A mapping of names to types for use in forward reference resolution during signature modelling.
status_code¶ – An http status code for the response. Defaults to 200 for GET, PUT and PATCH, 201 for POST and 204 for DELETE. For mixed method requests it will check for POST and DELETE first then defaults to 200.
sync_to_thread¶ – A boolean dictating whether the handler function will be executed in a worker thread or the main event loop. This has an effect only for sync handler functions. See using sync handler functions.
content_encoding¶ – A string describing the encoding of the content, e.g. "base64".
content_media_type¶ – A string designating the media-type of the content, e.g. "image/png".
deprecated¶ – A boolean dictating whether this route should be marked as deprecated in the OpenAPI schema.
description¶ – Text used for the route’s schema description section.
include_in_schema¶ – A boolean flag dictating whether the route handler should be documented in the OpenAPI schema.
operation_class¶ – Operation to be used with the route’s OpenAPI schema.
operation_id¶ – Either a string or a callable returning a string. An identifier used for the route’s schema operationId.
raises¶ – A list of exception classes extending from litestar.HttpException that is used for the OpenAPI documentation. This list should describe all exceptions raised within the route handler’s function/method. The Litestar ValidationException will be added automatically for the schema if any validation is involved.
response_description¶ – Text used for the route’s response schema description section.
security¶ – A sequence of dictionaries that contain information about which security scheme can be used on the endpoint.
summary¶ – Text used for the route’s schema summary section.
tags¶ – A sequence of string tags that will be appended to the OpenAPI schema.
type_decoders¶ – A sequence of tuples, each composed of a predicate testing for type identity and a msgspec hook for deserialization.
type_encoders¶ – A mapping of types to callables that transform them into types supported for serialization.
parameters¶ – A mapping of Parameter definitions
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

resolve_request_class() → type[litestar.connection.request.Request]¶

Return the closest custom Request class in the owner graph or the default Request class.

This method is memoized so the computation occurs only once.

Returns:: The default Request class for the route handler.

resolve_response_class() → type[litestar.response.base.Response]¶

Return the closest custom Response class in the owner graph or the default Response class.

This method is memoized so the computation occurs only once.

Returns:: The default Response class for the route handler.

resolve_before_request() → AsyncAnyCallable | None¶

Resolve the before_handler handler by starting from the route handler and moving up.

If a handler is found it is returned, otherwise None is set. This method is memoized so the computation occurs only once.

Returns:: An optional before request lifecycle hook handler

resolve_after_response() → AsyncAnyCallable | None¶

Resolve the after_response handler by starting from the route handler and moving up.

If a handler is found it is returned, otherwise None is set. This method is memoized so the computation occurs only once.

Returns:: An optional after response lifecycle hook handler

resolve_include_in_schema() → bool¶

Resolve the ‘include_in_schema’ property by starting from the route handler and moving up.

If ‘include_in_schema’ is found in any of the ownership layers, the last value found is returned. If not found in any layer, the default value True is returned.

Returns:: The resolved ‘include_in_schema’ property.
Return type:: bool

resolve_security() → tuple[SecurityRequirement, ...]¶

Resolve the security property by starting from the route handler and moving up.

Security requirements are additive, so the security requirements of the route handler are the sum of all security requirements of the ownership layers.

Returns:: The resolved security property.
Return type:: list[SecurityRequirement]

resolve_tags() → frozenset[str]¶

Resolve the tags property by starting from the route handler and moving up.

Tags are additive, so the tags of the route handler are the sum of all tags of the ownership layers.

on_registration(route: BaseRoute, app: Litestar) → None¶

Called once per handler when the app object is instantiated.

Parameters:

route¶ – The route this handler is being registered on
app¶ – The application instance

Returns:

None

async handle(connection: Request[Any, Any, Any]) → None¶

ASGI app that creates a Request from the passed in args, determines which handler function to call and then: handles the call.

Parameters:: connection¶ – The request
Returns:: None

async to_response(data: Any, request: Request) → ASGIApp¶

Return a Response from the handler by resolving and calling it.

Parameters:

data¶ – Either an instance of a Response, a Response instance or an arbitrary value.
request¶ – A Request instance

Returns:

A Response instance

class litestar.handlers.WebsocketListener¶

Bases: ABC

path: str | list[str] | None = None¶: A path fragment for the route handler function or a sequence of path fragments. If not given defaults to /

dependencies: Dependencies | None = None¶: A string keyed mapping of dependency Provider instances.

dto: type[AbstractDTO] | None | EmptyType = 0¶: AbstractDTO to use for (de)serializing and validation of request data

exception_handlers: dict[int | type[Exception], ExceptionHandler] | None = None¶: A mapping of status codes and/or exception types to handler functions.

guards: list[Guard] | None = None¶: A sequence of Guard callables.

middleware: list[Middleware] | None = None¶: A sequence of Middleware.

receive_mode: WebSocketMode = 'text'¶: WebSocket mode to receive data in, either text or binary.

send_mode: WebSocketMode = 'text'¶: Websocket mode to send data in, either text or binary.

name: str | None = None¶: A string identifying the route handler.

opt: dict[str, Any] | None = None¶: A string keyed mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.

return_dto: type[AbstractDTO] | None | EmptyType = 0¶: AbstractDTO to use for serializing outbound response data.

signature_namespace: Mapping[str, Any] | None = None¶: A mapping of names to types for use in forward reference resolution during signature modelling.

type_decoders: TypeDecodersSequence | None = None¶

A sequence of tuples, each composed of a predicate testing for type identity and a msgspec hook for deserialization.

Type:: type_decoders

type_encoders: TypeEncodersMap | None = None¶

A mapping of types to callables that transform them into types supported for serialization.

Type:: type_encoders

websocket_class: type[WebSocket] | None = None¶

A custom subclass of WebSocket to be used as route handler’s default websocket class.

Type:: websocket_class

on_accept(*args: Any, **kwargs: Any) → Any¶: Called after a WebSocket connection has been accepted. Can receive any dependencies

on_disconnect(*args: Any, **kwargs: Any) → Any¶: Called after a WebSocket connection has been disconnected. Can receive any dependencies

abstract on_receive(*args: Any, **kwargs: Any) → Any¶

Called after data has been received from the WebSocket.

This should take a data argument, receiving the processed WebSocket data, and can additionally include handler dependencies such as state, or other regular dependencies.

Data returned from this function will be serialized and sent via the socket according to handler configuration.

class litestar.handlers.WebsocketListenerRouteHandler¶

Bases: WebsocketRouteHandler

A websocket listener that automatically accepts a connection, handles disconnects, invokes a callback function every time new data is received and sends any data returned

__init__(path: str | list[str] | None = None, *, fn: AnyCallable, connection_lifespan: Callable[..., AbstractAsyncContextManager[Any]] | None = None, dependencies: Dependencies | None = None, dto: type[AbstractDTO] | None | EmptyType = Empty, exception_handlers: dict[int | type[Exception], ExceptionHandler] | None = None, guards: Sequence[Guard] | None = None, middleware: Sequence[Middleware] | None = None, receive_mode: WebSocketMode = 'text', send_mode: WebSocketMode = 'text', name: str | None = None, opt: dict[str, Any] | None = None, return_dto: type[AbstractDTO] | None | EmptyType = Empty, signature_namespace: Mapping[str, Any] | None = None, type_decoders: TypeDecodersSequence | None = None, type_encoders: TypeEncodersMap | None = None, websocket_class: type[WebSocket] | None = None, parameters: ParametersMap | None = None, **kwargs: Any) → None¶

__init__(path: str | list[str] | None = None, *, fn: AnyCallable, connection_accept_handler: Callable[[WebSocket], Coroutine[Any, Any, None]] = WebSocket.accept, dependencies: Dependencies | None = None, dto: type[AbstractDTO] | None | EmptyType = Empty, exception_handlers: dict[int | type[Exception], ExceptionHandler] | None = None, guards: Sequence[Guard] | None = None, middleware: Sequence[Middleware] | None = None, receive_mode: WebSocketMode = 'text', send_mode: WebSocketMode = 'text', name: str | None = None, on_accept: AnyCallable | None = None, on_disconnect: AnyCallable | None = None, opt: dict[str, Any] | None = None, return_dto: type[AbstractDTO] | None | EmptyType = Empty, signature_namespace: Mapping[str, Any] | None = None, type_decoders: TypeDecodersSequence | None = None, type_encoders: TypeEncodersMap | None = None, websocket_class: type[WebSocket] | None = None, parameters: ParametersMap | None = None, **kwargs: Any) → None

Initialize WebsocketRouteHandler

Parameters:

path¶ – A path fragment for the route handler function or a sequence of path fragments. If not given defaults to /
fn¶ – The handler function
connection_accept_handler¶ – A callable that accepts a WebSocket instance and returns a coroutine that when awaited, will accept the connection. Defaults to WebSocket.accept.
connection_lifespan¶ – An asynchronous context manager, handling the lifespan of the connection. By default, it calls the connection_accept_handler, on_connect and on_disconnect. Can request any dependencies, for example the WebSocket connection
dependencies¶ – A string keyed mapping of dependency Provider instances.
dto¶ – AbstractDTO to use for (de)serializing and validation of request data.
exception_handlers¶ – A mapping of status codes and/or exception types to handler functions.
guards¶ – A sequence of Guard callables.
middleware¶ – A sequence of Middleware.
receive_mode¶ – Websocket mode to receive data in, either text or binary.
send_mode¶ – Websocket mode to receive data in, either text or binary.
name¶ – A string identifying the route handler.
on_accept¶ – Callback invoked after a connection has been accepted. Can request any dependencies, for example the WebSocket connection
on_disconnect¶ – Callback invoked after a connection has been closed. Can request any dependencies, for example the WebSocket connection
opt¶ – A string keyed mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
return_dto¶ – AbstractDTO to use for serializing outbound response data.
signature_namespace¶ – A mapping of names to types for use in forward reference resolution during signature modelling.
type_decoders¶ – A sequence of tuples, each composed of a predicate testing for type identity and a msgspec hook for deserialization.
type_encoders¶ – A mapping of types to callables that transform them into types supported for serialization.
websocket_class¶ – A custom subclass of WebSocket to be used as route handler’s default websocket class.
parameters¶ – A mapping of Parameter definitions
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

connection_accept_handler¶: Callback to accept a WebSocket connection. By default, calls WebSocket.accept

on_accept¶: Callback invoked after a WebSocket connection has been accepted

on_disconnect¶: Callback invoked after a WebSocket connection has been closed

on_registration(route: BaseRoute, app: Litestar) → None¶

Called once per handler when the app object is instantiated.

Parameters:

route¶ – The route this handler is being registered on
app¶ – The application instance

Returns:

None

default_connection_lifespan(socket: WebSocket, on_accept_dependencies: dict[str, Any] | None = None, on_disconnect_dependencies: dict[str, Any] | None = None) → AsyncGenerator[None, None]¶

Handle the connection lifespan of a WebSocket.

Parameters:

socket¶ – The WebSocket connection
on_accept_dependencies¶ – Dependencies requested by the on_accept hook
on_disconnect_dependencies¶ – Dependencies requested by the on_disconnect hook

By, default this will

Call connection_accept_handler to accept a connection

Call on_accept if defined after a connection has been accepted

Call on_disconnect upon leaving the context

class litestar.handlers.WebsocketRouteHandler¶

Bases: BaseRouteHandler

Route handler for WebSocket routes.

Parameters:

path¶ – A path fragment for the route handler function or a sequence of path fragments. If not given defaults to /
fn¶ –
The handler function

New in version 3.0.
dependencies¶ – A string keyed mapping of dependency Provider instances.
exception_handlers¶ – A mapping of status codes and/or exception types to handler functions.
guards¶ – A sequence of Guard callables.
middleware¶ – A sequence of Middleware.
name¶ – A string identifying the route handler.
opt¶ – A string keyed mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
signature_namespace¶ – A mapping of names to types for use in forward reference resolution during signature modelling.
type_encoders¶ – A mapping of types to callables that transform them into types supported for serialization.
websocket_class¶ – A custom subclass of WebSocket to be used as route handler’s default websocket class.
parameters¶ – A mapping of Parameter definitions
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

resolve_websocket_class() → type[litestar.connection.websocket.WebSocket]¶

Return the closest custom WebSocket class in the owner graph or the default Websocket class.

This method is memoized so the computation occurs only once.

Returns:: The default WebSocket class for the route handler.

on_registration(route: BaseRoute, app: Litestar) → None¶

Called once per handler when the app object is instantiated.

Parameters:

route¶ – The route this handler is being registered on
app¶ – The application instance

Returns:

None

async handle(connection: WebSocket[Any, Any, Any]) → None¶

ASGI app that creates a WebSocket from the passed in args, and then awaits the handler function.

Parameters:: connection¶ – WebSocket connection
Returns:: None

litestar.handlers.asgi(path: str | Sequence[str] | None = None, *, exception_handlers: ExceptionHandlersMap | None = None, guards: Sequence[Guard] | None = None, name: str | None = None, opt: Mapping[str, Any] | None = None, is_mount: bool = False, signature_namespace: Mapping[str, Any] | None = None, handler_class: type[ASGIRouteHandler] = <class 'litestar.handlers.asgi_handlers.ASGIRouteHandler'>, **kwargs: Any) → Callable[[AsyncAnyCallable], ASGIRouteHandler]¶

Create an ASGIRouteHandler.

Parameters:

path¶ – A path fragment for the route handler function or a sequence of path fragments. If not given defaults to /
exception_handlers¶ – A mapping of status codes and/or exception types to handler functions.
guards¶ – A sequence of Guard callables.
name¶ – A string identifying the route handler.
opt¶ – A string keyed mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
signature_namespace¶ – A mapping of names to types for use in forward reference resolution during signature modelling.
is_mount¶ – A boolean dictating whether the handler’s paths should be regarded as mount paths. Mount path accept any arbitrary paths that begin with the defined prefixed path. For example, a mount with the path /some-path/ will accept requests for /some-path/ and any sub path under this, e.g. /some-path/sub-path/ etc.
handler_class¶ – Route handler class instantiated by the decorator
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

litestar.handlers.delete(path: str | None | Sequence[str] = None, *, after_request: AfterRequestHookHandler | None = None, after_response: AfterResponseHookHandler | None = None, background: BackgroundTask | BackgroundTasks | None = None, before_request: BeforeRequestHookHandler | None = None, cache: bool | int | type[CACHE_FOREVER] = False, cache_control: CacheControlHeader | None = None, cache_key_builder: CacheKeyBuilder | None = None, dependencies: Dependencies | None = None, dto: type[AbstractDTO] | None | EmptyType = _EmptyEnum.EMPTY, etag: ETag | None = None, exception_handlers: ExceptionHandlersMap | None = None, guards: Sequence[Guard] | None = None, media_type: MediaType | str | None = None, middleware: Sequence[Middleware] | None = None, name: str | None = None, opt: Mapping[str, Any] | None = None, request_class: type[Request] | None = None, response_class: type[Response] | None = None, response_cookies: ResponseCookies | None = None, response_headers: ResponseHeaders | None = None, return_dto: type[AbstractDTO] | None | EmptyType = _EmptyEnum.EMPTY, signature_namespace: Mapping[str, Any] | None = None, status_code: int | None = None, sync_to_thread: bool | None = None, content_encoding: str | None = None, content_media_type: str | None = None, deprecated: bool = False, description: str | None = None, include_in_schema: bool | EmptyType = _EmptyEnum.EMPTY, operation_class: type[Operation] = <class 'litestar.openapi.spec.operation.Operation'>, operation_id: str | OperationIDCreator | None = None, raises: Sequence[type[HTTPException]] | None = None, response_description: str | None = None, responses: Mapping[int, ResponseSpec] | None = None, security: Sequence[SecurityRequirement] | None = None, summary: str | None = None, tags: Sequence[str] | None = None, type_decoders: TypeDecodersSequence | None = None, type_encoders: TypeEncodersMap | None = None, handler_class: type[HTTPRouteHandler] = <class 'litestar.handlers.http_handlers.base.HTTPRouteHandler'>, **kwargs: Any) → Callable[[AnyCallable], HTTPRouteHandler]¶

Create an HTTPRouteHandler with a DELETE method.

Parameters:

path¶ – A path fragment for the route handler function or a sequence of path fragments. If not given defaults to /
after_request¶ – A sync or async function executed before a Request is passed to any route handler. If this function returns a value, the request will not reach the route handler, and instead this value will be used.
after_response¶ – A sync or async function called after the response has been awaited. It receives the Request object and should not return any values.
background¶ – A BackgroundTask instance or BackgroundTasks to execute after the response is finished. Defaults to None.
before_request¶ – A sync or async function called immediately before calling the route handler. Receives the connection.Request instance and any non-None return value is used for the response, bypassing the route handler.
cache¶ – Enables response caching if configured on the application level. Valid values are True or a number of seconds (e.g. 120) to cache the response.
cache_control¶ – A cache-control header of type CacheControlHeader that will be added to the response.
cache_key_builder¶ – A cache-key builder function. Allows for customization of the cache key if caching is configured on the application level.
dto¶ – AbstractDTO to use for (de)serializing and validation of request data.
dependencies¶ – A string keyed mapping of dependency Provider instances.
etag¶ – An etag header of type ETag that will be added to the response.
exception_handlers¶ – A mapping of status codes and/or exception types to handler functions.
guards¶ – A sequence of Guard callables.
media_type¶ – A member of the MediaType enum or a string with a valid IANA Media-Type.
middleware¶ – A sequence of Middleware.
name¶ – A string identifying the route handler.
opt¶ – A string keyed mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
request_class¶ – A custom subclass of Request to be used as route handler’s default request.
response_class¶ – A custom subclass of Response to be used as route handler’s default response.
response_cookies¶ – A sequence of Cookie instances.
response_headers¶ – A string keyed mapping of ResponseHeader instances.
responses¶ – A mapping of additional status codes and a description of their expected content. This information will be included in the OpenAPI schema
return_dto¶ – AbstractDTO to use for serializing outbound response data.
signature_namespace¶ – A mapping of names to types for use in forward reference resolution during signature modelling.
status_code¶ – An http status code for the response. Defaults to 200 for mixed method or GET, PUT and PATCH, 201 for POST and 204 for DELETE.
sync_to_thread¶ – A boolean dictating whether the handler function will be executed in a worker thread or the main event loop. This has an effect only for sync handler functions. See using sync handler functions.
content_encoding¶ – A string describing the encoding of the content, e.g. base64.
content_media_type¶ – A string designating the media-type of the content, e.g. image/png.
deprecated¶ – A boolean dictating whether this route should be marked as deprecated in the OpenAPI schema.
description¶ – Text used for the route’s schema description section.
include_in_schema¶ – A boolean flag dictating whether the route handler should be documented in the OpenAPI schema.
operation_class¶ – Operation to be used with the route’s OpenAPI schema.
operation_id¶ – Either a string or a callable returning a string. An identifier used for the route’s schema operationId.
raises¶ – A list of exception classes extending from litestar.HttpException that is used for the OpenAPI documentation. This list should describe all exceptions raised within the route handler’s function/method. The Litestar ValidationException will be added automatically for the schema if any validation is involved.
response_description¶ – Text used for the route’s response schema description section.
security¶ – A sequence of dictionaries that contain information about which security scheme can be used on the endpoint.
summary¶ – Text used for the route’s schema summary section.
tags¶ – A sequence of string tags that will be appended to the OpenAPI schema.
type_decoders¶ – A sequence of tuples, each composed of a predicate testing for type identity and a msgspec hook for deserialization.
type_encoders¶ – A mapping of types to callables that transform them into types supported for serialization.
handler_class¶ – Route handler class instantiated by the decorator
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

litestar.handlers.get(path: str | None | Sequence[str] = None, *, after_request: AfterRequestHookHandler | None = None, after_response: AfterResponseHookHandler | None = None, background: BackgroundTask | BackgroundTasks | None = None, before_request: BeforeRequestHookHandler | None = None, cache: bool | int | type[CACHE_FOREVER] = False, cache_control: CacheControlHeader | None = None, cache_key_builder: CacheKeyBuilder | None = None, dependencies: Dependencies | None = None, dto: type[AbstractDTO] | None | EmptyType = _EmptyEnum.EMPTY, etag: ETag | None = None, exception_handlers: ExceptionHandlersMap | None = None, guards: Sequence[Guard] | None = None, media_type: MediaType | str | None = None, middleware: Sequence[Middleware] | None = None, name: str | None = None, opt: Mapping[str, Any] | None = None, request_class: type[Request] | None = None, response_class: type[Response] | None = None, response_cookies: ResponseCookies | None = None, response_headers: ResponseHeaders | None = None, return_dto: type[AbstractDTO] | None | EmptyType = _EmptyEnum.EMPTY, signature_namespace: Mapping[str, Any] | None = None, status_code: int | None = None, sync_to_thread: bool | None = None, content_encoding: str | None = None, content_media_type: str | None = None, deprecated: bool = False, description: str | None = None, include_in_schema: bool | EmptyType = _EmptyEnum.EMPTY, operation_class: type[Operation] = <class 'litestar.openapi.spec.operation.Operation'>, operation_id: str | OperationIDCreator | None = None, raises: Sequence[type[HTTPException]] | None = None, response_description: str | None = None, responses: Mapping[int, ResponseSpec] | None = None, security: Sequence[SecurityRequirement] | None = None, summary: str | None = None, tags: Sequence[str] | None = None, type_decoders: TypeDecodersSequence | None = None, type_encoders: TypeEncodersMap | None = None, handler_class: type[HTTPRouteHandler] = <class 'litestar.handlers.http_handlers.base.HTTPRouteHandler'>, **kwargs: Any) → Callable[[AnyCallable], HTTPRouteHandler]¶

Create an HTTPRouteHandler with a GET method.

Parameters:

path¶ – A path fragment for the route handler function or a sequence of path fragments. If not given defaults to /
after_request¶ – A sync or async function executed before a Request is passed to any route handler. If this function returns a value, the request will not reach the route handler, and instead this value will be used.
after_response¶ – A sync or async function called after the response has been awaited. It receives the Request object and should not return any values.
background¶ – A BackgroundTask instance or BackgroundTasks to execute after the response is finished. Defaults to None.
before_request¶ – A sync or async function called immediately before calling the route handler. Receives the connection.Request instance and any non-None return value is used for the response, bypassing the route handler.
cache¶ – Enables response caching if configured on the application level. Valid values are True or a number of seconds (e.g. 120) to cache the response.
cache_control¶ – A cache-control header of type CacheControlHeader that will be added to the response.
cache_key_builder¶ – A cache-key builder function. Allows for customization of the cache key if caching is configured on the application level.
dependencies¶ – A string keyed mapping of dependency Provider instances.
dto¶ – AbstractDTO to use for (de)serializing and validation of request data.
etag¶ – An etag header of type ETag that will be added to the response.
exception_handlers¶ – A mapping of status codes and/or exception types to handler functions.
guards¶ – A sequence of Guard callables.
media_type¶ – A member of the MediaType enum or a string with a valid IANA Media-Type.
middleware¶ – A sequence of Middleware.
name¶ – A string identifying the route handler.
opt¶ – A string keyed mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
request_class¶ – A custom subclass of Request to be used as route handler’s default request.
response_class¶ – A custom subclass of Response to be used as route handler’s default response.
response_cookies¶ – A sequence of Cookie instances.
response_headers¶ – A string keyed mapping of ResponseHeader instances.
responses¶ – A mapping of additional status codes and a description of their expected content. This information will be included in the OpenAPI schema
return_dto¶ – AbstractDTO to use for serializing outbound response data.
signature_namespace¶ – A mapping of names to types for use in forward reference resolution during signature modelling.
status_code¶ – An http status code for the response. Defaults to 200 for mixed method or GET, PUT and PATCH, 201 for POST and 204 for DELETE.
sync_to_thread¶ – A boolean dictating whether the handler function will be executed in a worker thread or the main event loop. This has an effect only for sync handler functions. See using sync handler functions.
content_encoding¶ – A string describing the encoding of the content, e.g. base64.
content_media_type¶ – A string designating the media-type of the content, e.g. image/png.
deprecated¶ – A boolean dictating whether this route should be marked as deprecated in the OpenAPI schema.
description¶ – Text used for the route’s schema description section.
include_in_schema¶ – A boolean flag dictating whether the route handler should be documented in the OpenAPI schema.
operation_class¶ – Operation to be used with the route’s OpenAPI schema.
operation_id¶ – Either a string or a callable returning a string. An identifier used for the route’s schema operationId.
raises¶ – A list of exception classes extending from litestar.HttpException that is used for the OpenAPI documentation. This list should describe all exceptions raised within the route handler’s function/method. The Litestar ValidationException will be added automatically for the schema if any validation is involved.
response_description¶ – Text used for the route’s response schema description section.
security¶ – A sequence of dictionaries that contain information about which security scheme can be used on the endpoint.
summary¶ – Text used for the route’s schema summary section.
tags¶ – A sequence of string tags that will be appended to the OpenAPI schema.
type_decoders¶ – A sequence of tuples, each composed of a predicate testing for type identity and a msgspec hook for deserialization.
type_encoders¶ – A mapping of types to callables that transform them into types supported for serialization.
handler_class¶ – Route handler class instantiated by the decorator
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

litestar.handlers.head(path: str | None | Sequence[str] = None, *, after_request: AfterRequestHookHandler | None = None, after_response: AfterResponseHookHandler | None = None, background: BackgroundTask | BackgroundTasks | None = None, before_request: BeforeRequestHookHandler | None = None, cache: bool | int | type[CACHE_FOREVER] = False, cache_control: CacheControlHeader | None = None, cache_key_builder: CacheKeyBuilder | None = None, dependencies: Dependencies | None = None, dto: type[AbstractDTO] | None | EmptyType = _EmptyEnum.EMPTY, etag: ETag | None = None, exception_handlers: ExceptionHandlersMap | None = None, guards: Sequence[Guard] | None = None, media_type: MediaType | str | None = None, middleware: Sequence[Middleware] | None = None, name: str | None = None, opt: Mapping[str, Any] | None = None, request_class: type[Request] | None = None, response_class: type[Response] | None = None, response_cookies: ResponseCookies | None = None, response_headers: ResponseHeaders | None = None, signature_namespace: Mapping[str, Any] | None = None, status_code: int | None = None, sync_to_thread: bool | None = None, content_encoding: str | None = None, content_media_type: str | None = None, deprecated: bool = False, description: str | None = None, include_in_schema: bool | EmptyType = _EmptyEnum.EMPTY, operation_class: type[Operation] = <class 'litestar.openapi.spec.operation.Operation'>, operation_id: str | OperationIDCreator | None = None, raises: Sequence[type[HTTPException]] | None = None, response_description: str | None = None, responses: Mapping[int, ResponseSpec] | None = None, return_dto: type[AbstractDTO] | None | EmptyType = _EmptyEnum.EMPTY, security: Sequence[SecurityRequirement] | None = None, summary: str | None = None, tags: Sequence[str] | None = None, type_decoders: TypeDecodersSequence | None = None, type_encoders: TypeEncodersMap | None = None, handler_class: type[HTTPRouteHandler] = <class 'litestar.handlers.http_handlers.base.HTTPRouteHandler'>, **kwargs: Any) → Callable[[AnyCallable], HTTPRouteHandler]¶

Create an HTTPRouteHandler with a HEAD method.

Notes

A response to a head request cannot include a body.
See: [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD).

Parameters:

path¶ – A path fragment for the route handler function or a sequence of path fragments. If not given defaults to /
after_request¶ – A sync or async function executed before a Request is passed to any route handler. If this function returns a value, the request will not reach the route handler, and instead this value will be used.
after_response¶ – A sync or async function called after the response has been awaited. It receives the Request object and should not return any values.
background¶ – A BackgroundTask instance or BackgroundTasks to execute after the response is finished. Defaults to None.
before_request¶ – A sync or async function called immediately before calling the route handler. Receives the connection.Request instance and any non-None return value is used for the response, bypassing the route handler.
cache¶ – Enables response caching if configured on the application level. Valid values are True or a number of seconds (e.g. 120) to cache the response.
cache_control¶ – A cache-control header of type CacheControlHeader that will be added to the response.
cache_key_builder¶ – A cache-key builder function. Allows for customization of the cache key if caching is configured on the application level.
dependencies¶ – A string keyed mapping of dependency Provider instances.
dto¶ – AbstractDTO to use for (de)serializing and validation of request data.
etag¶ – An etag header of type ETag that will be added to the response.
exception_handlers¶ – A mapping of status codes and/or exception types to handler functions.
guards¶ – A sequence of Guard callables.
media_type¶ – A member of the MediaType enum or a string with a valid IANA Media-Type.
middleware¶ – A sequence of Middleware.
name¶ – A string identifying the route handler.
opt¶ – A string keyed mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
request_class¶ – A custom subclass of Request to be used as route handler’s default request.
response_class¶ – A custom subclass of Response to be used as route handler’s default response.
response_cookies¶ – A sequence of Cookie instances.
response_headers¶ – A string keyed mapping of ResponseHeader instances.
responses¶ – A mapping of additional status codes and a description of their expected content. This information will be included in the OpenAPI schema
return_dto¶ – AbstractDTO to use for serializing outbound response data.
signature_namespace¶ – A mapping of names to types for use in forward reference resolution during signature modelling.
status_code¶ – An http status code for the response. Defaults to 200 for mixed method or GET, PUT and PATCH, 201 for POST and 204 for DELETE.
sync_to_thread¶ – A boolean dictating whether the handler function will be executed in a worker thread or the main event loop. This has an effect only for sync handler functions. See using sync handler functions.
content_encoding¶ – A string describing the encoding of the content, e.g. base64.
content_media_type¶ – A string designating the media-type of the content, e.g. image/png.
deprecated¶ – A boolean dictating whether this route should be marked as deprecated in the OpenAPI schema.
description¶ – Text used for the route’s schema description section.
include_in_schema¶ – A boolean flag dictating whether the route handler should be documented in the OpenAPI schema.
operation_class¶ – Operation to be used with the route’s OpenAPI schema.
operation_id¶ – Either a string or a callable returning a string. An identifier used for the route’s schema operationId.
raises¶ – A list of exception classes extending from litestar.HttpException that is used for the OpenAPI documentation. This list should describe all exceptions raised within the route handler’s function/method. The Litestar ValidationException will be added automatically for the schema if any validation is involved.
response_description¶ – Text used for the route’s response schema description section.
security¶ – A sequence of dictionaries that contain information about which security scheme can be used on the endpoint.
summary¶ – Text used for the route’s schema summary section.
tags¶ – A sequence of string tags that will be appended to the OpenAPI schema.
type_decoders¶ – A sequence of tuples, each composed of a predicate testing for type identity and a msgspec hook for deserialization.
type_encoders¶ – A mapping of types to callables that transform them into types supported for serialization.
handler_class¶ – Route handler class instantiated by the decorator
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

litestar.handlers.patch(path: str | None | Sequence[str] = None, *, after_request: AfterRequestHookHandler | None = None, after_response: AfterResponseHookHandler | None = None, background: BackgroundTask | BackgroundTasks | None = None, before_request: BeforeRequestHookHandler | None = None, cache: bool | int | type[CACHE_FOREVER] = False, cache_control: CacheControlHeader | None = None, cache_key_builder: CacheKeyBuilder | None = None, dependencies: Dependencies | None = None, dto: type[AbstractDTO] | None | EmptyType = _EmptyEnum.EMPTY, etag: ETag | None = None, exception_handlers: ExceptionHandlersMap | None = None, guards: Sequence[Guard] | None = None, media_type: MediaType | str | None = None, middleware: Sequence[Middleware] | None = None, name: str | None = None, opt: Mapping[str, Any] | None = None, request_class: type[Request] | None = None, request_max_body_size: int | None | EmptyType = _EmptyEnum.EMPTY, response_class: type[Response] | None = None, response_cookies: ResponseCookies | None = None, response_headers: ResponseHeaders | None = None, return_dto: type[AbstractDTO] | None | EmptyType = _EmptyEnum.EMPTY, signature_namespace: Mapping[str, Any] | None = None, status_code: int | None = None, sync_to_thread: bool | None = None, content_encoding: str | None = None, content_media_type: str | None = None, deprecated: bool = False, description: str | None = None, include_in_schema: bool | EmptyType = _EmptyEnum.EMPTY, operation_class: type[Operation] = <class 'litestar.openapi.spec.operation.Operation'>, operation_id: str | OperationIDCreator | None = None, raises: Sequence[type[HTTPException]] | None = None, response_description: str | None = None, responses: Mapping[int, ResponseSpec] | None = None, security: Sequence[SecurityRequirement] | None = None, summary: str | None = None, tags: Sequence[str] | None = None, type_decoders: TypeDecodersSequence | None = None, type_encoders: TypeEncodersMap | None = None, handler_class: type[HTTPRouteHandler] = <class 'litestar.handlers.http_handlers.base.HTTPRouteHandler'>, **kwargs: Any) → Callable[[AnyCallable], HTTPRouteHandler]¶

Create an HTTPRouteHandler with a PATCH method.

Parameters:

path¶ – A path fragment for the route handler function or a sequence of path fragments. If not given defaults to /
after_request¶ – A sync or async function executed before a Request is passed to any route handler. If this function returns a value, the request will not reach the route handler, and instead this value will be used.
after_response¶ – A sync or async function called after the response has been awaited. It receives the Request object and should not return any values.
background¶ – A BackgroundTask instance or BackgroundTasks to execute after the response is finished. Defaults to None.
before_request¶ – A sync or async function called immediately before calling the route handler. Receives the connection.Request instance and any non-None return value is used for the response, bypassing the route handler.
cache¶ – Enables response caching if configured on the application level. Valid values are True or a number of seconds (e.g. 120) to cache the response.
cache_control¶ – A cache-control header of type CacheControlHeader that will be added to the response.
cache_key_builder¶ – A cache-key builder function. Allows for customization of the cache key if caching is configured on the application level.
dependencies¶ – A string keyed mapping of dependency Provider instances.
dto¶ – AbstractDTO to use for (de)serializing and validation of request data.
etag¶ – An etag header of type ETag that will be added to the response.
exception_handlers¶ – A mapping of status codes and/or exception types to handler functions.
guards¶ – A sequence of Guard callables.
media_type¶ – A member of the MediaType enum or a string with a valid IANA Media-Type.
middleware¶ – A sequence of Middleware.
name¶ – A string identifying the route handler.
opt¶ – A string keyed mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
request_class¶ – A custom subclass of Request to be used as route handler’s default request.
request_max_body_size¶ – Maximum allowed size of the request body in bytes. If this size is exceeded, a ‘413 - Request Entity Too Large’ error response is returned.
response_class¶ – A custom subclass of Response to be used as route handler’s default response.
response_cookies¶ – A sequence of Cookie instances.
response_headers¶ – A string keyed mapping of ResponseHeader instances.
responses¶ – A mapping of additional status codes and a description of their expected content. This information will be included in the OpenAPI schema
return_dto¶ – AbstractDTO to use for serializing outbound response data.
signature_namespace¶ – A mapping of names to types for use in forward reference resolution during signature modelling.
status_code¶ – An http status code for the response. Defaults to 200 for mixed method or GET, PUT and PATCH, 201 for POST and 204 for DELETE.
sync_to_thread¶ – A boolean dictating whether the handler function will be executed in a worker thread or the main event loop. This has an effect only for sync handler functions. See using sync handler functions.
content_encoding¶ – A string describing the encoding of the content, e.g. base64.
content_media_type¶ – A string designating the media-type of the content, e.g. image/png.
deprecated¶ – A boolean dictating whether this route should be marked as deprecated in the OpenAPI schema.
description¶ – Text used for the route’s schema description section.
include_in_schema¶ – A boolean flag dictating whether the route handler should be documented in the OpenAPI schema.
operation_class¶ – Operation to be used with the route’s OpenAPI schema.
operation_id¶ – Either a string or a callable returning a string. An identifier used for the route’s schema operationId.
raises¶ – A list of exception classes extending from litestar.HttpException that is used for the OpenAPI documentation. This list should describe all exceptions raised within the route handler’s function/method. The Litestar ValidationException will be added automatically for the schema if any validation is involved.
response_description¶ – Text used for the route’s response schema description section.
security¶ – A sequence of dictionaries that contain information about which security scheme can be used on the endpoint.
summary¶ – Text used for the route’s schema summary section.
tags¶ – A sequence of string tags that will be appended to the OpenAPI schema.
type_decoders¶ – A sequence of tuples, each composed of a predicate testing for type identity and a msgspec hook for deserialization.
type_encoders¶ – A mapping of types to callables that transform them into types supported for serialization.
handler_class¶ – Route handler class instantiated by the decorator
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

litestar.handlers.post(path: str | None | Sequence[str] = None, *, after_request: AfterRequestHookHandler | None = None, after_response: AfterResponseHookHandler | None = None, background: BackgroundTask | BackgroundTasks | None = None, before_request: BeforeRequestHookHandler | None = None, cache: bool | int | type[CACHE_FOREVER] = False, cache_control: CacheControlHeader | None = None, cache_key_builder: CacheKeyBuilder | None = None, dependencies: Dependencies | None = None, dto: type[AbstractDTO] | None | EmptyType = _EmptyEnum.EMPTY, etag: ETag | None = None, exception_handlers: ExceptionHandlersMap | None = None, guards: Sequence[Guard] | None = None, media_type: MediaType | str | None = None, middleware: Sequence[Middleware] | None = None, name: str | None = None, opt: Mapping[str, Any] | None = None, request_class: type[Request] | None = None, request_max_body_size: int | None | EmptyType = _EmptyEnum.EMPTY, response_class: type[Response] | None = None, response_cookies: ResponseCookies | None = None, response_headers: ResponseHeaders | None = None, return_dto: type[AbstractDTO] | None | EmptyType = _EmptyEnum.EMPTY, signature_namespace: Mapping[str, Any] | None = None, status_code: int | None = None, sync_to_thread: bool | None = None, content_encoding: str | None = None, content_media_type: str | None = None, deprecated: bool = False, description: str | None = None, include_in_schema: bool | EmptyType = _EmptyEnum.EMPTY, operation_class: type[Operation] = <class 'litestar.openapi.spec.operation.Operation'>, operation_id: str | OperationIDCreator | None = None, raises: Sequence[type[HTTPException]] | None = None, response_description: str | None = None, responses: Mapping[int, ResponseSpec] | None = None, security: Sequence[SecurityRequirement] | None = None, summary: str | None = None, tags: Sequence[str] | None = None, type_decoders: TypeDecodersSequence | None = None, type_encoders: TypeEncodersMap | None = None, handler_class: type[HTTPRouteHandler] = <class 'litestar.handlers.http_handlers.base.HTTPRouteHandler'>, **kwargs: Any) → Callable[[AnyCallable], HTTPRouteHandler]¶

Create an HTTPRouteHandler with a POST method.

Parameters:

path¶ – A path fragment for the route handler function or a sequence of path fragments. If not given defaults to /
after_request¶ – A sync or async function executed before a Request is passed to any route handler. If this function returns a value, the request will not reach the route handler, and instead this value will be used.
after_response¶ – A sync or async function called after the response has been awaited. It receives the Request object and should not return any values.
background¶ – A BackgroundTask instance or BackgroundTasks to execute after the response is finished. Defaults to None.
before_request¶ – A sync or async function called immediately before calling the route handler. Receives the connection.Request instance and any non-None return value is used for the response, bypassing the route handler.
cache¶ – Enables response caching if configured on the application level. Valid values are True or a number of seconds (e.g. 120) to cache the response.
cache_control¶ – A cache-control header of type CacheControlHeader that will be added to the response.
cache_key_builder¶ – A cache-key builder function. Allows for customization of the cache key if caching is configured on the application level.
dependencies¶ – A string keyed mapping of dependency Provider instances.
dto¶ – AbstractDTO to use for (de)serializing and validation of request data.
etag¶ – An etag header of type ETag that will be added to the response.
exception_handlers¶ – A mapping of status codes and/or exception types to handler functions.
guards¶ – A sequence of Guard callables.
media_type¶ – A member of the MediaType enum or a string with a valid IANA Media-Type.
middleware¶ – A sequence of Middleware.
name¶ – A string identifying the route handler.
opt¶ – A string keyed mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
request_class¶ – A custom subclass of Request to be used as route handler’s default request.
request_max_body_size¶ – Maximum allowed size of the request body in bytes. If this size is exceeded, a ‘413 - Request Entity Too Large’ error response is returned.
response_class¶ – A custom subclass of Response to be used as route handler’s default response.
response_cookies¶ – A sequence of Cookie instances.
response_headers¶ – A string keyed mapping of ResponseHeader instances.
responses¶ – A mapping of additional status codes and a description of their expected content. This information will be included in the OpenAPI schema
return_dto¶ – AbstractDTO to use for serializing outbound response data.
signature_namespace¶ – A mapping of names to types for use in forward reference resolution during signature modelling.
status_code¶ – An http status code for the response. Defaults to 200 for mixed method or GET, PUT and PATCH, 201 for POST and 204 for DELETE.
sync_to_thread¶ – A boolean dictating whether the handler function will be executed in a worker thread or the main event loop. This has an effect only for sync handler functions. See using sync handler functions.
content_encoding¶ – A string describing the encoding of the content, e.g. base64.
content_media_type¶ – A string designating the media-type of the content, e.g. image/png.
deprecated¶ – A boolean dictating whether this route should be marked as deprecated in the OpenAPI schema.
description¶ – Text used for the route’s schema description section.
include_in_schema¶ – A boolean flag dictating whether the route handler should be documented in the OpenAPI schema.
operation_class¶ – Operation to be used with the route’s OpenAPI schema.
operation_id¶ – Either a string or a callable returning a string. An identifier used for the route’s schema operationId.
raises¶ – A list of exception classes extending from litestar.HttpException that is used for the OpenAPI documentation. This list should describe all exceptions raised within the route handler’s function/method. The Litestar ValidationException will be added automatically for the schema if any validation is involved.
response_description¶ – Text used for the route’s response schema description section.
security¶ – A sequence of dictionaries that contain information about which security scheme can be used on the endpoint.
summary¶ – Text used for the route’s schema summary section.
tags¶ – A sequence of string tags that will be appended to the OpenAPI schema.
type_decoders¶ – A sequence of tuples, each composed of a predicate testing for type identity and a msgspec hook for deserialization.
type_encoders¶ – A mapping of types to callables that transform them into types supported for serialization.
handler_class¶ – Route handler class instantiated by the decorator
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

litestar.handlers.put(path: str | None | Sequence[str] = None, *, after_request: AfterRequestHookHandler | None = None, after_response: AfterResponseHookHandler | None = None, background: BackgroundTask | BackgroundTasks | None = None, before_request: BeforeRequestHookHandler | None = None, cache: bool | int | type[CACHE_FOREVER] = False, cache_control: CacheControlHeader | None = None, cache_key_builder: CacheKeyBuilder | None = None, dependencies: Dependencies | None = None, dto: type[AbstractDTO] | None | EmptyType = _EmptyEnum.EMPTY, etag: ETag | None = None, exception_handlers: ExceptionHandlersMap | None = None, guards: Sequence[Guard] | None = None, media_type: MediaType | str | None = None, middleware: Sequence[Middleware] | None = None, name: str | None = None, opt: Mapping[str, Any] | None = None, request_class: type[Request] | None = None, request_max_body_size: int | None | EmptyType = _EmptyEnum.EMPTY, response_class: type[Response] | None = None, response_cookies: ResponseCookies | None = None, response_headers: ResponseHeaders | None = None, return_dto: type[AbstractDTO] | None | EmptyType = _EmptyEnum.EMPTY, signature_namespace: Mapping[str, Any] | None = None, status_code: int | None = None, sync_to_thread: bool | None = None, content_encoding: str | None = None, content_media_type: str | None = None, deprecated: bool = False, description: str | None = None, include_in_schema: bool | EmptyType = _EmptyEnum.EMPTY, operation_class: type[Operation] = <class 'litestar.openapi.spec.operation.Operation'>, operation_id: str | OperationIDCreator | None = None, raises: Sequence[type[HTTPException]] | None = None, response_description: str | None = None, responses: Mapping[int, ResponseSpec] | None = None, security: Sequence[SecurityRequirement] | None = None, summary: str | None = None, tags: Sequence[str] | None = None, type_decoders: TypeDecodersSequence | None = None, type_encoders: TypeEncodersMap | None = None, handler_class: type[HTTPRouteHandler] = <class 'litestar.handlers.http_handlers.base.HTTPRouteHandler'>, **kwargs: Any) → Callable[[AnyCallable], HTTPRouteHandler]¶

Create an HTTPRouteHandler with a PUT method.

Parameters:

path¶ – A path fragment for the route handler function or a sequence of path fragments. If not given defaults to /
after_request¶ – A sync or async function executed before a Request is passed to any route handler. If this function returns a value, the request will not reach the route handler, and instead this value will be used.
after_response¶ – A sync or async function called after the response has been awaited. It receives the Request object and should not return any values.
background¶ – A BackgroundTask instance or BackgroundTasks to execute after the response is finished. Defaults to None.
before_request¶ – A sync or async function called immediately before calling the route handler. Receives the connection.Request instance and any non-None return value is used for the response, bypassing the route handler.
cache¶ – Enables response caching if configured on the application level. Valid values are True or a number of seconds (e.g. 120) to cache the response.
cache_control¶ – A cache-control header of type CacheControlHeader that will be added to the response.
cache_key_builder¶ – A cache-key builder function. Allows for customization of the cache key if caching is configured on the application level.
dependencies¶ – A string keyed mapping of dependency Provider instances.
dto¶ – AbstractDTO to use for (de)serializing and validation of request data.
etag¶ – An etag header of type ETag that will be added to the response.
exception_handlers¶ – A mapping of status codes and/or exception types to handler functions.
guards¶ – A sequence of Guard callables.
media_type¶ – A member of the MediaType enum or a string with a valid IANA Media-Type.
middleware¶ – A sequence of Middleware.
name¶ – A string identifying the route handler.
opt¶ – A string keyed mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
request_class¶ – A custom subclass of Request to be used as route handler’s default request.
request_max_body_size¶ – Maximum allowed size of the request body in bytes. If this size is exceeded, a ‘413 - Request Entity Too Large’ error response is returned.
response_class¶ – A custom subclass of Response to be used as route handler’s default response.
response_cookies¶ – A sequence of Cookie instances.
response_headers¶ – A string keyed mapping of ResponseHeader instances.
responses¶ – A mapping of additional status codes and a description of their expected content. This information will be included in the OpenAPI schema
return_dto¶ – AbstractDTO to use for serializing outbound response data.
signature_namespace¶ – A mapping of names to types for use in forward reference resolution during signature modelling.
status_code¶ – An http status code for the response. Defaults to 200 for mixed method or GET, PUT and PATCH, 201 for POST and 204 for DELETE.
sync_to_thread¶ – A boolean dictating whether the handler function will be executed in a worker thread or the main event loop. This has an effect only for sync handler functions. See using sync handler functions.
content_encoding¶ – A string describing the encoding of the content, e.g. base64.
content_media_type¶ – A string designating the media-type of the content, e.g. image/png.
deprecated¶ – A boolean dictating whether this route should be marked as deprecated in the OpenAPI schema.
description¶ – Text used for the route’s schema description section.
include_in_schema¶ – A boolean flag dictating whether the route handler should be documented in the OpenAPI schema.
operation_class¶ – Operation to be used with the route’s OpenAPI schema.
operation_id¶ – Either a string or a callable returning a string. An identifier used for the route’s schema operationId.
raises¶ – A list of exception classes extending from litestar.HttpException that is used for the OpenAPI documentation. This list should describe all exceptions raised within the route handler’s function/method. The Litestar ValidationException will be added automatically for the schema if any validation is involved.
response_description¶ – Text used for the route’s response schema description section.
security¶ – A sequence of dictionaries that contain information about which security scheme can be used on the endpoint.
summary¶ – Text used for the route’s schema summary section.
tags¶ – A sequence of string tags that will be appended to the OpenAPI schema.
type_decoders¶ – A sequence of tuples, each composed of a predicate testing for type identity and a msgspec hook for deserialization.
type_encoders¶ – A mapping of types to callables that transform them into types supported for serialization.
handler_class¶ – Route handler class instantiated by the decorator
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

Create an HTTPRouteHandler.

Parameters:

path¶ – A path fragment for the route handler function or a sequence of path fragments. If not given defaults to /
after_request¶ – A sync or async function executed before a Request is passed to any route handler. If this function returns a value, the request will not reach the route handler, and instead this value will be used.
after_response¶ – A sync or async function called after the response has been awaited. It receives the Request object and should not return any values.
background¶ – A BackgroundTask instance or BackgroundTasks to execute after the response is finished. Defaults to None.
before_request¶ – A sync or async function called immediately before calling the route handler. Receives the connection.Request instance and any non-None return value is used for the response, bypassing the route handler.
cache¶ – Enables response caching if configured on the application level. Valid values are True or a number of seconds (e.g. 120) to cache the response.
cache_control¶ – A cache-control header of type CacheControlHeader that will be added to the response.
cache_key_builder¶ – A cache-key builder function. Allows for customization of the cache key if caching is configured on the application level.
dependencies¶ – A string keyed mapping of dependency Provider instances.
dto¶ – AbstractDTO to use for (de)serializing and validation of request data.
etag¶ – An etag header of type ETag that will be added to the response.
exception_handlers¶ – A mapping of status codes and/or exception types to handler functions.
guards¶ – A sequence of Guard callables.
http_method¶ – An http method string, a member of the enum HttpMethod or a list of these that correlates to the methods the route handler function should handle.
media_type¶ – A member of the MediaType enum or a string with a valid IANA Media-Type.
middleware¶ – A sequence of Middleware.
name¶ – A string identifying the route handler.
opt¶ – A string keyed mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
request_class¶ – A custom subclass of Request to be used as route handler’s default request.
response_class¶ – A custom subclass of Response to be used as route handler’s default response.
response_cookies¶ – A sequence of Cookie instances.
response_headers¶ – A string keyed mapping of ResponseHeader instances.
responses¶ – A mapping of additional status codes and a description of their expected content. This information will be included in the OpenAPI schema
return_dto¶ – AbstractDTO to use for serializing outbound response data.
signature_namespace¶ – A mapping of names to types for use in forward reference resolution during signature modelling.
status_code¶ – An http status code for the response. Defaults to 200 for mixed method or GET, PUT and PATCH, 201 for POST and 204 for DELETE.
sync_to_thread¶ – A boolean dictating whether the handler function will be executed in a worker thread or the main event loop. This has an effect only for sync handler functions. See using sync handler functions.
content_encoding¶ – A string describing the encoding of the content, e.g. base64.
content_media_type¶ – A string designating the media-type of the content, e.g. image/png.
deprecated¶ – A boolean dictating whether this route should be marked as deprecated in the OpenAPI schema.
description¶ – Text used for the route’s schema description section.
include_in_schema¶ – A boolean flag dictating whether the route handler should be documented in the OpenAPI schema.
operation_class¶ – Operation to be used with the route’s OpenAPI schema.
operation_id¶ – Either a string or a callable returning a string. An identifier used for the route’s schema operationId.
raises¶ – A list of exception classes extending from litestar.HttpException that is used for the OpenAPI documentation. This list should describe all exceptions raised within the route handler’s function/method. The Litestar ValidationException will be added automatically for the schema if any validation is involved.
response_description¶ – Text used for the route’s response schema description section.
security¶ – A sequence of dictionaries that contain information about which security scheme can be used on the endpoint.
summary¶ – Text used for the route’s schema summary section.
tags¶ – A sequence of string tags that will be appended to the OpenAPI schema.
type_decoders¶ – A sequence of tuples, each composed of a predicate testing for type identity and a msgspec hook for deserialization.
type_encoders¶ – A mapping of types to callables that transform them into types supported for serialization.
handler_class¶ – Route handler class instantiated by the decorator
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

async litestar.handlers.send_websocket_stream(socket: WebSocket, stream: AsyncGenerator[Any, Any], *, close: bool = True, mode: WebSocketMode = 'text', send_handler: Callable[[WebSocket, Any], Awaitable[Any]] | None = None, listen_for_disconnect: bool = False, warn_on_data_discard: bool = True) → None¶

Stream data to the socket from an asynchronous generator.

Example

Sending the current time to the connected client every 0.5 seconds:

async def stream_current_time() -> AsyncGenerator[str, None]:
    while True:
        yield str(time.time())
        await asyncio.sleep(0.5)


@websocket("/time")
async def time_handler(socket: WebSocket) -> None:
    await socket.accept()
    await send_websocket_stream(
        socket,
        stream_current_time(),
        listen_for_disconnect=True,
    )

Parameters:

socket¶ – The WebSocket to send to
stream¶ – An asynchronous generator yielding data to send
close¶ – If True, close the socket after the generator is exhausted
mode¶ – WebSocket mode to use for sending when no send_handler is specified
send_handler¶ – Callable to handle the send process. If None, defaults to type(socket).send_data
listen_for_disconnect¶ – If True, listen for client disconnects in the background. If a client disconnects, stop the generator and cancel sending data. Should always be True unless disconnects are handled elsewhere, for example by reading data from the socket concurrently. Should never be set to True when reading data from socket concurrently, as it can lead to data loss
warn_on_data_discard¶ – If True and listen_for_disconnect=True, warn if during listening for client disconnects, data is received from the socket

litestar.handlers.websocket(path: str | list[str] | None = None, *, dependencies: Dependencies | None = None, exception_handlers: dict[int | type[Exception], ExceptionHandler] | None = None, guards: list[Guard] | None = None, middleware: list[Middleware] | None = None, name: str | None = None, opt: dict[str, Any] | None = None, signature_namespace: Mapping[str, Any] | None = None, websocket_class: type[WebSocket] | None = None, handler_class: type[WebsocketRouteHandler] = <class 'litestar.handlers.websocket_handlers.route_handler.WebsocketRouteHandler'>, **kwargs: Any) → Callable[[AsyncAnyCallable], WebsocketRouteHandler]¶

Create a WebsocketRouteHandler.

Parameters:

path¶ – A path fragment for the route handler function or a sequence of path fragments. If not given defaults to /
dependencies¶ – A string keyed mapping of dependency Provider instances.
exception_handlers¶ – A mapping of status codes and/or exception types to handler functions.
guards¶ – A sequence of Guard callables.
middleware¶ – A sequence of Middleware.
name¶ – A string identifying the route handler.
opt¶ – A string keyed mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
signature_namespace¶ – A mapping of names to types for use in forward reference resolution during signature modelling.
websocket_class¶ – A custom subclass of WebSocket to be used as route handler’s default websocket class.
handler_class¶ – Route handler class instantiated by the decorator
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

litestar.handlers.websocket_listener(path: str | list[str] | None = None, *, connection_accept_handler: Callable[[WebSocket], Coroutine[Any, Any, None]] = <function WebSocket.accept>, connection_lifespan: Callable[..., AbstractAsyncContextManager[Any]] | None = None, dependencies: Dependencies | None = None, dto: type[AbstractDTO] | None | EmptyType = _EmptyEnum.EMPTY, exception_handlers: dict[int | type[Exception], ExceptionHandler] | None = None, guards: list[Guard] | None = None, middleware: list[Middleware] | None = None, receive_mode: WebSocketMode = 'text', send_mode: WebSocketMode = 'text', name: str | None = None, on_accept: AnyCallable | None = None, on_disconnect: AnyCallable | None = None, opt: dict[str, Any] | None = None, return_dto: type[AbstractDTO] | None | EmptyType = _EmptyEnum.EMPTY, signature_namespace: Mapping[str, Any] | None = None, type_decoders: TypeDecodersSequence | None = None, type_encoders: TypeEncodersMap | None = None, websocket_class: type[WebSocket] | None = None, **kwargs: Any) → Callable[[AnyCallable], WebsocketListenerRouteHandler]¶

Create a WebsocketListenerRouteHandler.

Parameters:

path¶ – A path fragment for the route handler function or a sequence of path fragments. If not given defaults to /
connection_accept_handler¶ – A callable that accepts a WebSocket instance and returns a coroutine that when awaited, will accept the connection. Defaults to WebSocket.accept.
connection_lifespan¶ – An asynchronous context manager, handling the lifespan of the connection. By default, it calls the connection_accept_handler, on_connect and on_disconnect. Can request any dependencies, for example the WebSocket connection
dependencies¶ – A string keyed mapping of dependency Provider instances.
dto¶ – AbstractDTO to use for (de)serializing and validation of request data.
exception_handlers¶ – A mapping of status codes and/or exception types to handler functions.
guards¶ – A sequence of Guard callables.
middleware¶ – A sequence of Middleware.
receive_mode¶ – Websocket mode to receive data in, either text or binary.
send_mode¶ – Websocket mode to receive data in, either text or binary.
name¶ – A string identifying the route handler.
on_accept¶ – Callback invoked after a connection has been accepted. Can request any dependencies, for example the WebSocket connection
on_disconnect¶ – Callback invoked after a connection has been closed. Can request any dependencies, for example the WebSocket connection
opt¶ – A string keyed mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
return_dto¶ – AbstractDTO to use for serializing outbound response data.
signature_namespace¶ – A mapping of names to types for use in forward reference resolution during signature modelling.
type_decoders¶ – A sequence of tuples, each composed of a predicate testing for type identity and a msgspec hook for deserialization.
type_encoders¶ – A mapping of types to callables that transform them into types supported for serialization.
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.
websocket_class¶ – A custom subclass of WebSocket to be used as route handler’s default websocket class.

litestar.handlers.websocket_stream(path: str | list[str] | None = None, *, dependencies: Dependencies | None = None, exception_handlers: dict[int | type[Exception], ExceptionHandler] | None = None, guards: list[Guard] | None = None, middleware: list[Middleware] | None = None, name: str | None = None, opt: dict[str, Any] | None = None, signature_namespace: Mapping[str, Any] | None = None, websocket_class: type[WebSocket] | None = None, mode: WebSocketMode = 'text', return_dto: type[AbstractDTO] | None | EmptyType = _EmptyEnum.EMPTY, type_encoders: TypeEncodersMap | None = None, listen_for_disconnect: bool = True, warn_on_data_discard: bool = True, **kwargs: Any) → Callable[[Callable[..., AsyncGenerator[Any, Any]]], WebsocketRouteHandler]¶

Create a WebSocket handler that accepts a connection and sends data to it from an async generator.

Example

Sending the current time to the connected client every 0.5 seconds:

@websocket_stream("/time")
async def send_time() -> AsyncGenerator[str, None]:
    while True:
        yield str(time.time())
        await asyncio.sleep(0.5)

Parameters:

path¶ – A path fragment for the route handler function or a sequence of path fragments. If not given defaults to /
dependencies¶ – A string keyed mapping of dependency Provider instances.
exception_handlers¶ – A mapping of status codes and/or exception types to handler functions.
guards¶ – A sequence of Guard callables.
middleware¶ – A sequence of Middleware.
name¶ – A string identifying the route handler.
opt¶ – A string keyed mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
signature_namespace¶ – A mapping of names to types for use in forward reference resolution during signature modelling.
websocket_class¶ – A custom subclass of WebSocket to be used as route handler’s default websocket class.
mode¶ – WebSocket mode used for sending
return_dto¶ – AbstractDTO to use for serializing outbound response data.
type_encoders¶ – A mapping of types to callables that transform them into types supported for serialization.
listen_for_disconnect¶ – If True, listen for client disconnects in the background. If a client disconnects, stop the generator and cancel sending data. Should always be True unless disconnects are handled elsewhere, for example by reading data from the socket concurrently. Should never be set to True when reading data from socket concurrently, as it can lead to data loss
warn_on_data_discard¶ – If True and listen_for_disconnect=True, warn if during listening for client disconnects, data is received from the socket
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.