connection¶

class litestar.connection.ASGIConnection[source]¶

Bases: Generic[HandlerT, UserT, AuthT, StateT]

The base ASGI connection container.

receive: Receive¶: The ASGI receive function.

scope: Scope¶: The ASGI scope attached to the connection.

send: Send¶: The ASGI send function.

__init__(scope: Scope, receive: Receive = <function empty_receive>, send: Send = <function empty_send>) → None[source]¶

Initialize ASGIConnection.

Parameters:

scope¶ – The ASGI connection scope.
receive¶ – The ASGI receive function.
send¶ – The ASGI send function.

property app: Litestar¶

Return the app for this connection.

Returns:: The Litestar application instance

property auth: AuthT¶

Return the auth data of this connection’s Scope.

Raises:: ImproperlyConfiguredException – If auth is not set in scope via an AuthMiddleware, raises an exception
Returns:: A type correlating to the generic variable Auth.

property base_url: URL¶

Return the base URL of this connection’s Scope.

Returns:: A URL instance constructed from the request’s scope, representing only the base part (host + domain + prefix) of the request.

clear_session() → None[source]¶

Remove the session from the connection’s Scope.

If the Litestar SessionMiddleware is enabled, this will cause the session data to be cleared.

Returns:: None.

property client: Address | None¶

Return the client data of this connection’s Scope.

Returns:: A two tuple of the host name and port number.

property cookies: dict[str, str]¶

Return the cookies of this connection’s Scope.

Returns:: Returns any cookies stored in the header as a parsed dictionary.

property headers: Headers¶

Return the headers of this connection’s Scope.

Returns:: A Headers instance with the request’s scope[“headers”] value.

property path_params: dict[str, Any]¶

Return the path_params of this connection’s Scope.

Returns:: A string keyed dictionary of path parameter values.

property query_params: MultiDict[Any]¶

Return the query parameters of this connection’s Scope.

Returns:: A normalized dict of query parameters. Multiple values for the same key are returned as a list.

property route_handler: HandlerT¶

Return the route_handler for this connection.

Returns:: The target route handler instance.

property session: dict[str, Any]¶

Return the session for this connection if a session was previously set in the Scope

Returns:: A dictionary representing the session value - if existing.
Raises:: ImproperlyConfiguredException – if session is not set in scope.

set_session(value: dict[str, Any] | DataContainerType | EmptyType) → None[source]¶

Set the session in the connection’s Scope.

If the SessionMiddleware is enabled, the session will be added to the response as a cookie header.

Parameters:: value¶ – Dictionary or pydantic model instance for the session data.
Returns:: None

property state: StateT¶

Return the State of this connection.

Returns:: A State instance constructed from the scope[“state”] value.

property url: URL¶

Return the URL of this connection’s Scope.

Returns:: A URL instance constructed from the request’s scope.

url_for(name: str | BaseRouteHandler, **path_parameters: Any) → str[source]¶

Return the url for a given route handler / handler name.

Parameters:

name¶ – The name of the route handler, or the route handler itself.
**path_parameters¶ – Values for path parameters in the route

Raises:

NoRouteMatchFoundException – If route with name does not exist, path parameters are missing or have a wrong type.

Returns:

A string representing the absolute url of the route handler.

property user: UserT¶

Return the user data of this connection’s Scope.

Raises:: ImproperlyConfiguredException – If user is not set in scope via an AuthMiddleware, raises an exception
Returns:: A type correlating to the generic variable User.

class litestar.connection.Request[source]¶

Bases: Generic[UserT, AuthT, StateT], ASGIConnection[HTTPRouteHandler, UserT, AuthT, StateT]

The Litestar Request class.

__init__(scope: Scope, receive: Receive = <function empty_receive>, send: Send = <function empty_send>) → None[source]¶

Initialize Request.

Parameters:

scope¶ – The ASGI connection scope.
receive¶ – The ASGI receive function.
send¶ – The ASGI send function.

property accept: Accept¶

Parse the request’s ‘Accept’ header, returning an Accept instance.

Returns:: An Accept instance, representing the list of acceptable media types.

async body() → bytes[source]¶

Return the body of the request.

Returns:: A byte-string representing the body of the request.

property content_type: tuple[str, dict[str, str]]¶

Parse the request’s ‘Content-Type’ header, returning the header value and any options as a dictionary.

Returns:: A tuple with the parsed value and a dictionary containing any options send in it.

async form() → FormMultiDict[source]¶

Retrieve form data from the request. If the request is either a ‘multipart/form-data’ or an ‘application/x-www-form- urlencoded’, return a FormMultiDict instance populated with the values sent in the request, otherwise, an empty instance.

Returns:: A FormMultiDict instance

async json() → Any[source]¶

Retrieve the json request body from the request.

Returns:: An arbitrary value

property method: Method¶

Return the request method.

Returns:: The request Method

async msgpack() → Any[source]¶

Retrieve the MessagePack request body from the request.

Returns:: An arbitrary value

async send_push_promise(path: str, raise_if_unavailable: bool = False) → None[source]¶

Send a push promise.

This method requires the http.response.push extension to be sent from the ASGI server.

Parameters:

path¶ – Path to send the promise to.
raise_if_unavailable¶ – Raise an exception if server push is not supported by the server

Returns:

None

async stream() → AsyncGenerator[bytes, None][source]¶

Return an async generator that streams chunks of bytes.

Returns:: An async generator.
Raises:: RuntimeError – if the stream is already consumed

class litestar.connection.WebSocket[source]¶

Bases: Generic[UserT, AuthT, StateT], ASGIConnection[WebsocketRouteHandler, UserT, AuthT, StateT]

The Litestar WebSocket class.

__init__(scope: Scope, receive: Receive = <function empty_receive>, send: Send = <function empty_send>) → None[source]¶

Initialize WebSocket.

Parameters:

scope¶ – The ASGI connection scope.
receive¶ – The ASGI receive function.
send¶ – The ASGI send function.

async accept(subprotocols: str | None = None, headers: Headers | dict[str, Any] | list[tuple[bytes, bytes]] | None = None) → None[source]¶

Accept the incoming connection. This method should be called before receiving data.

Parameters:

subprotocols¶ – Websocket sub-protocol to use.
headers¶ – Headers to set on the data sent.

Returns:

None

async close(code: int = 1000, reason: str | None = None) → None[source]¶

Send an ‘websocket.close’ event.

Parameters:

code¶ – Status code.
reason¶ – Reason for closing the connection

Returns:

None

async iter_data(mode: WebSocketMode = 'text') → AsyncGenerator[str | bytes, None][source]¶

Continuously receive data and yield it

Parameters:: mode¶ – Socket mode to use. Either text or binary

async iter_json(mode: WebSocketMode = 'text') → AsyncGenerator[Any, None][source]¶

Continuously receive data and yield it, decoding it as JSON in the process.

Parameters:: mode¶ – Socket mode to use. Either text or binary

async iter_msgpack() → AsyncGenerator[Any, None][source]¶

Continuously receive data and yield it, decoding it as MessagePack in the process.

Note that since MessagePack is a binary format, this method will always receive data in binary mode.

async receive_bytes() → bytes[source]¶

Receive data as bytes.

Returns:: A byte-string.

async receive_data(mode: WebSocketMode) → str | bytes[source]¶

Receive an ‘websocket.receive’ event and returns the data stored on it.

Parameters:: mode¶ – The respective event key to use.
Returns:: The event’s data.

async receive_json(mode: WebSocketMode = 'text') → Any[source]¶

Receive data and decode it as JSON.

Parameters:: mode¶ – Either text or binary.
Returns:: An arbitrary value

async receive_msgpack() → Any[source]¶

Receive data and decode it as MessagePack.

Note that since MessagePack is a binary format, this method will always receive data in binary mode.

Returns:: An arbitrary value

async receive_text() → str[source]¶

Receive data as text.

Returns:: A string.

receive_wrapper(receive: Receive) → Receive[source]¶

Wrap receive to set ‘self.connection_state’ and validate events.

Parameters:: receive¶ – The ASGI receive function.
Returns:: An ASGI receive function.

async send_bytes(data: str | bytes, encoding: str = 'utf-8') → None[source]¶

Send data using the bytes key of the send event.

Parameters:

data¶ – Data to send
encoding¶ – Encoding to use for binary data.

Returns:

None

async send_data(data: str | bytes, mode: WebSocketMode = 'text', encoding: str = 'utf-8') → None[source]¶

Send a ‘websocket.send’ event.

Parameters:

data¶ – Data to send.
mode¶ – The respective event key to use.
encoding¶ – Encoding to use when converting bytes / str.

Returns:

None

async send_json(data: Any, mode: WebSocketMode = 'text', encoding: str = 'utf-8', serializer: Serializer = <function default_serializer>) → None[source]¶

Send data as JSON.

Parameters:

data¶ – A value to serialize.
mode¶ – Either text or binary.
encoding¶ – Encoding to use for binary data.
serializer¶ – A serializer function.

Returns:

None

async send_msgpack(data: Any, encoding: str = 'utf-8', serializer: Serializer = <function default_serializer>) → None[source]¶

Send data as MessagePack.

Note that since MessagePack is a binary format, this method will always send data in binary mode.

Parameters:

data¶ – A value to serialize.
encoding¶ – Encoding to use for binary data.
serializer¶ – A serializer function.

Returns:

None

async send_text(data: str | bytes, encoding: str = 'utf-8') → None[source]¶

Send data using the text key of the send event.

Parameters:

data¶ – Data to send
encoding¶ – Encoding to use for binary data.

Returns:

None

send_wrapper(send: Send) → Send[source]¶

Wrap send to ensure that state is not disconnected.

Parameters:: send¶ – The ASGI send function.
Returns:: An ASGI send function.