Claude Cursor opencode Skill

litestar

Use when working with Litestar, Controller, Router, @get/@post, FromPath, MsgspecDTO, OpenAPIConfig, Provide, FromDishka, Guard, ASGIMiddleware, HTTPException, ChannelsPlugin, or WebSocket. Not for standalone libs.

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download litestar-org-litestar-skills-skills_litestar-669a363.zip · 103 KB

Install

skills CLI npx skills add https://github.com/litestar-org/litestar-skills/tree/main/skills/litestar
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install litestar-org-litestar-skills@llmmart
Git git clone https://github.com/litestar-org/litestar-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole litestar-org/litestar-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Litestar Core Framework & Ecosystem Hub

Use this skill for all core Litestar framework subsystems (application composition, routing, controllers, parameters, DTOs, OpenAPI, dependency injection, Dishka integration, authentication/guards, middleware, exception handling, plugin protocols, WebSockets, Channels/SSE, typed settings, and CRUD data services/pagination) and to route to standalone Litestar ecosystem skills.

This guidance targets the released Litestar 2.25.0 contract. Do not copy unreleased main APIs into consumer examples.

Code Style Rules

  • Prefer first-party Litestar ecosystem packages (litestar-granian, advanced-alchemy, sqlspec, msgspec, litestar-saq, litestar-queues, litestar-vite, litestar-autowire, litestar-security, litestar-email, litestar-mcp, litestar-htmx) and match the project's existing stack.
  • Keep Litestar(...) app setup and route handlers thin: group domain routes into Controller / Router hierarchies, and centralize application wiring in create_app() -> Litestar.
  • Use explicit parameter and body annotations (FromPath, FromQuery, JSONBody, NamedDependency). Avoid untyped reserved kwargs (such as data: MyDTO without a body marker) and deprecated litestar.params.Dependency.
  • Define explicit msgspec.Struct (camelCase wire format via rename="camel") or DTO boundary contracts (dto and return_dto) on routes and controllers; never expose raw ORM models directly without a write-safe DTO.
  • Enforce authentication via middleware or litestar-security, and enforce authorization in Guard functions or security decorators — never inside route handler bodies.
  • Prefer built-in middleware configs (CORSConfig, CSRFConfig, AllowedHostsConfig, RateLimitConfig, CompressionConfig) over custom middleware.
  • Raise domain-specific exceptions in services and map them to HTTP responses in exception_handlers.
  • Use async I/O for all request handlers, WebSocket/SSE streams, service methods, stores, and external clients.

Quick Reference

Core Framework Subsystems (This Skill)

Subsystem Key Symbols / Patterns Reference
App Composition & Lifecycle Litestar(...), AppConfig, ApplicationCore, lifespan, State, ImmutableState, 2.22–2.25 contracts app-and-lifecycle.md
CLI & Project Config Autodiscovery, LITESTAR_* env vars, litestar run/info/routes/schema/sessions, CLIPlugin, litestar.toml cli-and-config.md
Route Handlers & Controllers @get/@post/@put/@patch/@delete, Controller, Router, layered config inheritance handlers.md
Parameters & Request Bodies FromPath, FromQuery, FromHeader, FromCookie, JSONBody, RequestBody, MsgPackBody, MultipartBody, URLEncodedBody, RawBody, QueryParams, RequestCookies, UploadFile parameters.md
Domain Package Layout domains/<name>/ structure, sub-controllers, full-stack domain wiring layout.md
DTOs & Boundary Contracts MsgspecDTO, SQLAlchemyDTO, DataclassDTO, PydanticDTO, DTOConfig, DTOData[T], DTOField, Mark dtos.md
OpenAPI & Schema UI OpenAPIConfig, Scalar/Swagger/Redoc/Stoplight/RapiDoc plugins, ResponseSpec, Operation, security schemes openapi.md
Dependency Injection & Dishka Provide, NamedDependency[T], SkipValidation[T], generator cleanup, FromDishka[T], setup_dishka di-and-dishka.md
Authentication & Guards Guard callables, ASGIConnection, JWTAuth, JWTCookieAuth, SessionAuth, OAuth2, RBAC & tenant guards auth-and-guards.md
Middleware & HTTP Security ASGIMiddleware, DefineMiddleware, CORSConfig, CSRFConfig, AllowedHostsConfig, CompressionConfig, RateLimitConfig middleware.md
Exceptions & Problem Details HTTPException hierarchy, ApplicationError mapping, exception_handlers, after_exception, RFC 9457 exceptions.md
Plugin Protocols InitPlugin, CLIPluginProtocol, SerializationPluginProtocol, OpenAPISchemaPluginProtocol, DIPlugin, PydanticPlugin plugins.md
WebSockets @websocket, WebSocket lifecycle, @websocket_listener, @websocket_stream, WS Dishka DI, WS guards, stream_pubsub websockets.md
Channels & Server-Sent Events ChannelsPlugin (Memory, Redis, AsyncPg, PsycoPg, SQLSpec), ServerSentEvent, Stream, RealtimeEvent, RealtimePublisher channels-and-sse.md
Typed Settings & Env Config dataclass + get_env vs pydantic-settings, @lru_cache factories, plugin config builders settings.md
Filters & Pagination create_filter_dependencies, FilterTypes, OffsetPagination, ClassicPagination, cursor pagination, custom search filters-and-pagination.md
Data Services & Repositories SQLAlchemyAsyncRepositoryService (advanced-alchemy) and SQLSpecAsyncService (sqlspec) CRUD services services-and-repos.md
Logging & Observability LoggingConfig, StructlogPlugin, OpenTelemetryPlugin, PrometheusConfig, PrometheusController logging-and-observability.md
Stores & Response Caching StoreRegistry, MemoryStore, FileStore, RedisStore, ValkeyStore, ResponseCacheConfig stores-and-caching.md

Standalone Ecosystem Skills

Task Skill
Convention-based domain-package discovery (AutowirePlugin, domain_packages) litestar-autowire
msgspec.Struct, Meta, tagged unions, JSON/MsgPack encode/decode hooks msgspec
SecurityPlugin, CurrentUser, Principal, @requires_role/@requires_scope/@requires_tenant litestar-security
SQLAlchemy ORM models, SQLAlchemyPlugin, Alembic migrations, repositories advanced-alchemy
SQL-first drivers, SQLFileLoader, query builders, ADK stores, data dictionary sqlspec
Vite asset pipeline, HMR, TypeGen, SPA/hybrid modes, and Inertia.js (InertiaConfig, component=) litestar-vite
Server-rendered HTMX requests, partial templates, HX-* response helpers litestar-htmx
Redis-backed background workers, queues, cron schedules (litestar-saq) litestar-saq
SQL/memory task queues, @task, QueueService, workers (litestar-queues) litestar-queues
Transactional email (EmailPlugin, SMTP/Resend/SendGrid/Mailgun/SES backends) litestar-email
Model Context Protocol servers and agent runtimes (LitestarMCP, SkillController, AgentRuntime) litestar-mcp
Granian ASGI server plugin, runtime threads, HTTP/2, TLS, static mounts litestar-granian
TestClient, AsyncTestClient, create_async_test_client, handler/DI/Guard tests litestar-testing
Typed test data factories (MsgspecFactory, ModelFactory, DataclassFactory) polyfactory
Docker database/service fixtures for integration tests (pytest-databases) pytest-databases
Wheels, PyApp standalone binaries, GitHub release matrices (litestar-build) litestar-build
Containers, Cloud Run, GKE, Kubernetes, systemd, runtime servers (litestar-deployment) litestar-deployment
Python/TypeScript/Litestar code style, linting, typing, and quality gates litestar-styleguide

References Index

Official References

Shared Styleguide Baseline

Files (litestar-skills)
  • references
    • app-and-lifecycle.md 14.3 KB
      Loading…
    • auth-and-guards.md 24.8 KB
      Loading…
    • channels-and-sse.md 29.6 KB
      Loading…
    • cli-and-config.md 6.1 KB
      Loading…
    • di-and-dishka.md 17.4 KB
      Loading…
    • dtos.md 16.1 KB
      Loading…
    • exceptions.md 15.9 KB
      Loading…
    • filters-and-pagination.md 17.3 KB
      Loading…
    • handlers.md 10.6 KB
      Loading…
    • layout.md 11 KB
      Loading…
    • logging-and-observability.md 6.1 KB
      Loading…
    • middleware.md 20.1 KB
      Loading…
    • openapi.md 14.2 KB
      Loading…
    • parameters.md 7.8 KB
      Loading…
    • plugins.md 18.8 KB
      Loading…
    • services-and-repos.md 22.4 KB
      Loading…
    • settings.md 19 KB
      Loading…
    • stores-and-caching.md 5.5 KB
      Loading…
    • websockets.md 23.5 KB
      Loading…
  • SKILL.md 19.6 KB
    ---
    name: litestar
    description: "Use when working with Litestar, Controller, Router, @get/@post, FromPath, MsgspecDTO, OpenAPIConfig, Provide, FromDishka, Guard, ASGIMiddleware, HTTPException, ChannelsPlugin, or WebSocket. Not for standalone libs."
    ---
    
    # Litestar Core Framework & Ecosystem Hub
    
    Use this skill for all core **Litestar** framework subsystems (application composition, routing, controllers, parameters, DTOs, OpenAPI, dependency injection, Dishka integration, authentication/guards, middleware, exception handling, plugin protocols, WebSockets, Channels/SSE, typed settings, and CRUD data services/pagination) and to route to standalone Litestar ecosystem skills.
    
    This guidance targets the released Litestar 2.25.0 contract. Do not copy unreleased `main` APIs into consumer examples.
    
    ## Code Style Rules
    
    - Prefer first-party Litestar ecosystem packages (`litestar-granian`, `advanced-alchemy`, `sqlspec`, `msgspec`, `litestar-saq`, `litestar-queues`, `litestar-vite`, `litestar-autowire`, `litestar-security`, `litestar-email`, `litestar-mcp`, `litestar-htmx`) and match the project's existing stack.
    - Keep `Litestar(...)` app setup and route handlers thin: group domain routes into `Controller` / `Router` hierarchies, and centralize application wiring in `create_app() -> Litestar`.
    - Use explicit parameter and body annotations (`FromPath`, `FromQuery`, `JSONBody`, `NamedDependency`). Avoid untyped reserved kwargs (such as `data: MyDTO` without a body marker) and deprecated `litestar.params.Dependency`.
    - Define explicit `msgspec.Struct` (camelCase wire format via `rename="camel"`) or DTO boundary contracts (`dto` and `return_dto`) on routes and controllers; never expose raw ORM models directly without a write-safe DTO.
    - Enforce authentication via middleware or `litestar-security`, and enforce authorization in `Guard` functions or security decorators — never inside route handler bodies.
    - Prefer built-in middleware configs (`CORSConfig`, `CSRFConfig`, `AllowedHostsConfig`, `RateLimitConfig`, `CompressionConfig`) over custom middleware.
    - Raise domain-specific exceptions in services and map them to HTTP responses in `exception_handlers`.
    - Use async I/O for all request handlers, WebSocket/SSE streams, service methods, stores, and external clients.
    
    ## Quick Reference
    
    ### Core Framework Subsystems (This Skill)
    
    | Subsystem | Key Symbols / Patterns | Reference |
    | --- | --- | --- |
    | App Composition & Lifecycle | `Litestar(...)`, `AppConfig`, `ApplicationCore`, `lifespan`, `State`, `ImmutableState`, 2.22–2.25 contracts | [app-and-lifecycle.md](references/app-and-lifecycle.md) |
    | CLI & Project Config | Autodiscovery, `LITESTAR_*` env vars, `litestar run`/`info`/`routes`/`schema`/`sessions`, `CLIPlugin`, `litestar.toml` | [cli-and-config.md](references/cli-and-config.md) |
    | Route Handlers & Controllers | `@get`/`@post`/`@put`/`@patch`/`@delete`, `Controller`, `Router`, layered config inheritance | [handlers.md](references/handlers.md) |
    | Parameters & Request Bodies | `FromPath`, `FromQuery`, `FromHeader`, `FromCookie`, `JSONBody`, `RequestBody`, `MsgPackBody`, `MultipartBody`, `URLEncodedBody`, `RawBody`, `QueryParams`, `RequestCookies`, `UploadFile` | [parameters.md](references/parameters.md) |
    | Domain Package Layout | `domains/<name>/` structure, sub-controllers, full-stack domain wiring | [layout.md](references/layout.md) |
    | DTOs & Boundary Contracts | `MsgspecDTO`, `SQLAlchemyDTO`, `DataclassDTO`, `PydanticDTO`, `DTOConfig`, `DTOData[T]`, `DTOField`, `Mark` | [dtos.md](references/dtos.md) |
    | OpenAPI & Schema UI | `OpenAPIConfig`, Scalar/Swagger/Redoc/Stoplight/RapiDoc plugins, `ResponseSpec`, `Operation`, security schemes | [openapi.md](references/openapi.md) |
    | Dependency Injection & Dishka | `Provide`, `NamedDependency[T]`, `SkipValidation[T]`, generator cleanup, `FromDishka[T]`, `setup_dishka` | [di-and-dishka.md](references/di-and-dishka.md) |
    | Authentication & Guards | `Guard` callables, `ASGIConnection`, `JWTAuth`, `JWTCookieAuth`, `SessionAuth`, OAuth2, RBAC & tenant guards | [auth-and-guards.md](references/auth-and-guards.md) |
    | Middleware & HTTP Security | `ASGIMiddleware`, `DefineMiddleware`, `CORSConfig`, `CSRFConfig`, `AllowedHostsConfig`, `CompressionConfig`, `RateLimitConfig` | [middleware.md](references/middleware.md) |
    | Exceptions & Problem Details | `HTTPException` hierarchy, `ApplicationError` mapping, `exception_handlers`, `after_exception`, RFC 9457 | [exceptions.md](references/exceptions.md) |
    | Plugin Protocols | `InitPlugin`, `CLIPluginProtocol`, `SerializationPluginProtocol`, `OpenAPISchemaPluginProtocol`, `DIPlugin`, `PydanticPlugin` | [plugins.md](references/plugins.md) |
    | WebSockets | `@websocket`, `WebSocket` lifecycle, `@websocket_listener`, `@websocket_stream`, WS Dishka DI, WS guards, `stream_pubsub` | [websockets.md](references/websockets.md) |
    | Channels & Server-Sent Events | `ChannelsPlugin` (`Memory`, `Redis`, `AsyncPg`, `PsycoPg`, `SQLSpec`), `ServerSentEvent`, `Stream`, `RealtimeEvent`, `RealtimePublisher` | [channels-and-sse.md](references/channels-and-sse.md) |
    | Typed Settings & Env Config | `dataclass` + `get_env` vs `pydantic-settings`, `@lru_cache` factories, plugin config builders | [settings.md](references/settings.md) |
    | Filters & Pagination | `create_filter_dependencies`, `FilterTypes`, `OffsetPagination`, `ClassicPagination`, cursor pagination, custom search | [filters-and-pagination.md](references/filters-and-pagination.md) |
    | Data Services & Repositories | `SQLAlchemyAsyncRepositoryService` (`advanced-alchemy`) and `SQLSpecAsyncService` (`sqlspec`) CRUD services | [services-and-repos.md](references/services-and-repos.md) |
    | Logging & Observability | `LoggingConfig`, `StructlogPlugin`, `OpenTelemetryPlugin`, `PrometheusConfig`, `PrometheusController` | [logging-and-observability.md](references/logging-and-observability.md) |
    | Stores & Response Caching | `StoreRegistry`, `MemoryStore`, `FileStore`, `RedisStore`, `ValkeyStore`, `ResponseCacheConfig` | [stores-and-caching.md](references/stores-and-caching.md) |
    
    ### Standalone Ecosystem Skills
    
    | Task | Skill |
    | --- | --- |
    | Convention-based domain-package discovery (`AutowirePlugin`, `domain_packages`) | [litestar-autowire](../litestar-autowire/SKILL.md) |
    | `msgspec.Struct`, `Meta`, tagged unions, JSON/MsgPack encode/decode hooks | [msgspec](../msgspec/SKILL.md) |
    | `SecurityPlugin`, `CurrentUser`, `Principal`, `@requires_role`/`@requires_scope`/`@requires_tenant` | [litestar-security](../litestar-security/SKILL.md) |
    | SQLAlchemy ORM models, `SQLAlchemyPlugin`, Alembic migrations, repositories | [advanced-alchemy](../advanced-alchemy/SKILL.md) |
    | SQL-first drivers, `SQLFileLoader`, query builders, ADK stores, data dictionary | [sqlspec](../sqlspec/SKILL.md) |
    | Vite asset pipeline, HMR, TypeGen, SPA/hybrid modes, and Inertia.js (`InertiaConfig`, `component=`) | [litestar-vite](../litestar-vite/SKILL.md) |
    | Server-rendered HTMX requests, partial templates, `HX-*` response helpers | [litestar-htmx](../litestar-htmx/SKILL.md) |
    | Redis-backed background workers, queues, cron schedules (`litestar-saq`) | [litestar-saq](../litestar-saq/SKILL.md) |
    | SQL/memory task queues, `@task`, `QueueService`, workers (`litestar-queues`) | [litestar-queues](../litestar-queues/SKILL.md) |
    | Transactional email (`EmailPlugin`, SMTP/Resend/SendGrid/Mailgun/SES backends) | [litestar-email](../litestar-email/SKILL.md) |
    | Model Context Protocol servers and agent runtimes (`LitestarMCP`, `SkillController`, `AgentRuntime`) | [litestar-mcp](../litestar-mcp/SKILL.md) |
    | Granian ASGI server plugin, runtime threads, HTTP/2, TLS, static mounts | [litestar-granian](../litestar-granian/SKILL.md) |
    | `TestClient`, `AsyncTestClient`, `create_async_test_client`, handler/DI/Guard tests | [litestar-testing](../litestar-testing/SKILL.md) |
    | Typed test data factories (`MsgspecFactory`, `ModelFactory`, `DataclassFactory`) | [polyfactory](../polyfactory/SKILL.md) |
    | Docker database/service fixtures for integration tests (`pytest-databases`) | [pytest-databases](../pytest-databases/SKILL.md) |
    | Wheels, PyApp standalone binaries, GitHub release matrices (`litestar-build`) | [litestar-build](../litestar-build/SKILL.md) |
    | Containers, Cloud Run, GKE, Kubernetes, systemd, runtime servers (`litestar-deployment`) | [litestar-deployment](../litestar-deployment/SKILL.md) |
    | Python/TypeScript/Litestar code style, linting, typing, and quality gates | [litestar-styleguide](../litestar-styleguide/SKILL.md) |
    
    <workflow>
    
    ## Workflow
    
    1. **Detect the project stack first**: inspect `pyproject.toml`, `litestar.toml`, existing domain packages, DI setup (`Provide` vs `Dishka`), data layer (`advanced-alchemy` vs `sqlspec`), settings (`dataclass` vs `pydantic-settings`), and auth (`JWTAuth`/`SessionAuth` vs `litestar-security`).
    2. **Open the matching core reference** in `references/*.md` for any Litestar framework concern:
       - Routing, controllers, parameters, or domain layout -> [handlers.md](references/handlers.md), [parameters.md](references/parameters.md), [layout.md](references/layout.md)
       - DTOs, request/response schemas, or OpenAPI docs -> [dtos.md](references/dtos.md), [openapi.md](references/openapi.md)
       - Dependency injection or Dishka providers -> [di-and-dishka.md](references/di-and-dishka.md)
       - Auth backends, guards, middleware, or exception handlers -> [auth-and-guards.md](references/auth-and-guards.md), [middleware.md](references/middleware.md), [exceptions.md](references/exceptions.md)
       - Plugins, WebSockets, Channels/SSE, settings, or CRUD services/filters -> [plugins.md](references/plugins.md), [websockets.md](references/websockets.md), [channels-and-sse.md](references/channels-and-sse.md), [settings.md](references/settings.md), [filters-and-pagination.md](references/filters-and-pagination.md), [services-and-repos.md](references/services-and-repos.md)
       - App composition, CLI, logging/metrics/tracing, or stores/caching -> [app-and-lifecycle.md](references/app-and-lifecycle.md), [cli-and-config.md](references/cli-and-config.md), [logging-and-observability.md](references/logging-and-observability.md), [stores-and-caching.md](references/stores-and-caching.md)
    3. **Open standalone ecosystem skills** when working on dedicated first-party packages (`advanced-alchemy`, `sqlspec`, `msgspec`, `litestar-vite`, `litestar-htmx`, `litestar-saq`, `litestar-queues`, `litestar-security`, `litestar-autowire`, `litestar-email`, `litestar-mcp`, `litestar-granian`, `litestar-testing`, `polyfactory`, `pytest-databases`, `litestar-build`, `litestar-deployment`).
    4. **Keep the stack consistent** across the feature: never mix two persistence layers, two DI containers, or two settings paradigms unless the repository already bridges them intentionally.
    
    </workflow>
    
    <guardrails>
    
    ## Guardrails
    
    - Do not infer a new stack from examples — always match the current project's data layer, DI pattern, settings style, and auth mechanism first.
    - Do not put authentication, authorization, SQL queries, environment parsing, or heavy background work directly inside route handlers; delegate to `Guard` callables, services/repositories, cached settings factories, and task queues.
    - Do not use deprecated `StaticFilesConfig`, `litestar.contrib.*` plugins, `litestar.repository`, `litestar.params.Dependency`, or implicit dependency parameters.
    - Do not expose ORM models directly in `dto` / `return_dto` without `exclude` / `include` field rules that prevent mass assignment and hidden relationship lazy-loads.
    - Do not call `os.getenv()` inside request handlers or module-level code outside the settings module, and never hardcode secrets in source files.
    - Do not call `start_subscription(..., history=N)` on Channels backends that do not implement history (`RedisChannelsPubSubBackend`, `AsyncPgChannelsBackend`, `PsycoPgChannelsBackend`).
    
    </guardrails>
    
    <validation>
    
    ## Validation Checkpoint
    
    - [ ] Route handlers use explicit Litestar 2.25 parameter, body, reserved-kwarg, and dependency markers (`FromPath[T]`, `FromQuery[T]`, `JSONBody[T]`/`RequestBody[T]`, `RawBody`, `QueryParams`, `RequestCookies`, `NamedDependency[T]`, `SkipValidation[T]`).
    - [ ] Request and response contracts use `msgspec.Struct` or `MsgspecDTO` / `SQLAlchemyDTO` with explicit field exclusions and `status_code` declarations.
    - [ ] Authorization checks live in `Guard` functions (`ASGIConnection`, `BaseRouteHandler`) or `litestar-security` decorators, and domain exceptions map cleanly through `exception_handlers`.
    - [ ] Built-in config objects (`CORSConfig`, `CSRFConfig`, `AllowedHostsConfig`, `CompressionConfig`, `LoggingConfig`, `OpenAPIConfig`, `ResponseCacheConfig`) are wired through `Litestar(...)` or `ApplicationCore.on_app_init`.
    - [ ] Validation commands use `make` targets when editing skills in this repository.
    
    </validation>
    
    <example>
    
    ## Example
    
    ```python
    import click
    import msgspec
    from litestar import Controller, Litestar, MediaType, Request, Response, get, post
    from litestar.config.app import AppConfig
    from litestar.config.cors import CORSConfig
    from litestar.config.response_cache import ResponseCacheConfig
    from litestar.connection import ASGIConnection
    from litestar.datastructures import State
    from litestar.di import NamedDependency, Provide
    from litestar.dto import DTOConfig, MsgspecDTO
    from litestar.exceptions import LitestarException, NotFoundException, PermissionDeniedException
    from litestar.handlers.base import BaseRouteHandler
    from litestar.logging import LoggingConfig
    from litestar.openapi import OpenAPIConfig
    from litestar.openapi.plugins import ScalarRenderPlugin
    from litestar.params import FromPath, FromQuery, JSONBody
    from litestar.plugins import CLIPluginProtocol, InitPluginProtocol
    from litestar.status_codes import HTTP_201_CREATED, HTTP_409_CONFLICT
    from litestar.stores.memory import MemoryStore
    from litestar.stores.registry import StoreRegistry
    
    
    class DuplicateSkuError(LitestarException):
        """Raised when an item SKU already exists."""
    
        def __init__(self, sku: str) -> None:
            self.sku = sku
            self.message = f"SKU '{sku}' already exists"
            super().__init__(self.message)
    
    
    def duplicate_sku_exception_handler(
        request: Request[object, object, State],
        exc: DuplicateSkuError,
    ) -> Response[dict[str, object]]:
        """Map DuplicateSkuError to an HTTP 409 response."""
        return Response(
            media_type=MediaType.JSON,
            status_code=HTTP_409_CONFLICT,
            content={"detail": exc.message, "sku": exc.sku, "path": request.url.path},
        )
    
    
    async def require_catalog_editor(
        connection: ASGIConnection[BaseRouteHandler, dict[str, object], object, State],
        _: BaseRouteHandler,
    ) -> None:
        """Verify the authenticated user has catalog write permission."""
        user = connection.scope.get("user")
        if not isinstance(user, dict) or "catalog:write" not in user.get("scopes", ()):
            raise PermissionDeniedException("Missing catalog:write scope")
    
    
    class CatalogItem(msgspec.Struct, rename="camel"):
        """Serialized catalog item contract."""
    
        id: int
        sku: str
        name: str
        locale: str = "en"
    
    
    class CreateCatalogItem(msgspec.Struct, rename="camel"):
        """Payload for creating a catalog item."""
    
        sku: str
        name: str
    
    
    class CatalogItemReadDTO(MsgspecDTO[CatalogItem]):
        """Read DTO for CatalogItem responses."""
    
        config = DTOConfig(rename_strategy="camel")
    
    
    class CatalogService:
        """Domain service managing catalog items."""
    
        async def fetch_item(self, item_id: int, locale: str) -> CatalogItem:
            if item_id <= 0:
                raise NotFoundException(f"Item {item_id} not found")
            return CatalogItem(id=item_id, sku=f"SKU-{item_id}", name="Widget", locale=locale)
    
        async def create_item(self, data: CreateCatalogItem) -> CatalogItem:
            if data.sku == "DUPLICATE":
                raise DuplicateSkuError(data.sku)
            return CatalogItem(id=1, sku=data.sku, name=data.name)
    
    
    async def provide_catalog_service() -> CatalogService:
        """Provide request-scoped CatalogService."""
        return CatalogService()
    
    
    class CatalogController(Controller):
        """HTTP controller for catalog operations."""
    
        path = "/catalog"
        tags = ["Catalog"]
        dependencies = {"catalog_service": Provide(provide_catalog_service)}
        return_dto = CatalogItemReadDTO
    
        @get("/{item_id:int}", cache=60)
        async def get_item(
            self,
            item_id: FromPath[int],
            catalog_service: NamedDependency[CatalogService],
            locale: FromQuery[str] = "en",
        ) -> CatalogItem:
            """Resolve path/query parameters and service dependency explicitly."""
            return await catalog_service.fetch_item(item_id=item_id, locale=locale)
    
        @post("/", guards=[require_catalog_editor], status_code=HTTP_201_CREATED)
        async def create_item(
            self,
            data: JSONBody[CreateCatalogItem],
            catalog_service: NamedDependency[CatalogService],
        ) -> CatalogItem:
            """Validate JSON payload, enforce guard, and delegate creation to service."""
            return await catalog_service.create_item(data)
    
    
    class ApplicationCore(InitPluginProtocol, CLIPluginProtocol):
        """Reference architecture core plugin (litestar-fullstack / litestar-sqlstack)."""
    
        def on_app_init(self, app_config: AppConfig) -> AppConfig:
            app_config.route_handlers.append(CatalogController)
            app_config.exception_handlers[DuplicateSkuError] = duplicate_sku_exception_handler
            app_config.cors_config = CORSConfig(allow_origins=["https://app.example.com"])
            app_config.openapi_config = OpenAPIConfig(
                title="Catalog API",
                version="1.0.0",
                render_plugins=[ScalarRenderPlugin()],
            )
            app_config.stores = StoreRegistry(stores={"response_cache": MemoryStore()})
            app_config.response_cache_config = ResponseCacheConfig(default_expiration=60)
            app_config.logging_config = LoggingConfig(
                log_exceptions="always",
                disable_stack_trace={404, NotFoundException},
            )
            app_config.state = State({"service_name": "catalog-api"})
            return app_config
    
        def on_cli_init(self, cli: click.Group) -> None:
            _ = cli
    
    
    def create_app() -> Litestar:
        """Compose the Litestar 2.25 application via ApplicationCore."""
        return Litestar(plugins=[ApplicationCore()])
    ```
    
    </example>
    
    ## References Index
    
    - [app-and-lifecycle.md](references/app-and-lifecycle.md)
    - [auth-and-guards.md](references/auth-and-guards.md)
    - [channels-and-sse.md](references/channels-and-sse.md)
    - [cli-and-config.md](references/cli-and-config.md)
    - [di-and-dishka.md](references/di-and-dishka.md)
    - [dtos.md](references/dtos.md)
    - [exceptions.md](references/exceptions.md)
    - [filters-and-pagination.md](references/filters-and-pagination.md)
    - [handlers.md](references/handlers.md)
    - [layout.md](references/layout.md)
    - [logging-and-observability.md](references/logging-and-observability.md)
    - [middleware.md](references/middleware.md)
    - [openapi.md](references/openapi.md)
    - [parameters.md](references/parameters.md)
    - [plugins.md](references/plugins.md)
    - [services-and-repos.md](references/services-and-repos.md)
    - [settings.md](references/settings.md)
    - [stores-and-caching.md](references/stores-and-caching.md)
    - [websockets.md](references/websockets.md)
    
    ## Official References
    
    - <https://docs.litestar.dev/> - Litestar documentation
    - <https://docs.litestar.dev/latest/reference/> - Litestar API reference
    - <https://docs.litestar.dev/latest/release-notes/changelog.html> - Litestar 2.x changelog
    - <https://github.com/litestar-org/litestar/tree/v2.25.0> - Audited Litestar 2.25.0 source
    - <https://dishka.readthedocs.io/en/stable/integrations/litestar.html> - Dishka Litestar integration
    
    ## Shared Styleguide Baseline
    
    - [General](../litestar-styleguide/references/general.md)
    - [Python](../litestar-styleguide/references/python.md)
    - [Litestar](../litestar-styleguide/references/litestar.md)
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.