3.x Changelog

3.0.0

Released: 2364-01-27

Features

Remove logging config and related constructsbreaking

Remove Litestar’s logging configuration, and related modules. In particular, the following have been removed:

• Litestar.logging_config parameter

• Litestar.logger attribute

• Litestar.get_logger method

• AppConfig.logging_config attribute

• ASGIConnection.logger property

• litestar.logging module

• litestar.plugins.structlog module

• litestar.middleware.lgging.LoggingMiddlewareConfig class

Aside from debugging, there is only one place where Litestar logs, which is LoggingMiddleware, which has been changed to accept a logger directly. litestar.middleware.lgging.LoggingMiddlewareConfig has also been removed, with LoggingMiddleware now accepting all configuration arguments directly.

Users that have previously relied on Litestar to configure logging, can simply use the standard logging configuration provided by their logging library of choice.

See also

Request logging

References: https://github.com/litestar-org/litestar/issues/2858,, https://github.com/litestar-org/litestar/issues/3913,, https://github.com/litestar-org/litestar/issues/3455, https://github.com/litestar-org/litestar/pull/4615

Remove default exception handler for all unhandled exceptionsbreaking

Remove the default exception handler for all unhandled exceptions. Unhandled exceptions will now be re-raised, for the server to handle. “Unhandled exceptions” in this context means any exception for which no custom exception handler exist, and that does not derive from LitestarException or HTTPException.

Important

Your application’s runtime behaviour won’t change in terms of if exceptions get handled. The main difference will be that, for an unhandled exception, it will be the ASGI server that creates a 500 - Internal Server Error response, instead of Litestar

References: https://github.com/litestar-org/litestar/pull/4610

Remove all SQLAlchemy modules in favor of direct advanced-alchemy importsbreaking

Remove all SQLAlchemy functionality from Litestar. Both litestar.contrib.sqlalchemy and litestar.plugins.sqlalchemy modules have been completely removed. Users must now import directly from advanced_alchemy.extensions.litestar.

Migration: - from litestar.contrib.sqlalchemy import X → from advanced_alchemy.extensions.litestar import X - from litestar.plugins.sqlalchemy import Y → from advanced_alchemy.extensions.litestar import Y

This completes the separation of concerns, with advanced-alchemy being the sole provider of SQLAlchemy integration for Litestar.

References: https://github.com/litestar-org/litestar/pull/4340

Remove deprecated litestar.contrib.prometheus modulebreaking

Remove the deprecated litestar.contrib.prometheus module. Code still using imports from this module should switch to using litestar.plugins.prometheus.

References: https://github.com/litestar-org/litestar/issues/4305, https://github.com/litestar-org/litestar/pull/4328

Make AsyncTestClient async-nativebreaking

Re-implement AsyncTestClient to be async-native, i.e. use the currently running event loop to run the application, instead of running a separate event loop in a new thread. Additionally, a new AsyncWebSocketTestSession has been introduced, providing an async testing utility for WebSockets.

To ensure consisten behaviour across TestClient and AsyncTestClient, all testing utilities have been rewritten to be async first, with their synchronous counterparts proxying calls to the async implementation, which they run internally within a dedicated thread + event loop.

See also

Test Clients Deciding which test client to use

References: https://github.com/litestar-org/litestar/issues/1920, https://github.com/litestar-org/litestar/pull/4291

Remove deprecated plugin properties from Litestarbreaking

Remove deprecated <plugin_type>_plugins properties from Litestar.

Removed	Use instead
Litestar.openapi_schema_plugins	Litestar.plugins.openapi_schema
Litestar.cli_plugins	Litestar.plugins.cli
Litestar.serialization_plugins	Litestar.serialization.cli

References: https://github.com/litestar-org/litestar/pull/4297

Remove deprecated allow_reserved and allow_empty_value property from ResponseHeader and OpenAPIHeaderbreaking

Remove the deprecated properties allow_reserved and allow_empty_value from ResponseHeader and OpenAPIHeader.

References: https://github.com/litestar-org/litestar/pull/4299

Remove deprecated traceback_line_limit parameter of LoggingConfigbreaking

The traceback_line_limit parameter of litestar.logging.config.LoggingConfig has been removed. This parameter had no effect since version 2.9.0, so it can be removed safely from applications without any change in behaviour.

References: https://github.com/litestar-org/litestar/pull/4300

Remove deprecated litestar.middleware.cors modulebreaking

Remove the deprecated litestar.middleware.cors module and litestar.middleware.cors.CORSMiddleware. To configure the CORS middleware, use CORSConfig.

References: https://github.com/litestar-org/litestar/pull/4309

Remove deprecated encoded_headers parameter from ASGI response classes and to_asgi_response methodsbreaking

The deprecated encoded_headers parameter has been removed from the following clases:

• ASGIResponse

• to_asgi_response()

• ASGIFileResponse

• to_asgi_response()

• ASGIRedirectResponse

• to_asgi_response()

• ASGIStreamingResponse

• to_asgi_response()

• to_asgi_response()

Existing code still using encoded_headers should be migrated to using the headers parameter instead.

References: https://github.com/litestar-org/litestar/pull/4311

Remove deprecated litestar.contrib.htmx modulebreaking

Remove the deprecated litestar.contrib.htmx module. Code still using imports from this module should switch to using litestar_htmx.

Install it via litestar[htmx] extra.

References: https://github.com/litestar-org/litestar/issues/4303, https://github.com/litestar-org/litestar/pull/4316

Remove deprecated LitestarTypebreaking

Remove the deprecated litestar.types.internal_types.LitestarType type alias. In its stead, type[Litestar] can be used.

References: https://github.com/litestar-org/litestar/pull/4312

Remove deprecated TemplateContextbreaking

Remove the deprecated litestar.template.base.TemplateContext type. Its usages should be replaced with collections.abc.Mapping.

References: https://github.com/litestar-org/litestar/pull/4313

Remove deprecated ASGIResponse.encoded_headers propertybreaking

Remove the deprecated ASGIResponse.encoded_headers property. Instead, encode_headers() should be used.

References: https://github.com/litestar-org/litestar/pull/4314

Remove deprecated pydantic_get_unwrapped_annotation_and_type_hintsbreaking

Remove the deprecated pydantic_get_unwrapped_annotation_and_type_hints function.

References: https://github.com/litestar-org/litestar/pull/4315

Remove deprecated litestar.contrib.attrs modulebreaking

Remove the deprecated litestar.contrib.attrs module. Code still using imports from this module should switch to using litestar.plugins.attrs.

References: https://github.com/litestar-org/litestar/issues/4302, https://github.com/litestar-org/litestar/pull/4322

Remove deprecated litestar.contrib.jwt modulebreaking

Remove the deprecated litestar.contrib.jwt module. Code still using imports from this module should switch to using litestar.security.jwt.

References: https://github.com/litestar-org/litestar/issues/4304, https://github.com/litestar-org/litestar/pull/4333

Remove deprecated litestar.contrib.repository modulebreaking

Remove the deprecated litestar.contrib.repository module. Code still using imports from this module should switch to using litestar.repository.

References: https://github.com/litestar-org/litestar/issues/4307, https://github.com/litestar-org/litestar/pull/4337

Remove deprecated litestar.contrib.pydantic modulebreaking

Remove the deprecated litestar.contrib.pydantic module. Code still using imports from this module should switch to using litestar.plugins.pydantic.

References: https://github.com/litestar-org/litestar/issues/4306, https://github.com/litestar-org/litestar/pull/4339

Remove deprecated module litestar/contrib/minijnjabreaking

Remove the deprecated module litestar.contrib.minijnja. This module was created with a typo in its name (minijnja instead of minijinja). Instead litestar.contrib.minijinja should be used.

References: https://github.com/litestar-org/litestar/issues/4357, https://github.com/litestar-org/litestar/pull/4357

Add round_trip parameter to PydanticPlugin

New round_trip: bool parameter to PydanticPlugin allows serializing types like pydanctic.Json correctly.

References: https://github.com/litestar-org/litestar/issues/4349, https://github.com/litestar-org/litestar/pull/4350

Remove deprecated litestar.contrib.minijinja.minijinja_from_state functionbreaking

Remove the deprecated litestar.contrib.minijinja.minijinja_from_state function. Instead use a callable that receives the minijinja State object as first argument.

References: https://github.com/litestar-org/litestar/issues/4356, https://github.com/litestar-org/litestar/pull/4355

Remove deprecated litestar.contrib.piccolo modulebreaking

Use litestar[piccolo] extra installation target and litestar_piccolo plugin instead: https://github.com/litestar-org/litestar-piccolo

References: https://github.com/litestar-org/litestar/issues/4364, https://github.com/litestar-org/litestar/pull/4363

Zero cost excluded middlewaresbreaking

Middlewares inheriting from ASGIMiddleware will now have zero runtime cost when they are excluded e.g. via the scope or exclude_opt_key options.

Previously, the base middleware was always being invoked for every request, evaluating the exclusion criteria, and then calling the user defined middleware functions. If a middleware had defined scopes = (ScopeType.HTTP,), it would still be called for every request, regardless of the scope type. Only for requests with the type HTTP, it would then call the user’s function.

Note

This behaviour is still true for the legacy AbstractMiddleware

With zero cost exclusion, the exclusion is being evaluated statically. At app creation time, when route handlers are registered and their middleware stacks are being built, a middleware that is to be excluded will simply not be included in the stack.

Note

Even though this change is marked as breaking, no runtime behaviour difference is expected. Some test cases may break though if they relied on the fact that the middleware wrapper created by ASGIMiddleware was always being called

References:

Support for typing.ReadOnly in typed dict schemas

Support unwrapping ReadOnly type in schemas like:

from typing import ReadOnly, TypedDict

class User(TypedDict):
    id: ReadOnly[int]

typing_extensions.ReadOnly should be used for python versions <3.13.

References: https://github.com/litestar-org/litestar/issues/4423, https://github.com/litestar-org/litestar/pull/4424

Add should_bypass_for_scope to ASGIMiddleware to allow excluding middlewares dynamically

Add a new attribute should_bypass_for_scope; A callable which takes in a Scope and returns a boolean to indicate whether to bypass the middleware for the current request.

References: https://github.com/litestar-org/litestar/pull/4441

Bugfixes

Fix raise_server_exceptions flag in test clients

Fix the raise_server_exceptions. This flag has been non-functional (i.e. did not change the behaviour at all) since version 1. This is now fixed, and unhandled exceptions will be re-raised by the test client

References: https://github.com/litestar-org/litestar/pull/4610

Fix swallowing of unhandled exceptions in WebSocket client

Fix a bug that could lead to unhandled exceptions raised within websocket handlers, and not derived from LitestarException or HTTPException to be silently swallowed. This would lead to a closing of the WebSocket connection without any indication of an exception

References: https://github.com/litestar-org/litestar/pull/4610

Change Optional to NotRequired for pydantic fields with default_factory

Now, in the OpenAPI schema, pydantic fields with default_factory are displayed as non-null and not required. Previously, this fields was nullable and not required.

References: https://github.com/litestar-org/litestar/issues/4294, https://github.com/litestar-org/litestar/pull/4347