http#

class starlite.handlers.http.HTTPRouteHandler#

Bases: BaseRouteHandler[HTTPRouteHandler]

HTTP Route Decorator.

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

Initialize HTTPRouteHandler.

Parameters:

path – A path fragment for the route handler function or a list 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 starlite.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 dictionary of dependency Provider instances.
etag – An etag header of type ETag that will be added to the response.
exception_handlers – A dictionary that maps handler functions to status codes and/or exception types.
guards – A list 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 list of Middleware.
name – A string identifying the route handler.
opt – A string keyed dictionary of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
response_class – A custom subclass of Response to be used as route handler’s default response.
response_cookies – A list of Cookie instances.
response_headers – A string keyed dictionary mapping ResponseHeader instances.
responses – A dictionary of additional status codes and a description of their expected content. This information will be included in the OpenAPI schema
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_id – An identifier used for the route’s schema operationId. Defaults to the __name__ of the wrapped function.
raises – A list of exception classes extending from starlite.HttpException that is used for the OpenAPI documentation. This list should describe all exceptions raised within the route handler’s function/method. The Starlite 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 list 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 list of string tags that will be appended to the OpenAPI schema.
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.

__call__(fn: AnyCallable) → HTTPRouteHandler#: Replace a function with itself.

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_headers() → Dict[str, Any]#

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

Returns:: A dictionary mapping keys to ResponseHeader instances.

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_before_request() → Optional[Callable[[Any], Union[Any, Awaitable[Any]]]]#

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() → Optional[Callable[[Any], Union[None, Awaitable[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_type_encoders() → Optional[Dict[Any, Callable[[Any], Any]]]#

Resolve type_encoders by merging existing type_encoders from all layers.

Returns:: A TypeEncodersMap to use for this response or None

resolve_response_handler() → Callable[[Any], Awaitable[Callable[[Union[HTTPScope, WebSocketScope], Callable[[...], Awaitable[Union[HTTPRequestEvent, HTTPDisconnectEvent, WebSocketConnectEvent, WebSocketReceiveEvent, WebSocketDisconnectEvent]]], Callable[[Union[HTTPResponseStartEvent, HTTPResponseBodyEvent, HTTPServerPushEvent, HTTPDisconnectEvent, WebSocketAcceptEvent, WebSocketSendEvent, WebSocketResponseStartEvent, WebSocketResponseBodyEvent, WebSocketCloseEvent]], Awaitable[None]]], Awaitable[None]]]]#

Resolve the response_handler function for the route handler.

This method is memoized so the computation occurs only once.

Returns:: Async Callable to handle an HTTP Request

async to_response(app: Starlite, data: Any, plugins: List[PluginProtocol], request: Request) → ASGIApp#

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

Parameters:

app – The Starlite app instance
data – Either an instance of a ResponseContainer, a Response instance or an arbitrary value.
plugins – An optional mapping of plugins
request – A Request instance

Returns:

A Response instance

starlite.handlers.http.route#: alias of HTTPRouteHandler

class starlite.handlers.http.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 list 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 starlite.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 dictionary of dependency Provider instances.
etag – An etag header of type ETag that will be added to the response.
exception_handlers – A dictionary that maps handler functions to status codes and/or exception types.
guards – A list of Guard callables.
media_type – A member of the MediaType enum or a string with a valid IANA Media-Type.
middleware – A list of Middleware.
name – A string identifying the route handler.
opt – A string keyed dictionary of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
response_class – A custom subclass of Response to be used as route handler’s default response.
response_cookies – A list of Cookie instances.
response_headers – A string keyed dictionary mapping ResponseHeader instances.
responses – A dictionary of additional status codes and a description of their expected content. This information will be included in the OpenAPI schema
status_code – An http status code for the response. 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_id – An identifier used for the route’s schema operationId. Defaults to the __name__ of the wrapped function.
raises – A list of exception classes extending from starlite.HttpException that is used for the OpenAPI documentation. This list should describe all exceptions raised within the route handler’s function/method. The Starlite 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 list 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 list of string tags that will be appended to the OpenAPI schema. type_encoders: A mapping of types to callables that transform them into types supported for serialization.
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 starlite.handlers.http.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 list 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 starlite.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 dictionary of dependency Provider instances.
exception_handlers – A dictionary that maps handler functions to status codes and/or exception types.
guards – A list of Guard callables.
media_type – A member of the MediaType enum or a string with a valid IANA Media-Type.
middleware – A list of Middleware.
name – A string identifying the route handler.
opt – A string keyed dictionary of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
response_class – A custom subclass of Response to be used as route handler’s default response.
response_cookies – A list of Cookie instances.
response_headers – A string keyed dictionary mapping ResponseHeader instances.
responses – A dictionary of additional status codes and a description of their expected content. This information will be included in the OpenAPI schema
status_code – An http status code for the response. 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_id – An identifier used for the route’s schema operationId. Defaults to the __name__ of the wrapped function.
raises – A list of exception classes extending from starlite.HttpException that is used for the OpenAPI documentation. This list should describe all exceptions raised within the route handler’s function/method. The Starlite 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 list 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 list of string tags that will be appended to the OpenAPI schema.
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 starlite.handlers.http.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 list 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 starlite.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 dictionary of dependency Provider instances.
etag – An etag header of type ETag that will be added to the response.
exception_handlers – A dictionary that maps handler functions to status codes and/or exception types.
guards – A list of Guard callables.
media_type – A member of the MediaType enum or a string with a valid IANA Media-Type.
middleware – A list of Middleware.
name – A string identifying the route handler.
opt – A string keyed dictionary of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
response_class – A custom subclass of Response to be used as route handler’s default response.
response_cookies – A list of Cookie instances.
response_headers – A string keyed dictionary mapping ResponseHeader instances.
responses – A dictionary of additional status codes and a description of their expected content. This information will be included in the OpenAPI schema
status_code – An http status code for the response. Defaults to 201 for POST.
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_id – An identifier used for the route’s schema operationId. Defaults to the __name__ of the wrapped function.
raises – A list of exception classes extending from starlite.HttpException that is used for the OpenAPI documentation. This list should describe all exceptions raised within the route handler’s function/method. The Starlite 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 list 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 list of string tags that will be appended to the OpenAPI schema.
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 starlite.handlers.http.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 list 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 starlite.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 dictionary of dependency Provider instances.
etag – An etag header of type ETag that will be added to the response.
exception_handlers – A dictionary that maps handler functions to status codes and/or exception types.
guards – A list of Guard callables.
media_type – A member of the MediaType enum or a string with a valid IANA Media-Type.
middleware – A list of Middleware.
name – A string identifying the route handler.
opt – A string keyed dictionary of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
response_class – A custom subclass of Response to be used as route handler’s default response.
response_cookies – A list of Cookie instances.
response_headers – A string keyed dictionary mapping ResponseHeader instances.
responses – A dictionary of additional status codes and a description of their expected content. This information will be included in the OpenAPI schema
status_code – An http status code for the response. 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_id – An identifier used for the route’s schema operationId. Defaults to the __name__ of the wrapped function.
raises – A list of exception classes extending from starlite.HttpException that is used for the OpenAPI documentation. This list should describe all exceptions raised within the route handler’s function/method. The Starlite 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 list 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 list of string tags that will be appended to the OpenAPI schema.
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 starlite.handlers.http.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 list 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 starlite.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 dictionary of dependency Provider instances.
etag – An etag header of type ETag that will be added to the response.
exception_handlers – A dictionary that maps handler functions to status codes and/or exception types.
guards – A list of Guard callables.
media_type – A member of the MediaType enum or a string with a valid IANA Media-Type.
middleware – A list of Middleware.
name – A string identifying the route handler.
opt – A string keyed dictionary of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
response_class – A custom subclass of Response to be used as route handler’s default response.
response_cookies – A list of Cookie instances.
response_headers – A string keyed dictionary mapping ResponseHeader instances.
responses – A dictionary of additional status codes and a description of their expected content. This information will be included in the OpenAPI schema
status_code – An http status code for the response. 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_id – An identifier used for the route’s schema operationId. Defaults to the __name__ of the wrapped function.
raises – A list of exception classes extending from starlite.HttpException that is used for the OpenAPI documentation. This list should describe all exceptions raised within the route handler’s function/method. The Starlite 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 list 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 list of string tags that will be appended to the OpenAPI schema.
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 starlite.handlers.http.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 list 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 starlite.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 dictionary of dependency Provider instances.
etag – An etag header of type ETag that will be added to the response.
exception_handlers – A dictionary that maps handler functions to status codes and/or exception types.
guards – A list of Guard callables.
media_type – A member of the MediaType enum or a string with a valid IANA Media-Type.
middleware – A list of Middleware.
name – A string identifying the route handler.
opt – A string keyed dictionary of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.
response_class – A custom subclass of Response to be used as route handler’s default response.
response_cookies – A list of Cookie instances.
response_headers – A string keyed dictionary mapping ResponseHeader instances.
responses – A dictionary of additional status codes and a description of their expected content. This information will be included in the OpenAPI schema
status_code – An http status code for the response. Defaults to 204.
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_id – An identifier used for the route’s schema operationId. Defaults to the __name__ of the wrapped function.
raises – A list of exception classes extending from starlite.HttpException that is used for the OpenAPI documentation. This list should describe all exceptions raised within the route handler’s function/method. The Starlite 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 list 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 list of string tags that will be appended to the OpenAPI schema.
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.