litestar-styleguide

This is the shared style baseline that every other skill in this plugin references. It exists so that cross-cutting rules (PEP 604 unions, async I/O, ruff + mypy + pyright + prek, test file naming, CI/CD conventions) live in exactly one place — and individual skills stay focused on their framework or tool-specific surface.

Code Style Rules

• Terse, imperative, authoritative. State the preferred choice and a one-line Reason:; never hedge ("you might want to…").
• PEP 604 unions (T | None) and PEP 585 generics (list[T], dict[K, V]). Never use typing.Optional, typing.Union, typing.List, or typing.Dict.
• from __future__ import annotations is a library-author guardrail, not a consumer rule. Application code (handlers, services, tests) MAY use it; avoid it only in modules defining runtime-introspected types (msgspec.Struct, SQLAlchemy Mapped[...], Dishka @provide, SAQ @task).
• Keep runtime-inspected route annotations at module top-level (# noqa: TC001, TC002). When from __future__ import annotations and Ruff flake8-type-checking (TC) are active in Litestar controller/handler modules, keep Request, NamedDependency, FromDishka, FromPath, FromQuery, JSONBody, and request/response DTO imports at module top-level with # noqa: TC001, TC002 (or "**/controllers.py" = ["TC001", "TC002", "TC003"] in per-file-ignores), never inside if TYPE_CHECKING:. Reason: Litestar and Dishka inspect handler annotations at runtime during app startup and OpenAPI generation.
• Async all I/O, Google-style docstrings, function-based pytest tests (@pytest.mark.anyio).
• Litestar first-party stack bias with match-your-stack flexibility. Prefer msgspec, advanced-alchemy / sqlspec, litestar-granian, litestar-saq / litestar-queues when starting fresh, and match the user's existing stack when present.

Quick Reference