Installation¶

Requirements¶

Python ≥ 3.12
Litestar — the reference mount adapter (mounts components as routers), installed as a dependency. The mount core is framework-neutral; a Flask (WSGI) adapter ships in situ[flask], and importing the Flask path pulls in no Litestar.

Install¶

pip install situ                     # the compiler + the Litestar mount (the reference adapter)

or with the optional extras:

Extra	Installs	When you need it
`situ[flask]`	Flask	serving a compiled component on Flask/WSGI (`situ.mount.flask.mount_flask`) instead of Litestar
`situ[sqlalchemy]`	async SQLAlchemy engine helper + a Dishka session provider (`situ.infra.db`, `situ.infra.di`)	server-backed components against a real database
`situ[model-adapters]`	attrs, msgspec, pydantic	declui models written in those libraries (plain `@dataclass` needs nothing)

The component kit ships in the same distribution as a second package, situ_ui — nothing extra to install.

The Litestar mount assumes a Dishka container

Litestar's mount_component resolves your service per request from request.state.dishka_container. The [sqlalchemy] extra ships a ready-made provider, or wire your own — see Server components. This is a detail of the Litestar adapter, not situ: the Flask adapter takes a plain resolve callable and uses no Dishka.

Wire the static files and templates¶

The generated island loads a small runtime shim from /static/_rt.js, and situ ships a minimal default page template. Both come from the package — wire them into your app once:

import situ
from litestar.static_files import create_static_files_router
from litestar.template.config import TemplateConfig
from litestar.plugins.jinja import JinjaTemplateEngine

static = create_static_files_router(path="/static", directories=[situ.static_dir()])
templates = TemplateConfig(directory=situ.templates_dir(), engine=JinjaTemplateEngine)

If you use the component kit, also serve situ_ui.STATIC (its stylesheet + widget runtime) from the same /static route — pass both directories to create_static_files_router.

Working on situ itself¶

The repository uses uv and hatchling:

uv sync                                # installs everything, extras mirrored into the dev group
make lint                              # the gate: ruff ×2 + ty + pyrefly + mypy + `situ check`
make test                              # the full pytest suite
uv run playwright install chromium     # one-time, for the real-browser e2e tier

A feature in this repo only counts when a Playwright e2e passes and make lint is clean — see Status & roadmap.