Application and Routing

class Litestar:
    def __init__(
        self,
        route_handlers: Sequence[ControllerRouterHandler] | None = None,
        *,
        middleware: Sequence[Middleware] | None = None,
        dependencies: Dependencies | None = None,
        exception_handlers: ExceptionHandlersMap | None = None,
        on_app_init: Sequence[OnAppInitHandler] | None = None,
        listeners: Sequence[EventListener] | None = None,
        lifespan: Sequence[Callable[[], AsyncContextManager | ContextManager]] | None = None,
        after_exception: Sequence[AfterExceptionHookHandler] | None = None,
        after_request: AfterRequestHookHandler | None = None,
        after_response: AfterResponseHookHandler | None = None,
        before_request: BeforeRequestHookHandler | None = None,
        before_send: Sequence[BeforeMessageSendHookHandler] | None = None,
        cors_config: CORSConfig | None = None,
        csrf_config: CSRFConfig | None = None,
        allowed_hosts: AllowedHostsConfig | None = None,
        compression_config: CompressionConfig | None = None,
        cache_config: CacheConfig | None = None,
        etag: ETagConfig | None = None,
        static_files_config: Sequence[StaticFilesConfig] | None = None,
        template_config: TemplateConfig | None = None,
        openapi_config: OpenAPIConfig | None = None,
        logging_config: BaseLoggingConfig | None = None,
        state: State | None = None,
        debug: bool = False,
        pdb_on_exception: bool = False,
        plugins: Sequence[PluginProtocol] | None = None,
        request_class: type[Request] | None = None,
        response_class: type[Response] | None = None,
        websocket_class: type[WebSocket] | None = None,
        dto: type[AbstractDTO] | None = None,
        return_dto: type[AbstractDTO] | None = None,
        signature_namespace: dict[str, Any] | None = None,
        type_encoders: TypeEncodersMap | None = None,
        multipart_form_part_limit: int = 1000,
        experimental_features: list[ExperimentalFeatures] | None = None,
    ):
        """
        Create a Litestar application.

        Parameters:
        - route_handlers: A sequence containing Router, Controller, or route handler instances
        - middleware: A sequence of Middleware to apply to the application
        - dependencies: A dictionary of dependency providers
        - exception_handlers: A dictionary mapping exception types to handlers
        - on_app_init: A sequence of callables to invoke during application initialization
        - listeners: A sequence of event listeners
        - lifespan: A sequence of lifespan context managers
        - after_exception: A sequence of hooks called after exceptions
        - after_request: A hook called after processing requests
        - after_response: A hook called after sending responses
        - before_request: A hook called before processing requests
        - before_send: A sequence of hooks called before sending responses
        - cors_config: CORS configuration
        - csrf_config: CSRF protection configuration
        - allowed_hosts: Allowed hosts configuration
        - compression_config: Response compression configuration
        - cache_config: Response caching configuration
        - etag: ETag configuration
        - static_files_config: Static files serving configuration
        - template_config: Template engine configuration
        - openapi_config: OpenAPI documentation configuration
        - logging_config: Logging configuration
        - state: Application state
        - debug: Enable debug mode
        - pdb_on_exception: Drop into debugger on exceptions
        - plugins: A sequence of plugin instances
        - request_class: Custom Request class
        - response_class: Custom Response class
        - websocket_class: Custom WebSocket class
        - dto: Default DTO for request/response serialization
        - return_dto: Default DTO for response serialization
        - signature_namespace: Additional namespace for signature inspection
        - type_encoders: Custom type encoders
        - multipart_form_part_limit: Limit for multipart form parts
        - experimental_features: List of experimental features to enable
        """

    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
        """ASGI application entry point."""
        
    @property
    def routes(self) -> list[ASGIRoute]:
        """Get all registered routes."""
        
    @property
    def route_map(self) -> dict[str, list[Route]]:
        """Get mapping of paths to routes."""
        
    def url_for(self, name: str, **path_parameters: Any) -> str:
        """Generate URL for named route."""
        
    def url_for_static_asset(self, name: str, file_path: str) -> str:
        """Generate URL for static asset."""

class Router:
    def __init__(
        self,
        path: str = "",
        route_handlers: Sequence[ControllerRouterHandler] | None = None,
        *,
        dependencies: Dependencies | None = None,
        middleware: Sequence[Middleware] | None = None,
        exception_handlers: ExceptionHandlersMap | None = None,
        after_request: AfterRequestHookHandler | None = None,
        after_response: AfterResponseHookHandler | None = None,
        before_request: BeforeRequestHookHandler | None = None,
        dto: type[AbstractDTO] | None = None,
        return_dto: type[AbstractDTO] | None = None,
        signature_namespace: dict[str, Any] | None = None,
        include_in_schema: bool = True,
        tags: Sequence[str] | None = None,
        guards: Sequence[Guard] | None = None,
        opt: dict[str, Any] | None = None,
    ):
        """
        Create a Router for organizing route handlers.

        Parameters:
        - path: Base path for all routes in this router
        - route_handlers: Sequence of route handlers, controllers, or nested routers
        - dependencies: Dictionary of dependency providers
        - middleware: Sequence of middleware to apply
        - exception_handlers: Exception handler mapping
        - after_request: Hook called after request processing
        - after_response: Hook called after response sending
        - before_request: Hook called before request processing
        - dto: Default DTO for request/response serialization
        - return_dto: Default DTO for response serialization
        - signature_namespace: Additional namespace for signature inspection
        - include_in_schema: Whether to include routes in OpenAPI schema
        - tags: OpenAPI tags for routes
        - guards: Route guards for authorization
        - opt: Arbitrary options dictionary
        """

    @property
    def routes(self) -> list[BaseRoute]:
        """Get all routes registered with this router."""
        
    def register(self, handler: ControllerRouterHandler) -> None:
        """Register a route handler, controller, or router."""

class Controller:
    path: str = ""
    dependencies: Dependencies | None = None
    middleware: Sequence[Middleware] | None = None
    exception_handlers: ExceptionHandlersMap | None = None
    after_request: AfterRequestHookHandler | None = None
    after_response: AfterResponseHookHandler | None = None
    before_request: BeforeRequestHookHandler | None = None
    dto: type[AbstractDTO] | None = None
    return_dto: type[AbstractDTO] | None = None
    signature_namespace: dict[str, Any] | None = None
    include_in_schema: bool = True
    tags: Sequence[str] | None = None
    guards: Sequence[Guard] | None = None
    opt: dict[str, Any] | None = None
    
    def __init_subclass__(cls, **kwargs: Any) -> None:
        """Initialize controller subclass and register route handlers."""
        
    @classmethod
    def get_route_handlers(cls) -> list[BaseRouteHandler]:
        """Get all route handlers defined on this controller."""

def create_route_handler(
    handler_function: AnyCallable,
    *,
    http_method: HttpMethod | str,
    path: str | None = None,
    **kwargs: Any,
) -> HTTPRouteHandler:
    """Create a route handler from a function and HTTP method."""

def get_route_handlers(obj: Any) -> list[BaseRouteHandler]:
    """Extract route handlers from an object (controller, module, etc.)."""

from litestar import Litestar, get

@get("/health")
def health_check() -> dict[str, str]:
    return {"status": "healthy"}

app = Litestar(route_handlers=[health_check])

from litestar import Litestar, Router, get

@get("/users")
def list_users() -> list[dict]:
    return [{"id": 1, "name": "Alice"}]

@get("/users/{user_id:int}")
def get_user(user_id: int) -> dict:
    return {"id": user_id, "name": "Alice"}

# Group related routes under a router
api_router = Router(
    path="/api/v1",
    route_handlers=[list_users, get_user]
)

app = Litestar(route_handlers=[api_router])

from litestar import Controller, get, post
from litestar.dto import DataclassDTO
from dataclasses import dataclass

@dataclass
class User:
    id: int
    name: str
    email: str

class UserController(Controller):
    path = "/users"
    tags = ["users"]
    
    @get("/")
    async def list_users(self) -> list[User]:
        return [User(id=1, name="Alice", email="alice@example.com")]
    
    @get("/{user_id:int}")
    async def get_user(self, user_id: int) -> User:
        return User(id=user_id, name="Alice", email="alice@example.com")
    
    @post("/", dto=DataclassDTO[User])
    async def create_user(self, data: User) -> User:
        # Process user creation
        return data

app = Litestar(route_handlers=[UserController])

from litestar import Litestar, Router, Controller, get

class UserController(Controller):
    path = "/users"
    
    @get("/")
    def list_users(self) -> list[dict]:
        return []

class AdminController(Controller):
    path = "/admin"
    
    @get("/dashboard")
    def dashboard(self) -> dict:
        return {"status": "admin"}

# Nest controllers under routers
api_v1 = Router(path="/api/v1", route_handlers=[UserController])
admin_router = Router(path="/admin", route_handlers=[AdminController])

app = Litestar(route_handlers=[api_v1, admin_router])
# Creates routes: /api/v1/users, /admin/admin/dashboard

# Type aliases for route handlers
ControllerRouterHandler = Controller | Router | BaseRouteHandler

# Dependency injection types
Dependencies = dict[str, Provide]

# Hook handler types
OnAppInitHandler = Callable[[AppConfig], AppConfig]
AfterRequestHookHandler = Callable[[Request], None]
AfterResponseHookHandler = Callable[[Request, Response], None]
BeforeRequestHookHandler = Callable[[Request], None]
BeforeMessageSendHookHandler = Callable[[Message, Scope], None]
AfterExceptionHookHandler = Callable[[Request, Exception], None]

# Exception handling
ExceptionHandlersMap = dict[type[Exception], ExceptionHandler]
ExceptionHandler = Callable[[Request, Exception], Response]

# Middleware
Middleware = Callable | DefineMiddleware | type[AbstractMiddleware]