Skip to content

Upgrading

On a 0.x version, a minor bump is the only one that may break you, always with migration instructions; see Status → Versioning. Each section below is the one to read when a build that worked on the previous minor no longer does.

To 0.5.0

0.5.0 aligns composition and name lookup with Python's scoping. That fixes several silent miscompiles, listed in the changelog, and breaks one thing.

A handler writes a signal only through global

A local handler that assigns a signal's name without declaring it global is now a CompileError that names the fix:

count: Local[int] = 0


def bump() -> None:
    count = count + 1      # CompileError: declare `global count`

In Python that line binds a local, and count = count + 1 raises UnboundLocalError. situ wrote the signal anyway, so the browser ran something other than the Python on the page. Add the declaration, which compiles to nothing:

def bump() -> None:
    global count
    count = count + 1

A parameter that shares a signal's name is the parameter: assigning it no longer writes the signal. A server command still cannot assign a signal at all; push it with signal() or reset(), as before.

Composed names: no action needed

A child component's generator or :each variable that shares a name with a prop, or with a name the parent passes in, is now renamed, leaving the outer name intact. A handler parameter no longer reads a Local of the same name. A component that relied on the old behaviour was computing the wrong value; one that did not compiles as before.

To 0.4.0

0.4.0 finishes the typed dialect and stops assuming a web framework. It carries breaking changes, each announced in the changelog.

litestar is now an extra

The most likely break: pip install situ no longer installs Litestar, so importing the Litestar mount raises an ImportError that names the fix. The base install is the compiler plus situ.mount.asgi.asgi_app, which serves a component on any ASGI host and needs no web framework.

If you use mount_component, mount_tree, or declui's mount_model, add the extra:

pip install "situ[litestar]"      # or: uv add "situ[litestar]"

Nothing else changes: the mount API is identical. A FastAPI or bare-uvicorn user who was only ever on the ASGI adapter installs nothing extra and is unaffected.

A comparison the compiler cannot type is now a CompileError

Where an operand's type could not be established, situ used to emit a runtime guess (S.eqv) that compared both sides through Number(). The comparison reported 3 == [3] as true and made a non-numeric value (a status string, a filter id) never compare equal. That guess is gone; the comparison is refused at compile time instead.

The error names the operand and how to give it a type; any one of these fixes it:

  • Annotate the handler parameter: def go(id: int). (A bare parameter is now inferred from its call sites, so most comparisons type themselves; you see this error when the call sites disagree or pass something untypable.)
  • Declare the signal's element type: sel: Local[set[int]], with the element type spelled out.
  • Declare the row's record: data-row="IssueRow" on the row element plus a matching TypedDict, so t.id decodes to its real type.

Worked before/after examples: Compile errors → an operand whose type is not known.

Signal and Signals are gone from situ.siting

They were exported and documented, but the compiler never used them. It builds each app's signal table itself. If you reached for them, EmittedApp.signal_table is the real per-app projection. Site, TRANSPORT, and SIGNALS_HEADER are unchanged.

children= is gone from mount_component / mount_tree

Use components= (a resolution Context, e.g. Context.from_dir(DIR)), which has been the documented form for several releases and resolves the tags your tree actually reaches. mount_tree now requires it.

Set membership: no action needed

x in some_set now compiles to an element-wise Number() compare, because JavaScript's Set.has uses ===. True in {1, 2} was false in the browser and true in Python. If a set-membership test behaved differently in the browser than in Python, it now matches Python.