config#

class litestar.config.allowed_hosts.AllowedHostsConfig#

Bases: object

Configuration for allowed hosts protection.

To enable allowed hosts protection, pass an instance of this class to the Litestar constructor using the allowed_hosts key.

allowed_hosts: list[str]#

A list of trusted hosts.

Use *. to allow all hosts, or prefix domains with *. to allow all sub domains.

exclude: str | list[str] | None = None#

A pattern or list of patterns to skip in the Allowed Hosts middleware.

exclude_opt_key: str | None = None#

An identifier to use on routes to disable hosts check for a particular route.

__init__(allowed_hosts: list[str] = <factory>, exclude: str | list[str] | None = None, exclude_opt_key: str | None = None, scopes: Scopes | None = None, www_redirect: bool = True) None#
scopes: Scopes | None = None#

ASGI scopes processed by the middleware, if None both http and websocket will be processed.

www_redirect: bool = True#

A boolean dictating whether to redirect requests that start with www. and otherwise match a trusted host.

__post_init__() None#

Ensure that the trusted hosts have correct domain wildcards.

class litestar.config.app.AppConfig#

Bases: object

The parameters provided to the Litestar app are used to instantiate an instance, and then the instance is passed to any callbacks registered to on_app_init in the order they are provided.

The final attribute values are used to instantiate the application object.

after_exception: list[AfterExceptionHookHandler]#

An application level exception hook handler or list thereof.

This hook is called after an exception occurs. In difference to exception handlers, it is not meant to return a response - only to process the exception (e.g. log it, send it to Sentry etc.).

after_request: AfterRequestHookHandler | None = None#

A sync or async function executed after the route handler function returned and the response object has been resolved.

Receives the response object which may be any subclass of Response.

after_response: AfterResponseHookHandler | None = None#

A sync or async function called after the response has been awaited. It receives the Request object and should not return any values.

allowed_hosts: list[str] | AllowedHostsConfig | None = None#

If set enables the builtin allowed hosts middleware.

before_request: BeforeRequestHookHandler | None = None#

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.

before_send: list[BeforeMessageSendHookHandler]#

An application level before send hook handler or list thereof.

This hook is called when the ASGI send function is called.

cache_control: CacheControlHeader | None = None#

A cache-control header of type CacheControlHeader to add to route handlers of this app.

Can be overridden by route handlers.

compression_config: CompressionConfig | None = None#

Configures compression behaviour of the application, this enabled a builtin or user defined Compression middleware.

cors_config: CORSConfig | None = None#

If set this enables the builtin CORS middleware.

csrf_config: CSRFConfig | None = None#

If set this enables the builtin CSRF middleware.

debug: bool = False#

If True, app errors rendered as HTML with a stack trace.

dependencies: dict[str, Provide | AnyCallable]#

A string keyed dictionary of dependency Provider instances.

dto: type[AbstractDTO] | None | EmptyType = 0#

AbstractDTO to use for (de)serializing and validation of request data.

etag: ETag | None = None#

An etag header of type ETag to add to route handlers of this app.

Can be overridden by route handlers.

event_emitter_backend#

A subclass of BaseEventEmitterBackend.

alias of SimpleEventEmitter

exception_handlers: ExceptionHandlersMap#

A dictionary that maps handler functions to status codes and/or exception types.

guards: list[Guard]#

A list of Guard callables.

include_in_schema: bool | EmptyType = 0#

A boolean flag dictating whether the route handler should be documented in the OpenAPI schema

lifespan: list[Callable[[Litestar], AbstractAsyncContextManager] | AbstractAsyncContextManager]#

A list of callables returning async context managers, wrapping the lifespan of the ASGI application

listeners: list[EventListener]#

A list of EventListener.

logging_config: BaseLoggingConfig | None = None#

An instance of BaseLoggingConfig subclass.

middleware: list[Middleware]#

A list of Middleware.

on_shutdown: list[LifespanHook]#

A list of LifespanHook called during application shutdown.

on_startup: list[LifespanHook]#

A list of LifespanHook called during application startup.

openapi_config: OpenAPIConfig | None = None#

Defaults to DEFAULT_OPENAPI_CONFIG

opt: dict[str, Any]#

A string keyed dictionary of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.

Can be overridden by routers and router handlers.

__init__(after_exception: list[AfterExceptionHookHandler] = <factory>, after_request: AfterRequestHookHandler | None = None, after_response: AfterResponseHookHandler | None = None, allowed_hosts: list[str] | AllowedHostsConfig | None = None, before_request: BeforeRequestHookHandler | None = None, before_send: list[BeforeMessageSendHookHandler] = <factory>, cache_control: CacheControlHeader | None = None, compression_config: CompressionConfig | None = None, cors_config: CORSConfig | None = None, csrf_config: CSRFConfig | None = None, debug: bool = False, dependencies: dict[str, Provide | AnyCallable] = <factory>, dto: type[AbstractDTO] | None | EmptyType = _EmptyEnum.EMPTY, etag: ETag | None = None, event_emitter_backend: type[BaseEventEmitterBackend] = <class 'litestar.events.emitter.SimpleEventEmitter'>, exception_handlers: ExceptionHandlersMap = <factory>, guards: list[Guard] = <factory>, include_in_schema: bool | EmptyType = _EmptyEnum.EMPTY, lifespan: list[Callable[[Litestar], AbstractAsyncContextManager] | AbstractAsyncContextManager] = <factory>, listeners: list[EventListener] = <factory>, logging_config: BaseLoggingConfig | None = None, middleware: list[Middleware] = <factory>, on_shutdown: list[LifespanHook] = <factory>, on_startup: list[LifespanHook] = <factory>, openapi_config: OpenAPIConfig | None = None, opt: dict[str, Any] = <factory>, parameters: ParametersMap = <factory>, pdb_on_exception: bool = False, plugins: list[PluginProtocol] = <factory>, request_class: type[Request] | None = None, response_class: type[Response] | None = None, response_cookies: ResponseCookies = <factory>, response_headers: ResponseHeaders = <factory>, response_cache_config: ResponseCacheConfig = <factory>, return_dto: type[AbstractDTO] | None | EmptyType = _EmptyEnum.EMPTY, route_handlers: list[ControllerRouterHandler] = <factory>, security: list[SecurityRequirement] = <factory>, signature_namespace: dict[str, Any] = <factory>, signature_types: list[Any] = <factory>, state: State = <factory>, static_files_config: list[StaticFilesConfig] = <factory>, stores: StoreRegistry | dict[str, Store] | None = None, tags: list[str] = <factory>, template_config: TemplateConfigType | None = None, type_encoders: TypeEncodersMap | None = None, type_decoders: TypeDecodersSequence | None = None, websocket_class: type[WebSocket] | None = None, multipart_form_part_limit: int = 1000, experimental_features: list[ExperimentalFeatures] | None = None) None#
parameters: ParametersMap#

A mapping of Parameter definitions available to all application paths.

pdb_on_exception: bool = False#

Drop into the PDB on an exception

plugins: list[PluginProtocol]#

List of SerializationPluginProtocol.

request_class: type[Request] | None = None#

An optional subclass of Request to use for http connections.

response_class: type[Response] | None = None#

A custom subclass of Response to be used as the app’s default response.

response_cookies: ResponseCookies#

A list of Cookie.

response_headers: ResponseHeaders#

A string keyed dictionary mapping ResponseHeader.

response_cache_config: ResponseCacheConfig#

Configures caching behavior of the application.

return_dto: type[AbstractDTO] | None | EmptyType = 0#

AbstractDTO to use for serializing outbound response data.

route_handlers: list[ControllerRouterHandler]#

A required list of route handlers, which can include instances of Router, subclasses of Controller or any function decorated by the route handler decorators.

security: list[SecurityRequirement]#

A list of dictionaries that will be added to the schema of all route handlers in the application. See SecurityRequirement for details.

signature_namespace: dict[str, Any]#

A mapping of names to types for use in forward reference resolution during signature modeling.

signature_types: list[Any]#

A sequence of types for use in forward reference resolution during signature modeling.

These types will be added to the signature namespace using their __name__ attribute.

state: State#

A State <.datastructures.State>` instance holding application state.

static_files_config: list[StaticFilesConfig]#

An instance or list of StaticFilesConfig.

stores: StoreRegistry | dict[str, Store] | None = None#

Central registry of Store to be made available and be used throughout the application. Can be either a dictionary mapping strings to Store instances, or an instance of StoreRegistry.

tags: list[str]#

A list of string tags that will be appended to the schema of all route handlers under the application.

template_config: TemplateConfigType | None = None#

An instance of TemplateConfig.

type_encoders: TypeEncodersMap | None = None#

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

type_decoders: TypeDecodersSequence | None = None#

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

websocket_class: type[WebSocket] | None = None#

An optional subclass of WebSocket to use for websocket connections.

multipart_form_part_limit: int = 1000#

The maximal number of allowed parts in a multipart/formdata request. This limit is intended to protect from DoS attacks.

__post_init__() None#

Normalize the allowed hosts to be a config or None.

Returns:

Optional config.

class litestar.config.app.ExperimentalFeatures#

Bases: str, Enum

__new__(value)#
class litestar.config.compression.CompressionConfig#

Bases: object

Configuration for response compression.

To enable response compression, pass an instance of this class to the Litestar constructor using the compression_config key.

backend: Literal['gzip', 'brotli'] | str#

The backend to use.

If the value given is gzip or brotli, then the builtin gzip and brotli compression is used.

minimum_size: int = 500#

Minimum response size (bytes) to enable compression, affects all backends.

gzip_compress_level: int = 9#

Range [0-9], see gzip — Support for gzip files.

brotli_quality: int = 5#

Range [0-11], Controls the compression-speed vs compression-density tradeoff.

The higher the quality, the slower the compression.

brotli_mode: Literal['generic', 'text', 'font'] = 'text'#

MODE_GENERIC, MODE_TEXT (for UTF-8 format text input, default) or MODE_FONT (for WOFF 2.0).

brotli_lgwin: int = 22#

Base 2 logarithm of size.

Range is 10 to 24. Defaults to 22.

brotli_lgblock: Literal[0, 16, 17, 18, 19, 20, 21, 22, 23, 24] = 0#

Base 2 logarithm of the maximum input block size.

Range is 16 to 24. If set to 0, the value will be set based on the quality. Defaults to 0.

__init__(backend: Literal['gzip', 'brotli'] | str, minimum_size: int = 500, gzip_compress_level: int = 9, brotli_quality: int = 5, brotli_mode: Literal['generic', 'text', 'font'] = 'text', brotli_lgwin: int = 22, brotli_lgblock: Literal[0, 16, 17, 18, 19, 20, 21, 22, 23, 24] = 0, brotli_gzip_fallback: bool = True, middleware_class: type[CompressionMiddleware] = <class 'litestar.middleware.compression.middleware.CompressionMiddleware'>, exclude: str | list[str] | None = None, exclude_opt_key: str | None = None, compression_facade: type[CompressionFacade] = <class 'litestar.middleware.compression.gzip_facade.GzipCompression'>, backend_config: Any = None, gzip_fallback: bool = True) None#
brotli_gzip_fallback: bool = True#

Use GZIP if Brotli is not supported.

middleware_class#

Middleware class to use, should be a subclass of CompressionMiddleware.

alias of CompressionMiddleware

exclude: str | list[str] | None = None#

A pattern or list of patterns to skip in the compression middleware.

exclude_opt_key: str | None = None#

An identifier to use on routes to disable compression for a particular route.

compression_facade#

The compression facade to use for the actual compression.

alias of GzipCompression

backend_config: Any = None#

Configuration specific to the backend.

gzip_fallback: bool = True#

Use GZIP as a fallback if the provided backend is not supported by the client.

class litestar.config.cors.CORSConfig#

Bases: object

Configuration for CORS (Cross-Origin Resource Sharing).

To enable CORS, pass an instance of this class to the Litestar constructor using the ‘cors_config’ key.

allow_origins: list[str]#

List of origins that are allowed.

Can use ‘*’ in any component of the path, e.g. ‘domain.*’. Sets the ‘Access-Control-Allow-Origin’ header.

allow_methods: list[Literal['*'] | Method]#

List of allowed HTTP methods.

Sets the ‘Access-Control-Allow-Methods’ header.

allow_headers: list[str]#

List of allowed headers.

Sets the ‘Access-Control-Allow-Headers’ header.

allow_credentials: bool = False#

Boolean dictating whether or not to set the ‘Access-Control-Allow-Credentials’ header.

allow_origin_regex: str | None = None#

Regex to match origins against.

expose_headers: list[str]#

List of headers that are exposed via the ‘Access-Control-Expose-Headers’ header.

max_age: int = 600#

Response caching TTL in seconds, defaults to 600.

Sets the ‘Access-Control-Max-Age’ header.

__init__(allow_origins: list[str] = <factory>, allow_methods: list[Literal['*'] | Method] = <factory>, allow_headers: list[str] = <factory>, allow_credentials: bool = False, allow_origin_regex: str | None = None, expose_headers: list[str] = <factory>, max_age: int = 600) None#
property allowed_origins_regex: Pattern[str]#

Get or create a compiled regex for allowed origins.

Returns:

A compiled regex of the allowed path.

property is_allow_all_origins: bool#

Get a cached boolean flag dictating whether all origins are allowed.

Returns:

Boolean dictating whether all origins are allowed.

property is_allow_all_methods: bool#

Get a cached boolean flag dictating whether all methods are allowed.

Returns:

Boolean dictating whether all methods are allowed.

property is_allow_all_headers: bool#

Get a cached boolean flag dictating whether all headers are allowed.

Returns:

Boolean dictating whether all headers are allowed.

property preflight_headers: dict[str, str]#

Get cached pre-flight headers.

Returns:

A dictionary of headers to set on the response object.

property simple_headers: dict[str, str]#

Get cached simple headers.

Returns:

A dictionary of headers to set on the response object.

is_origin_allowed(origin: str) bool#

Check whether a given origin is allowed.

Parameters:

origin – An origin header value.

Returns:

Boolean determining whether an origin is allowed.

class litestar.config.csrf.CSRFConfig#

Bases: object

Configuration for CSRF (Cross Site Request Forgery) protection.

To enable CSRF protection, pass an instance of this class to the Litestar constructor using the ‘csrf_config’ key.

secret: str#

A string that is used to create an HMAC to sign the CSRF token.

cookie_name: str = 'csrftoken'#

The CSRF cookie name.

cookie_path: str = '/'#

The CSRF cookie path.

header_name: str = 'x-csrftoken'#

The header that will be expected in each request.

cookie_secure: bool = False#

A boolean value indicating whether to set the Secure attribute on the cookie.

__init__(secret: str, cookie_name: str = 'csrftoken', cookie_path: str = '/', header_name: str = 'x-csrftoken', cookie_secure: bool = False, cookie_httponly: bool = False, cookie_samesite: Literal['lax', 'strict', 'none'] = 'lax', cookie_domain: str | None = None, safe_methods: set[Method] = <factory>, exclude: str | list[str] | None = None, exclude_from_csrf_key: str = 'exclude_from_csrf') None#
cookie_httponly: bool = False#

A boolean value indicating whether to set the HttpOnly attribute on the cookie.

cookie_samesite: Literal['lax', 'strict', 'none'] = 'lax'#

The value to set in the SameSite attribute of the cookie.

cookie_domain: str | None = None#

Specifies which hosts can receive the cookie.

safe_methods: set[Method]#

A set of “safe methods” that can set the cookie.

exclude: str | list[str] | None = None#

A pattern or list of patterns to skip in the CSRF middleware.

exclude_from_csrf_key: str = 'exclude_from_csrf'#

An identifier to use on routes to disable CSRF for a particular route.

class litestar.config.response_cache.ResponseCacheConfig#

Bases: object

Configuration for response caching.

To enable response caching, pass an instance of this class to Litestar using the response_cache_config key.

default_expiration: int | None = 60#

Default cache expiration in seconds used when a route handler is configured with cache=True.

key_builder() str#

CacheKeyBuilder. Defaults to default_cache_key_builder().

__init__(default_expiration: int | None = 60, key_builder: CacheKeyBuilder = <function default_cache_key_builder>, store: str = 'response_cache', cache_response_filter: Callable[[HTTPScope, int], bool] = <function default_do_cache_predicate>) None#
store: str = 'response_cache'#

Name of the Store to use.

cache_response_filter(status_code: int) bool#

A callable that receives connection scope and a status code, and returns a boolean indicating whether the response should be cached.

get_store_from_app(app: Litestar) Store#

Get the store defined in store from an Litestar instance.

litestar.config.response_cache.default_cache_key_builder(request: Request[Any, Any, Any]) str#

Given a request object, returns a cache key by combining the request method and path with the sorted query params.

Parameters:

request – request used to generate cache key.

Returns:

A combination of url path and query parameters

final class litestar.config.response_cache.CACHE_FOREVER#

Bases: object

Sentinel value indicating that a cached response should be stored without an expiration, explicitly skipping the default expiration