Metadata-Version: 2.4
Name: situ
Version: 0.6.0
Summary: Site your state, derive the wire — a Python→JS component compiler with an explicit client/server seam, for Litestar, ASGI and Flask.
Keywords: litestar,hypermedia,compiler,reactive,signals,web-ui,frontend,python-to-javascript
Author: Stéphane Fermigier
Author-email: Stéphane Fermigier <sfermigier@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Litestar
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Code Generators
Classifier: Typing :: Typed
Requires-Dist: abilian-astero>=0.3.0
Requires-Dist: jinja2>=3.1
Requires-Dist: flask>=3.0 ; extra == 'flask'
Requires-Dist: litestar>=2.22 ; extra == 'litestar'
Requires-Dist: attrs>=23.0 ; extra == 'model-adapters'
Requires-Dist: msgspec>=0.18 ; extra == 'model-adapters'
Requires-Dist: pydantic>=2.0 ; extra == 'model-adapters'
Requires-Dist: sqlalchemy>=2.0.50 ; extra == 'sqlalchemy'
Requires-Dist: aiosqlite>=0.20.0 ; extra == 'sqlalchemy'
Requires-Dist: dishka>=1.6 ; extra == 'sqlalchemy'
Requires-Dist: greenlet>=3.0 ; extra == 'sqlalchemy'
Requires-Python: >=3.12
Project-URL: Documentation, https://situ.hop3.abilian.com/
Project-URL: Homepage, https://situ.hop3.abilian.com/
Project-URL: Issues, https://github.com/sfermigier/situ/issues
Project-URL: Repository, https://github.com/sfermigier/situ
Provides-Extra: flask
Provides-Extra: litestar
Provides-Extra: model-adapters
Provides-Extra: sqlalchemy
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/situ-wordmark.svg" alt="situ" width="220">
</p>

<p align="center"><em>Site your state, derive the wire.</em></p>

---

**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 can read every line the compiler ships.

It is for Python developers who want a reactive web UI and would keep the whole app in
Python. A hypermedia library (htmx, Datastar) hands you a *mechanism*: swap HTML on an
event, wire the targets yourself; situ gives you a *structure* for the whole UI layer:

- **State has a place.** Declare where each signal lives (`Local` / `Url` / `Server` /
  `Synced`) and its transport is derived: a live search, a selection, an open dialog, a
  database command, a shareable URL. You write no fetch, target, or SSE wire by hand. The
  boundary is compile-checked: a client read of `Server` state is a `CompileError`.
- **No client JavaScript, no build step.** Real HTML and Python; the compiler emits the
  island (no bundler, `node_modules`, or separate front-end to deploy) and you can
  read each line it ships (a few kilobytes, no framework runtime underneath).
- **A composition model.** Components with props, events, slots, per-placement state, and
  scoped CSS; the compiler folds a whole tree of them into one island at zero runtime cost.
- **A component kit** *(work in progress)*. `situ_ui` provides typed, HTML-first widgets
  (Dialog, Tabs, Combobox, DataGrid, Menu), invoked from your templates, so common UI (a
  dialog, a searchable select, a data grid) ships with the framework.
- **A meta-framework on top.** For CRUD screens, [declui](#or-generate-the-ui-from-a-model-declui)
  turns a typed model into a form, list, tracker, or create/edit screen, with sensible
  type→widget defaults plus a MetaUI-style rule cascade. You write no component at all.
- **One component, any framework.** [Litestar](https://litestar.dev) (the reference), any
  ASGI host (FastAPI, Starlette, bare uvicorn), or Flask: unchanged. The ASGI adapter is built
  on the protocol itself, so it imports no web framework and adds no dependency; the Litestar
  imports are lazy, so neither other path pulls in Litestar.

> situ is a young, alpha library extracted from a research programme; the compiler accepts a
> **bounded** dialect of Python and fails *closed* on anything outside it.
> See [Status](#status) and the [known limits](https://situ.lab.abilian.com/project/status/).

## The one idea: site each piece of state

Every signal declares its **site**. The transport follows from that: you never write
a fetch, a target, or an SSE wire.

| Site | Where it lives | What the compiler derives |
|------|----------------|---------------------------|
| `Local[T]` | the browser | compiled to JS: zero network |
| `Url[T]` | the query string | a shareable link the server re-renders |
| `Server[Facade]` | the database | a POST command that re-renders one region |
| `Derived[T]` | the browser, computed from other signals | an update that reruns when they change |
| `Synced[T]` | *(reserved)* | a local-first replica (design stage) |

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.

## Install

```bash
pip install situ                   # the compiler + the generic ASGI adapter (no web framework)
pip install "situ[litestar]"       # + the Litestar mount (the reference adapter)
pip install "situ[flask]"          # + the Flask (WSGI) adapter
pip install "situ[sqlalchemy]"     # + the SQLAlchemy/Dishka session helpers
pip install "situ[model-adapters]" # + attrs/msgspec/pydantic model sources for declui
```

Requires Python 3.12+.

## Sixty seconds of situ

A component is **two sibling files sharing a stem**, so each gets native editor tooling.

`counter.py`: the signals and handlers:

```python
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
```

`counter.html` is real HTML with shorthand reactive attributes:

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

`app.py`: the controller is one mount call plus the wiring:

```python
from pathlib import Path

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

HERE = Path(__file__).parent

app = Litestar(
    route_handlers=[
        mount_static_component(
            path="/counter",
            stem=HERE / "counter",  # counter.py + counter.html
            template="page.html",  # situ ships a minimal default
            meta={"name": "Counter"},
        ),
        # serve the runtime shim the generated island loads from /static/_rt.js
        create_static_files_router(path="/static", directories=[situ.static_dir()]),
    ],
    template_config=TemplateConfig(
        directory=situ.templates_dir(), engine=JinjaTemplateEngine
    ),
)
```

```bash
litestar --app app:app run    # then open http://localhost:8000/counter
```

The runtime enforces two rules: every reactive element lives inside `<header>` or the single `<div data-region>` (the two roots where binders are wired); `data-region` is the **first attribute** on that `<div>`.

## When state needs the database

Declare the site; the seam follows:

```python
search: Local[str] = ""  # live search — compiled to JS, zero network
filter: Url[str] = "all"  # a shareable link the server re-renders
issues: Server[IssuesFacade]  # the store: a facade in handlers, rows in the template


async def close(id):  # `await` makes this a server command:
    await issues.set_status(id, "closed")  # → POST /cmd/close/{id} → region re-render
```

A handler containing `await` becomes a POST command; any other handler compiles to
client JS. The [Server components guide](https://situ.lab.abilian.com/getting-started/server-components/) walks the wiring. The [tutorial](https://situ.lab.abilian.com/tutorial/) builds a complete issue tracker this way in six parts (live search, filters, selection, commands, a create dialog), with **zero hand-written JavaScript** and a generated island of ~7 KB.

## Or generate the UI from a model: declui

For CRUD-shaped screens, skip the component too. **declui** turns a typed model into a
working form, list, master-detail, server-backed tracker, or **create/edit form**, at
compile time, onto the same seam:

```python
@dataclass
class Sample:
    title: str  # str  → text input
    shirt: Annotated[Shirt, Field()] = Shirt.medium  # Enum → <select>
    price: Annotated[Decimal, Field()] = Decimal("10.50")  # Decimal → decimal input
    need_by: Annotated[date | None, Field()] = None  # date → date picker


app = Litestar(
    route_handlers=[mount_model(path="/sample", screen=Screen(model=Sample)), ...]
)
```

Conditional predicates (`editable="rating > 50"`) compile to client binders. `@action`
methods become gated command buttons that can have a label and navigate on success.
`screens=("create",)` / `("edit",)` generate write forms whose submit calls the facade
(`facade.create(**fields)`), gated by `required=` / `valid=`. `Screen(rules=...)`
(the MetaUI app sheet) sets presentation by selector across fields and per screen. Models
may be dataclasses, attrs, msgspec, Pydantic, or SQLAlchemy. In the capstone example, an
8-line `Screen` stands in for the 311 lines of hand-written components in the equivalent
demo.
[declui documentation →](https://situ.lab.abilian.com/declui/)

## Litestar or Flask

The mount has a portable core (`situ.mount.core`: dispatch, render, the
command/region/feed/window protocol, no framework imported) with thin adapters over it:

- **Litestar** (the reference): `mount_component` / `mount_static_component` /
  `mount_tree`, with per-request DI via Dishka.
- **Flask** (WSGI): `situ.mount.flask.mount_flask` returns an ordinary `Blueprint`; a
  plain `resolve=lambda: store` callable replaces the DI container. The request path
  imports zero Litestar. See [`examples/flask/`](examples/flask/app.py).

## Documentation

Full documentation lives in [`docs/`](docs/) (a [Zensical](https://zensical.org) site;
`make docs-serve` to browse it locally at http://localhost:8000):

- **[Quickstart](https://situ.lab.abilian.com/getting-started/quickstart/)**: the counter, explained.
- **[Tutorial](https://situ.lab.abilian.com/tutorial/)**: build an issue tracker in six parts; every
  listing compiles and is browser-verified.
- **[Concepts](https://situ.lab.abilian.com/concepts/sites-and-the-seam/)**: sites & the seam, handlers &
  commands, the compiled dialect, composition, the wire protocol.
- **[Cheat sheet](https://situ.lab.abilian.com/reference/cheat-sheet/)**: the whole authoring surface on
  one page; plus the full [binder](https://situ.lab.abilian.com/reference/binders/),
  [API](https://situ.lab.abilian.com/reference/api.md), and [error](https://situ.lab.abilian.com/reference/errors/) references.
- **[situ vs. …](https://situ.lab.abilian.com/getting-started/comparisons/)**: React, Vue, Svelte, htmx,
  Datastar, LiveView, Eliom and the research lineage.
- **For AI coding assistants**: [`llms.txt`](https://situ.lab.abilian.com/llms.txt) (index) and
  [`llms-full.txt`](https://situ.lab.abilian.com/llms-full.txt): a single-file, self-contained reference
  with verified samples and the rules an agent must follow.

## Demos & examples

Everything documented runs, browser-verified by an e2e suite that fails on any console
error:

```bash
uv run litestar --app demos.app:app run       # 17 demos behind one gallery
uv run uvicorn examples.declui.app:app        # the declui example tour (create/edit, rules, …)
uv run --with flask flask --app examples/flask/app.py run   # the Flask adapter
```

<p align="center">
  <img src="https://situ.lab.abilian.com/assets/demo-issues.png" alt="The flagship demo: a master-detail issue tracker" width="720">
</p>

The flagship (`/issues`, above) is a five-component master-detail tracker whose entire
client is a **117-line generated island**; across all thirty shipped apps the islands
measure 6–13 KB over a ~540-line shared shim. Each demo page shows its own source, its
signal→transport table, and the island it serves.

## What's in the box

- `situ.compiler`: the Python→JS compiler (`parse_front_end`, `load_front_end`,
  `compile_app`, `splice_tree`) and the site markers. Pure standard library.
- `situ.mount`: the framework-neutral mount core plus the Litestar route factories and
  the Flask `Blueprint` adapter. Litestar bindings load lazily.
- `situ.declui`: the model→UI generator (`Field`, `Screen`, `Rule`, `zones`, `action`,
  `mount_model`): forms, lists, trackers, create/edit write forms, and the rule cascade.
- `situ_ui`: a component kit: 24 components (Dialog, Combobox, DataGrid, Menu, …), a
  `ui-*` CSS class contract, interactions compiled from Python.
- `situ.siting`: the `Site` contract and the transport it derives; `situ.infra`: Jinja
  string rendering and, behind `[sqlalchemy]`, an async engine + Dishka session provider.
- `situ new <Name>`: scaffold a component's `.html` + `.py` pair (`--server` adds a facade
  and an async command); `situ check`: static component-tree resolution for your lint loop
  (also runnable as `python -m situ.new` / `python -m situ.check`).

## Status

Alpha. The compiler accepts a bounded dialect of Python and rejects the rest with a clear
error; it does not relocate database I/O to the client.

The dialect is **specified as a table of typing rules**. Every rule is checked against
CPython: situ runs a differential oracle that generates expressions over operand type pairs,
evaluates them in CPython and in node, and compares. A construct with no rule cannot be
emitted at all. The lowerer has no guards, because an ill-typed program cannot reach it.
The oracle found 1323 divergences in a compiler that passed its whole test suite; the
disagreement baseline is now **empty**: across all the expressions it generates, as a value and
as a condition, situ agrees with CPython or refuses to compile. Knowing the types also lets the
compiler accept **more**: `k in d`, `xs[-1]`, `'ab' * 3` and `n % m` were all rejected by the
untyped emitter and are now correct. `Synced` is a reserved site: the
design names it and the implementation is future work. Dishka is required only by the
Litestar `mount_component`; the Flask adapter takes a plain callable. The full list of
limits is in [Status & roadmap](https://situ.lab.abilian.com/project/status/).

## License

[Apache 2.0](LICENSE) © Stefane Fermigier & Abilian SAS
