situ¶

Site your state, derive the wire.

situ lets a Python developer write a reactive web UI as one component — real HTML on top, Python signals and handlers below — and declare, per piece of state, where it lives. A real Python→JS compiler reads that declaration and emits a small, app-specific client island; the client/server boundary stays explicit and is enforced at compile time. You author no client JavaScript, and you can read every line the compiler ships.

It targets Litestar and is built for Python full-stack developers who reach for hypermedia (htmx, Datastar) and hit the wall where a piece of state wants to live in the browser — a live search, a selection, an open dialog.

The one idea: site each piece of state¶

Every signal declares its site, and the transport follows from that — you never write a fetch, a target, or an SSE wire.

The boundary is a compile-time invariant: a client read of Server-sited state is a CompileError, so database-backed state cannot reach the browser by accident.

Sixty seconds of situ¶

A component is two sibling files sharing a stem:

from situ import Local

count: Local[int] = 0  # client state — compiled to JS, no network


def bump() -> None:
    global count       # names the local signal this handler writes
    count = count + 1

<div data-region>
  <button @click="bump">+1</button>
  <strong :text="count"></strong>
</div>

One mount_static_component(...) call serves it; the compiler emits the island. The Quickstart walks through the whole thing, and Server components adds the database seam.

What makes it different¶

Three properties hold simultaneously, and each ships with its own falsifier:

1. The seam is proven at build time. Client access to server state fails the build — read, write, or loop (Sites & the seam). There is no code-generation path that could ship database I/O to the browser.
2. The wire is legible. In the unified idiom, a reactive loop declares exactly which per-row fields cross to the client; referencing anything else is a CompileError, so over-fetching is impossible by construction.
3. Decomposition is free. Composition — props, events, slots, provide/inject, per-instance state, scoped CSS — resolves entirely at compile time into one island. A page split into components emits byte-identical JS to the hand-written monolith, pinned by a golden-bytes test.

The generated island for every shipped demo measures 5–12 KB unminified, over a 509-line shared runtime shim that contains no expression interpreter.

What's in the box¶

• situ — the Python→JS compiler (pure standard library) and the Litestar mount factories. API reference.
• situ_ui — a dense-enterprise component kit: 24 components, a CSS class contract, compiled interactions.
• situ.declui — declui, a compile-time declarative-UI generator: a typed model + a small Screen become a working form, list, or master-detail tracker.
• 17 demos and 13 declui examples, each browser-verified — run them.

Where next¶

• New here → Installation, the five-minute Quickstart, then the Tutorial — build a working issue tracker in six parts.
• Weighing it against React, Vue, Svelte, htmx, Datastar, Eliom, … → situ vs. ….
• Coming from htmx/Datastar → Sites & the seam is the mental model; Handlers & commands replaces your target bookkeeping.
• Want CRUD screens from a model → declui.
• Want the research story → the technical report TR-001 and the design-note log.