What’s changed in 3.0?

This document is an overview of the changes between version 2.11.x and 3.0. For a detailed list of all changes, including changes between versions leading up to the 3.0 release, consult the 3.x Changelog.

Note

The 2.11 release line is unaffected by this change

Imports

2.x	3.x
SECTION
Put your changes here from v2 | Put your changes here from v3

Removal of StaticFileConfig

The StaticFilesConfig has been removed, alongside these related parameters and functions:

• Litestar.static_files_config

• Litestar.url_for_static_asset

• Request.url_for_static_asset

create_static_files_router() is a drop-in replacement for StaticFilesConfig, and can simply be added to the route_handlers like any other regular handler.

Usage of url_for_static_assets should be replaced with a url_for("static", ...) call.

Implicit Optional Default Parameters

In v2, if a handler was typed with an optional parameter it would be implicitly given a default value of None. For example, if the following handler is called with no query parameter, the value None would be passed in to the handler for the param parameter:

@get("/")
def my_handler(param: int | None) -> ...:
    ...

This legacy behavior originates from our history of using Pydantic v1 models to represent handler signatures. In v3, we no longer make this implicit conversion. If you want to have a default value of None for an optional parameter, you must explicitly set it:

@get("/")
def my_handler(param: int | None = None) -> ...:
    ...

OpenAPI Controller Replaced by Plugins

In version 3.0, the OpenAPI controller pattern, deprecated in v2.8, has been removed in favor of a more flexible plugin system.

Elimination of OpenAPIController Subclassing

Previously, users configured elements such as the root path and styling by subclassing OpenAPIController and setting it on the OpenAPIConfig.openapi_controller attribute. As of version 3.0, this pattern has been removed. Instead, users are required to transition to using UI plugins for configuration.

Migration Steps:

1. Remove any implementations subclassing OpenAPIController.

2. Use the OpenAPIConfig.render_plugins attribute to configure the OpenAPI UI made available to your users. If no plugin is supplied, we automatically add the ScalarRenderPlugin for the default configuration.

3. Use the OpenAPIConfig.openapi_router attribute for additional configuration.

See the OpenAPI UI Plugins documentation for more information on how to configure OpenAPI plugins.

Changes to Endpoint Configuration

The OpenAPIConfig.enabled_endpoints attribute is no longer available in version 3.0.0. This attribute previously enabled a set of endpoints that would serve different OpenAPI UIs. In the new version, only the openapi.json endpoint is enabled by default, alongside the Scalar UI plugin as the default.

To adapt to this change, you should explicitly configure any additional endpoints you need by properly setting up the necessary plugins within the OpenAPIConfig.render_plugins parameter.

Modification to root_schema_site Handling

The root_schema_site attribute, which enabled serving a particular UI at the OpenAPI root path, has been removed in version 3.0. The new approach automatically assigns the first OpenAPIRenderPlugin listed in the OpenAPIConfig.render_plugins list to serve at the /schema endpoint, unless a plugin has been defined with the root path (/), in which case that plugin will be used.

For those previously using the root_schema_site attribute, the migration involves ensuring that the UI intended to be served at the /schema endpoint is the first plugin listed in the OpenAPIConfig.render_plugins.

Deprecated app parameter for Response.to_asgi_response has been removed

The parameter app for to_asgi_response() has been removed. If you need access to the app instance inside a custom to_asgi_response method, replace the usages of app with request.app.

Deprecated scope state utilities removed

Litestar has previously made available utilities for storing and retrieving data in the ASGI scope state. These utilities have been removed in version 3.0.0. If you need to store data in the ASGI scope state, you should use do so using a namespace that is unique to your application and unlikely to conflict with other applications.

The following utilities have been removed:

• get_litestar_scope_state

• set_litestar_scope_state

• delete_litestar_scope_state

Deprecated utility function is_sync_or_async_generator removed

The utility function is_sync_or_async_generator has been removed as it is no longer used internally.

If you were relying on this utility, you can define it yourself as follows:

from inspect import isasyncgenfunction, isgeneratorfunction

def is_sync_or_async_generator(obj: Any) -> bool:
    return isgeneratorfunction(obj) or isasyncgenfunction(obj)

Removal of semantic HTTP route handler classes

The semantic HTTPRouteHandler classes have been removed in favour of functional decorators. route, get, post, patch, put, head and delete are now all decorator functions returning HTTPRouteHandler instances.

As a result, customizing the decorators directly is not possible anymore. Instead, to use a route handler decorator with a custom route handler class, the handler_class parameter to the decorator function can be used:

Before:

class my_get_handler(get):
    ... # custom handler

@my_get_handler()
async def handler() -> Any:
    ...

After:

class MyHTTPRouteHandler(HTTPRouteHandler):
    ... # custom handler


@get(handler_class=MyHTTPRouteHandler)
async def handler() -> Any:
    ...

Deprecated app parameter for Response.to_asgi_response has been removed

The parameter app for to_asgi_response() has been removed. If you need access to the app instance inside a custom to_asgi_response method, replace the usages of app with request.app.

Removal of deprecated litestar.middleware.exceptions module and ExceptionHandlerMiddleware

The deprecated litestar.middleware.exceptions module and the ExceptionHandlerMiddleware have been removed. Since ExceptionHandlerMiddleware has been applied automatically behind the scenes if necessary, no action is required.

Update MessagePack media type to application/vnd.msgpack

Change the default media type of MessagePack from application/x-msgpack to the newly introduced official application/vnd.msgpack.

https://www.iana.org/assignments/media-types/application/vnd.msgpack

Deprecated resolve_ methods on route handlers

All resolve_ methods on the route handlers (e.g. HTTPRouteHandler.resolve_response_headers) have been deprecated and will be removed in 4.0. The attributes can now safely be accessed directly (e.g. HTTPRouteHandlers.response_headers).

Moved routing related methods from Router to Litestar

Router now only holds route handlers and configuration, while the actual routing is done in Litestar. With this, several methods and properties have been moved from Router to Litestar:

• route_handler_method_map

• get_route_handler_map

• routes

Removal of CLIPluginProtocol

The Protocol CLIPluginProtocol has been removed in favour of the abstract CLIPluginProtocol. The functionality and interface remain the same, the only difference being that plugins that wish to provide this functionality are now required to inherit from CLIPlugin.

Removal of OpenAPISchemaPluginProtocol

The Protocol OpenAPISchemaPluginProtocol has been removed in favour of the abstract OpenAPISchemaPlugin. The functionality and interface remain the same, the only difference being that plugins that wish to provide this functionality are now required to inherit from OpenAPISchemaPlugin.

Dropped support for starlette middleware protocol

The starlette middleware protocol is no longer supported.

Only the “factory” pattern will now be supported, i.e. a callable that receives an ASGI callable as its only argument and returns another ASGI callable:

def middleware(app: ASGIApp) -> ASGIApp:
    ...

See also

Middleware

Removal of SerializationPluginProtocol

The Protocol SerializationPluginProtocol has been removed in favour of the abstract SerializationPlugin. The functionality and interface remain the same, the only difference being that plugins that wish to provide this functionality are now required to inherit from SerializationPlugin.

Removal of body in streaming responses

The unsupported body parameter of ASGIStreamingResponse and ASGIFileResponse has been removed.

This does not change any behaviour, as this parameter was previously ignored.

polyfactory package removed from default dependencies

The polyfactory library has been moved from the default dependencies to the litestar[polyfactory] package extra. It is also included in litestar[full].

pyyaml package removed from default dependencies

The PyYAML library, used to render the OpenAPI schema as YAML has been moved from the default dependencies to the litestar[yaml] package extra.

litestar-htmx package removed from default dependencies

The litestar-htmx package powering the HTMX plugin has been moved to the litestar[htmx] extra.

Improved file system handling / fsspec integration

A more coherent file system integration was added, with improved support for fsspec. This new implementation is more stable, performant and consistent, and includes new features such as random access to all supported file systems as well as streaming (optionally with offsets, even if the underlying file system does not support it natively).

See also

File Systems

Removal of resolve_symlinks parameter to create_static_files_router

resolve_symlinks parameter of create_static_files_router() has been removed in favour of the new allow_symlinks_outside_directory parameter.

Attention

This has been intentionally made a breaking change because the new parameter has slightly different behaviour and defaults to False instead of True.

Middleware configuration constraints

ASGIMiddlewares can now express constraints for how they are applied in the middleware stack, which are then validated on application startup.

See also

Configuration constraints