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.

parameters: ParametersMap

A mapping of Parameter definitions available to all application paths.

__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>, path: str = '', pdb_on_exception: bool = False, plugins: list[PluginProtocol] = <factory>, request_class: type[Request] | None = None, request_max_body_size: int | None | EmptyType = _EmptyEnum.EMPTY, 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_decoders: TypeDecodersSequence | None = None, type_encoders: TypeEncodersMap | None = None, websocket_class: type[WebSocket] | None = None, multipart_form_part_limit: int = 1000, experimental_features: list[ExperimentalFeatures] | None = None) → None

path: str = ''

A base path that prefixed to all route handlers, controllers and routers associated with the application instance.

New in version 2.8.0.

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.

request_max_body_size: int | None | EmptyType = 0

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: 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_decoders: TypeDecodersSequence | None = None

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

type_encoders: TypeEncodersMap | None = None

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

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