router#

class litestar.router.Router#

Bases: object

The Litestar Router class.

A Router instance is used to group controller, routers and route handler functions under a shared path fragment

__init__(path: str, *, after_request: AfterRequestHookHandler | None = None, after_response: AfterResponseHookHandler | None = None, before_request: BeforeRequestHookHandler | None = None, cache_control: CacheControlHeader | None = None, dependencies: Dependencies | None = None, dto: type[AbstractDTO] | None | EmptyType = _EmptyEnum.EMPTY, etag: ETag | None = None, exception_handlers: ExceptionHandlersMap | None = None, guards: Sequence[Guard] | None = None, include_in_schema: bool | EmptyType = _EmptyEnum.EMPTY, middleware: Sequence[Middleware] | None = None, opt: Mapping[str, Any] | None = None, parameters: ParametersMap | None = None, request_class: type[Request] | None = None, response_class: type[Response] | None = None, response_cookies: ResponseCookies | None = None, response_headers: ResponseHeaders | None = None, return_dto: type[AbstractDTO] | None | EmptyType = _EmptyEnum.EMPTY, route_handlers: Sequence[ControllerRouterHandler], security: Sequence[SecurityRequirement] | None = None, signature_namespace: Mapping[str, Any] | None = None, signature_types: Sequence[Any] | None = None, tags: Sequence[str] | None = None, type_decoders: TypeDecodersSequence | None = None, type_encoders: TypeEncodersMap | None = None, websocket_class: type[WebSocket] | None = None, request_max_body_size: int | None | EmptyType = _EmptyEnum.EMPTY) → None#

Initialize a Router.

Parameters:

  • 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.

  • before_request – A sync or async function called immediately before calling the route handler. Receives the litestar.connection.Request instance and any non-None return value is used for the response, bypassing the route handler.

  • cache_control – A cache-control header of type CacheControlHeader to add to route handlers of this router. Can be overridden by route handlers.

  • dependencies – A string keyed mapping of dependency Provide instances.

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

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

  • exception_handlers – A mapping of status codes and/or exception types to handler functions.

  • guards – A sequence of Guard callables.

  • include_in_schema – A boolean flag dictating whether the route handler should be documented in the OpenAPI schema.

  • middleware – A sequence of Middleware.

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

  • parameters – A mapping of Parameter definitions available to all application paths.

  • path – A path fragment that is prefixed to all route handlers, controllers and other routers associated with the router instance.

  • request_class – A custom subclass of Request to be used as the default for all route handlers, controllers and other routers associated with the router instance.

  • request_max_body_size – 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 – A custom subclass of Response to be used as the default for all route handlers, controllers and other routers associated with the router instance.

  • response_cookies – A sequence of Cookie instances.

  • response_headers – A string keyed mapping of ResponseHeader instances.

  • return_dto – AbstractDTO to use for serializing outbound response data.

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

  • security – A sequence of dicts that will be added to the schema of all route handlers in the application. See SecurityRequirement for details.

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

  • signature_types – 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.

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

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

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

  • websocket_class – A custom subclass of WebSocket to be used as the default for all route handlers, controllers and other routers associated with the router instance.

register(value: ControllerRouterHandler) → list[BaseRoute]#

Register a Controller, Route instance or RouteHandler on the router.

Parameters:

value – a subclass or instance of Controller, an instance of Router or a function/method that has been decorated by any of the routing decorators, e.g. get, post.

Returns:

Collection of handlers added to the router.

property route_handler_method_map: dict[str, RouteHandlerMapItem]#

Map route paths to RouteHandlerMapItem

Returns:

A dictionary mapping paths to route handlers

classmethod get_route_handler_map(value: RouteHandlerType | Router) → dict[str, RouteHandlerMapItem]#

Map route handlers to HTTP methods.