handlers#

class litestar.handlers.ASGIRouteHandler#

Bases: BaseRouteHandler

ASGI Route Handler decorator.

Use this decorator to decorate ASGI applications.

Initialize ASGIRouteHandler.

Parameters:

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.
path¶ – A path fragment for the route handler function or a list of path fragments. If not given defaults to /
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.
is_static¶ – A boolean dictating whether the handler’s paths should be regarded as static paths. Static paths are used to deliver static files.
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
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

on_registration(app: Litestar) → None#

Called once per handler when the app object is instantiated.

Parameters:: app¶ – The Litestar app object.
Returns:: None

class litestar.handlers.BaseRouteHandler#

Bases: object

Base route handler.

Serves as a subclass for all route handlers

__call__(fn: AsyncAnyCallable) → Self#: Replace a function with itself.

Initialize HTTPRouteHandler.

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.
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.
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

__str__() → str#

Return a unique identifier for the route handler.

Returns:: A string

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

create_kwargs_model(path_parameters: dict[str, PathParameterDefinition]) → KwargsModel#: Create a KwargsModel for a given route handler.

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 dependency_name_set: set[str]#: Set of all dependency names provided in the handler’s ownership layers.

property fn: AsyncAnyCallable#

Get the handler function.

Raises:: ImproperlyConfiguredException – if handler fn is not set.
Returns:: Handler function

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

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

on_registration(app: Litestar) → None#

Called once per handler when the app object is instantiated.

Parameters:: app¶ – The Litestar app object.
Returns:: None

property ownership_layers: list[Self | Controller | Router]#

Return the handler layers from the app down to the route handler.

app -> ... -> 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

resolve_data_dto() → type[AbstractDTO] | None#

Resolve the data_dto 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 DTO type

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

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_guards() → list[Guard]#: Return all guards in the handlers scope, starting from highest to current layer.

resolve_layered_parameters() → dict[str, FieldDefinition]#: Return all parameters declared above the handler.

resolve_middleware() → list[Middleware]#

Build the middleware stack for the RouteHandler and return it.

The middlewares are added from top to bottom (app -> router -> controller -> route handler) and then reversed.

resolve_opts() → None#

Build the route handler opt dictionary by going from top to bottom.

When merging keys from multiple layers, if the same key is defined by multiple layers, the value from the layer closest to the response handler will take precedence.

resolve_return_dto() → type[AbstractDTO] | None#

Resolve the return_dto 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 DTO type

resolve_signature_namespace() → dict[str, Any]#

Build the route handler signature namespace dictionary by going from top to bottom.

When merging keys from multiple layers, if the same key is defined by multiple layers, the value from the layer closest to the response handler will take precedence.

resolve_type_decoders() → Sequence[tuple[Callable[[Any], bool], Callable[[Any, Any], Any]]]#

Return a merged type_encoders mapping.

This method is memoized so the computation occurs only once.

Returns:: A dict of type encoders

resolve_type_encoders() → Mapping[Any, Callable[[Any], Any]]#

Return a merged type_encoders mapping.

This method is memoized so the computation occurs only once.

Returns:: A dict of type encoders

property signature_model: type[SignatureModel]#

Get the signature model for the route handler.

Returns:: A signature model for the route handler.

class litestar.handlers.HTTPRouteHandler#

Bases: BaseRouteHandler

HTTP Route Decorator.

Use this decorator to decorate an HTTP handler with multiple methods.

__call__(fn: Callable[[...], Any]) → HTTPRouteHandler#: Replace a function with itself.

Initialize 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 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.
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

get_response_handler(is_response_type_data: bool = False) → Callable[[Any], Awaitable[ASGIApp]]#

Resolve the response_handler function for the route handler.

This method is memoized so the computation occurs only once.

Parameters:: is_response_type_data¶ – Whether to return a handler for ‘Response’ instances.
Returns:: Async Callable to handle an HTTP Request

on_registration(app: Litestar) → None#

Called once per handler when the app object is instantiated.

Parameters:: app¶ – The Litestar app object.
Returns:: None

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_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_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_request_class() → type[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[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_response_cookies() → frozenset[Cookie]#

Return a list of Cookie instances. Filters the list to ensure each cookie key is unique.

Returns:: A list of Cookie instances.

resolve_response_headers() → frozenset[ResponseHeader]#

Return all header parameters in the scope of the handler function.

Returns:: A dictionary mapping keys to ResponseHeader instances.

resolve_security() → list[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() → list[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.

Returns:: A sorted list of unique tags.
Return type:: list[str]

async to_response(app: Litestar, data: Any, request: Request) → ASGIApp#

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

Parameters:

app¶ – The Litestar app instance
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

__init__(owner: Router) → None#

Initialize a WebsocketListener instance.

Parameters:: owner¶ – The Router instance that owns this listener.

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.

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

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

abstractmethod 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.

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.

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 /

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

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

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

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

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

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

__init__(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) → None#

Initialize WebsocketRouteHandler

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.

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

property signature_model: type[SignatureModel]#

Get the signature model for the route handler.

Returns:: A signature model for the route handler.

class litestar.handlers.WebsocketRouteHandler#

Bases: BaseRouteHandler

Websocket route handler decorator.

Use this decorator to decorate websocket handler functions.

Initialize 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.
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.
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

resolve_websocket_class() → type[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.

litestar.handlers.asgi#: alias of ASGIRouteHandler

class litestar.handlers.delete#

Bases: HTTPRouteHandler

DELETE Route Decorator.

Use this decorator to decorate an HTTP handler for DELETE requests.

Initialize delete

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.
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.
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

class litestar.handlers.get#

Bases: HTTPRouteHandler

GET Route Decorator.

Use this decorator to decorate an HTTP handler for GET requests.

Initialize get.

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.
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

class litestar.handlers.head#

Bases: HTTPRouteHandler

HEAD Route Decorator.

Use this decorator to decorate an HTTP handler for HEAD requests.

Initialize head.

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.
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.
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

class litestar.handlers.patch#

Bases: HTTPRouteHandler

PATCH Route Decorator.

Use this decorator to decorate an HTTP handler for PATCH requests.

Initialize patch.

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.
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.
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

class litestar.handlers.post#

Bases: HTTPRouteHandler

POST Route Decorator.

Use this decorator to decorate an HTTP handler for POST requests.

Initialize post

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.
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.
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

class litestar.handlers.put#

Bases: HTTPRouteHandler

PUT Route Decorator.

Use this decorator to decorate an HTTP handler for PUT requests.

Initialize put

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.
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.
**kwargs¶ – Any additional kwarg - will be set in the opt dictionary.

litestar.handlers.route#: alias of HTTPRouteHandler

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#: alias of WebsocketRouteHandler

litestar.handlers.websocket_listener#: alias of WebsocketListenerRouteHandler

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.