response#

class litestar.response.File#

Bases: Response

A response, streaming a file as response body.

Initialize File

Notes

This class extends the Stream class.

Parameters:

path¶ – A file path in one of the supported formats.
background¶ – A BackgroundTask instance or BackgroundTasks to execute after the response is finished. Defaults to None.
chunk_size¶ – The chunk sizes to use when streaming the file. Defaults to 1MB.
content_disposition_type¶ – The type of the Content-Disposition. Either inline or attachment.
cookies¶ – A list of Cookie instances to be set under the response Set-Cookie header.
encoding¶ – The encoding to be used for the response headers.
etag¶ – An optional ETag instance. If not provided, an etag will be generated.
file_info¶ – The output of calling file_system.info, equivalent to providing an os.stat_result.
file_system¶ – An implementation of the FileSystemProtocol. If provided it will be used to load the file.
filename¶ – An optional filename to set in the header.
headers¶ – A string keyed dictionary of response headers. Header keys are insensitive.
media_type¶ – A value for the response Content-Type header. If not provided, the value will be either derived from the filename if provided and supported by the stdlib, or will default to application/octet-stream.
stat_result¶ – An optional result of calling :func:os.stat:. If not provided, this will be done by the response constructor.
status_code¶ – An HTTP status code.

Create an ASGIFileResponse instance.

Parameters:

app¶ – The Litestar application instance.
background¶ – Background task(s) to be executed after the response is sent.
cookies¶ – A list of cookies to be set on the response.
encoded_headers¶ – A list of already encoded headers.
headers¶ – Additional headers to be merged with the response headers. Response headers take precedence.
is_head_response¶ – Whether the response is a HEAD response.
media_type¶ – Media type for the response. If media_type is already set on the response, this is ignored.
request¶ – The Request instance.
status_code¶ – Status code for the response. If status_code is already set on the response, this is
type_encoders¶ – A dictionary of type encoders to use for encoding the response content.

Returns:

A low-level ASGI file response.

class litestar.response.Redirect#

Bases: Response[Any]

A redirect response.

Initialize the response.

Parameters:

path¶ – A path to redirect to.
background¶ – A background task or tasks to be run after the response is sent.
cookies¶ – A list of Cookie instances to be set under the response Set-Cookie header.
encoding¶ – The encoding to be used for the response headers.
headers¶ – A string keyed dictionary of response headers. Header keys are insensitive.
media_type¶ – A value for the response Content-Type header.
status_code¶ – An HTTP status code. The status code should be one of 301, 302, 303, 307 or 308, otherwise an exception will be raised.
type_encoders¶ – A mapping of types to callables that transform them into types supported for serialization.

Raises:

ImproperlyConfiguredException – Either if status code is not a redirect status code or media type is not supported.

Create an ASGIResponse from a Response instance.

Parameters:

app¶ – The Litestar application instance.
background¶ – Background task(s) to be executed after the response is sent.
cookies¶ – A list of cookies to be set on the response.
encoded_headers¶ – A list of already encoded headers.
headers¶ – Additional headers to be merged with the response headers. Response headers take precedence.
is_head_response¶ – Whether the response is a HEAD response.
media_type¶ – Media type for the response. If media_type is already set on the response, this is ignored.
request¶ – The Request instance.
status_code¶ – Status code for the response. If status_code is already set on the response, this is
type_encoders¶ – A dictionary of type encoders to use for encoding the response content.

Returns:

An ASGIResponse instance.

class litestar.response.Response#

Bases: Generic[T]

Base Litestar HTTP response class, used as the basis for all other response classes.

Initialize the response.

Parameters:

content¶ – A value for the response body that will be rendered into bytes string.
status_code¶ – An HTTP status code.
media_type¶ – A value for the response Content-Type header.
background¶ – A BackgroundTask instance or BackgroundTasks to execute after the response is finished. Defaults to None.
headers¶ – A string keyed dictionary of response headers. Header keys are insensitive.
cookies¶ – A list of Cookie instances to be set under the response Set-Cookie header.
encoding¶ – The encoding to be used for the response headers.
type_encoders¶ – A mapping of types to callables that transform them into types supported for serialization.

set_cookie(cookie: Cookie) → None#

set_cookie(key: str, value: str | None = None, max_age: int | None = None, expires: int | None = None, path: str = '/', domain: str | None = None, secure: bool = False, httponly: bool = False, samesite: Literal['lax', 'strict', 'none'] = 'lax') → None

Set a cookie on the response. If passed a Cookie instance, keyword arguments will be ignored.

Parameters:

key¶ – Key for the cookie or a Cookie instance.
value¶ – Value for the cookie, if none given defaults to empty string.
max_age¶ – Maximal age of the cookie before its invalidated.
expires¶ – Seconds from now until the cookie expires.
path¶ – Path fragment that must exist in the request url for the cookie to be valid. Defaults to /.
domain¶ – Domain for which the cookie is valid.
secure¶ – Https is required for the cookie.
httponly¶ – Forbids javascript to access the cookie via document.cookie.
samesite¶ – Controls whether a cookie is sent with cross-site requests. Defaults to lax.

Returns:

None.

set_header(key: str, value: Any) → None#

Set a header on the response.

Parameters:

key¶ – Header key.
value¶ – Header value.

Returns:

None.

set_etag(etag: str | ETag) → None#

Set an etag header.

Parameters:: etag¶ – An etag value.
Returns:: None

delete_cookie(key: str, path: str = '/', domain: str | None = None) → None#

Delete a cookie.

Parameters:

key¶ – Key of the cookie.
path¶ – Path of the cookie.
domain¶ – Domain of the cookie.

Returns:

None.

render(content: Any, media_type: str, enc_hook: Serializer = <function default_serializer>) → bytes#

Handle the rendering of content into a bytes string.

Returns:: An encoded bytes string

Create an ASGIResponse from a Response instance.

Parameters:

app¶ – The Litestar application instance.
background¶ – Background task(s) to be executed after the response is sent.
cookies¶ – A list of cookies to be set on the response.
encoded_headers¶ – A list of already encoded headers.
headers¶ – Additional headers to be merged with the response headers. Response headers take precedence.
is_head_response¶ – Whether the response is a HEAD response.
media_type¶ – Media type for the response. If media_type is already set on the response, this is ignored.
request¶ – The Request instance.
status_code¶ – Status code for the response. If status_code is already set on the response, this is
type_encoders¶ – A dictionary of type encoders to use for encoding the response content.

Returns:

An ASGIResponse instance.

class litestar.response.ServerSentEvent#

Bases: Stream

Initialize the response.

Parameters:

content¶ – Bytes, string or a sync or async iterator or iterable.
background¶ – A BackgroundTask instance or BackgroundTasks to execute after the response is finished. Defaults to None.
cookies¶ – A list of Cookie instances to be set under the response Set-Cookie header.
encoding¶ – The encoding to be used for the response headers.
headers¶ – A string keyed dictionary of response headers. Header keys are insensitive.
status_code¶ – The response status code. Defaults to 200.
event_type¶ – The type of the SSE event. If given, the browser will sent the event to any ‘event-listener’ declared for it (e.g. via ‘addEventListener’ in JS).
event_id¶ – The event ID. This sets the event source’s ‘last event id’.
retry_duration¶ – Retry duration in milliseconds.
comment_message¶ – A comment message. This value is ignored by clients and is used mostly for pinging.

class litestar.response.ServerSentEventMessage#

Bases: object

__init__(data: str | int | bytes | None = '', event: str | None = None, id: int | str | None = None, retry: int | None = None, comment: str | None = None, sep: str = '\r\n') → None#

class litestar.response.Stream#

Bases: Response[Union[Iterable[Union[str, bytes]], Iterator[Union[str, bytes]], AsyncIterable[Union[str, bytes]], AsyncIterator[Union[str, bytes]]]]

An HTTP response that streams the response data as a series of ASGI http.response.body events.

Initialize the response.

Parameters:

content¶ – A sync or async iterator or iterable.
background¶ – A BackgroundTask instance or BackgroundTasks to execute after the response is finished. Defaults to None.
cookies¶ – A list of Cookie instances to be set under the response Set-Cookie header.
encoding¶ – The encoding to be used for the response headers.
headers¶ – A string keyed dictionary of response headers. Header keys are insensitive.
media_type¶ – A value for the response Content-Type header.
status_code¶ – An HTTP status code.

Create an ASGIStreamingResponse from a StremaingResponse instance.

Parameters:

app¶ – The Litestar application instance.
background¶ – Background task(s) to be executed after the response is sent.
cookies¶ – A list of cookies to be set on the response.
encoded_headers¶ – A list of already encoded headers.
headers¶ – Additional headers to be merged with the response headers. Response headers take precedence.
is_head_response¶ – Whether the response is a HEAD response.
media_type¶ – Media type for the response. If media_type is already set on the response, this is ignored.
request¶ – The Request instance.
status_code¶ – Status code for the response. If status_code is already set on the response, this is
type_encoders¶ – A dictionary of type encoders to use for encoding the response content.

Returns:

An ASGIStreamingResponse instance.

class litestar.response.Template#

Bases: Response[bytes]

Template-based response, rendering a given template into a bytes string.

Handle the rendering of a given template into a bytes string.

Parameters:

template_name¶ – Path-like name for the template to be rendered, e.g. index.html.
template_str¶ – A string representing the template, e.g. tmpl = "Hello <strong>World</strong>".
background¶ – A BackgroundTask instance or BackgroundTasks to execute after the response is finished. Defaults to None.
context¶ – A dictionary of key/value pairs to be passed to the temple engine’s render method.
cookies¶ – A list of Cookie instances to be set under the response Set-Cookie header.
encoding¶ – Content encoding
headers¶ – A string keyed dictionary of response headers. Header keys are insensitive.
media_type¶ – A string or member of the MediaType enum. If not set, try to infer the media type based on the template name. If this fails, fall back to text/plain.
status_code¶ – A value for the response HTTP status code.

create_template_context(request: Request) → dict[str, Any]#

Create a context object for the template.

Parameters:: request¶ – A Request instance.
Returns:: A dictionary holding the template context

Create an ASGIResponse from a Response instance.

Parameters:

app¶ – The Litestar application instance.
background¶ – Background task(s) to be executed after the response is sent.
cookies¶ – A list of cookies to be set on the response.
encoded_headers¶ – A list of already encoded headers.
headers¶ – Additional headers to be merged with the response headers. Response headers take precedence.
is_head_response¶ – Whether the response is a HEAD response.
media_type¶ – Media type for the response. If media_type is already set on the response, this is ignored.
request¶ – The Request instance.
status_code¶ – Status code for the response. If status_code is already set on the response, this is
type_encoders¶ – A dictionary of type encoders to use for encoding the response content.

Returns:

An ASGIResponse instance.