How a session works¶

A session is one running application. It knows which components to make, makes them in the right order, connects them, and takes them apart again when it ends.

You write a session as a class:

from collections.abc import Iterator
from typing import Annotated

from redsun import AsDevice, AsPresenter, AsView, Declare, Link
from redsun.qt import QtSession


class MyApp(QtSession):
    config = "session.yaml"

    stage: AsDevice[MyStage]
    motor_ctrl: AsPresenter[MotorPresenter]
    motor_widget: Annotated[AsView[MotorView], Declare(step_size=5.0)]

    def wire(self) -> Iterator[Link]:
        yield self.motor_ctrl.sig_moved, self.motor_widget.refresh


MyApp().run()

Each annotated line is a declaration: the name on the left becomes the component's name, and AsDevice, AsPresenter or AsView says which layer it belongs to and which class to make. Once the session is built, self.motor_ctrl holds the MotorPresenter it made, and your editor and mypy see it as one.

The layers of a session¶

A session has three layers of components, the DVP pattern, and the services below them reach the hardware. Point at a layer to read what it holds:

The layers of a session

The session builds the layers in that order, and a component's constructor or setup can take only what its own layer or an earlier one owns. So a view may take presenters and devices, while a presenter never holds a view, which is why a presenter runs without a screen, in a test for example. Signals and slots are not bound by the order: they connect components across layers in either direction. Components explains what each layer may contain.

Services are separate programs, not components the session builds. The session starts the ones it launches before anything else and stops them after every component.

What a build does¶

build reads the configuration, gets the frontend ready, then runs the build steps in a fixed order:

The build steps

Thirteen steps, always in this order. Step through them to see what each one does.

The session reads its files and mappings in order, merges them, and checks the result once, listing every problem it finds.

Before any component exists, the session sets the backend that runs coroutine slots. A QtSession also makes the QApplication here.

The session runs the module of every launched service at once, as its own process, and waits up to 15 seconds for the ready text the declaration names. A session whose storage names a catalog also starts its tiled server.

Each device is made with its name and its settings, plus its service's prefix and the path provider when its constructor takes them. One that raises is left out.

The devices connect all at once. A device that hasn't answered after 10 seconds is left out, like one that failed to build.

The registry collects what a constructor can ask for by type, before the first presenter is made.

Each presenter gets its constructor arguments by type and from the files. What it shares with provides is registered as soon as it is made.

Each view is made the same way. In a QtSession it also gets the main window as its parent.

Every setup runs now that all presenters and views exist, in declaration order, and gets what it asks for by type.

The session records what was built, notes the settings it would save, and closes itself to further building.

Signals are connected to slots: the links wire yields, then the wiring section of the files, then the pairs.

A QtSession puts every view in its main window, where its placement says. A plain Session shows nothing.

The session logs a summary of what it built and what it left out.

The shared values registry collects come from the session's providers, classes made only to share values. The settings seal notes let the session tell later whether you changed any.

The order never changes. A frontend can change what happens inside a step, never which steps run: presentation does nothing in a plain Session, while QtSession shows the main window and its views there.

Components that fail to build¶

A component that fails to build is left out, and so is anything built from it; the session carries on with the rest:

A device that fails to build

The stage and its presenter build. The camera's view takes the camera's presenter, which takes the camera.

The camera's constructor raises, so the session logs the error and leaves the camera out.

camera_ctrl takes the camera, so it is left out too.

So is camera_view, which takes camera_ctrl. The stage and its presenter run as usual.

Here the camera's constructor can't find the serial port it talks through:

class MyCamera(StandardReadable):
    def __init__(self, name: str = "", *, port: str = "COM3") -> None:
        raise OSError(f"serial port {port} not found")


class MyApp(Session):
    stage: AsDevice[MyStage]
    camera: AsDevice[MyCamera]
    stage_ctrl: AsPresenter[StagePresenter]

The session logs the error, and the summary at the end names what is missing:

$ uv run python my_session.py
[07-10-26|22:15:21][ERROR]: Failed to build device 'camera': serial port COM3 not found (_base.py:1581)
[07-10-26|22:15:21][WARNING]: Session built: 1/2 devices, 1/1 presenters, 0/0 views
Not built: camera (device) (_base.py:878)

A mistake in the session itself, such as a malformed wiring section, still stops the build, and a strict session stops whenever something is missing. How to find out why a component is missing shows how to read the summary and make a session strict. ADR 11 records why the session carries on.

Two cases only log a warning: a component that shares nothing, asks for nothing and isn't wired to anything, and a shared value no component asks for. Neither is a mistake while you're still putting a session together, or when a plugin ships more than your session uses.

Shutting down¶

Each build step registers how to undo what it did, at the moment it does it. These releases run in reverse order when you call shutdown:

What shutdown undoes, in order

Shutdown runs the releases the build registered, newest first.

The connections go first, so no signal reaches a slot of a component that is shutting down.

Then each presenter and view, newest first, through its shutdown method.

Then the devices, which the presenters and views may still have used in their own shutdown.

Then the launched services stop, now that no device needs them.

The log files close last, so they record how everything ended.

The connections go first, so no signal calls a slot of a component that is shutting down. A build that fails halfway runs the same releases, so it never leaves a service running. You can call shutdown twice, and build the session again afterwards.

The configuration¶

You can describe a session in one of two ways: declare its components in a Python class, or list them all in a session file. Either way, the settings come from the files and mappings the session reads.

Declared in a classDescribed in a file

The components and their classes live in your code, where your editor and mypy can check them. Files are optional. When the class lists some in config, they supply the session name and the arguments of the components the class declares, each under the component's name:

class MyApp(QtSession):
    config = "session.yaml"

    motor_ctrl: AsPresenter[MotorPresenter]

session: my-lab

presenters:
  motor_ctrl:
    step: 2.0

A file can also add a component the class doesn't declare, by naming the plugin that provides it, as Components from a file and from a class shows.

Every component comes from a plugin, and you need no class of your own:

from redsun import Session

app = Session.from_config("session.yaml").build()

session: my-lab
frontend: qt

devices:
  stage:
    plugin_name: mylab
    plugin_id: stage

The frontend key picks the class the session is built on, so a file naming qt comes up as a QtSession. With no class name to fall back on, the files must set session. Run a session without a GUI shows a file that names no frontend.

Merging the sources¶

A session reads its sources in order and merges them: a later source wins, and nested sections merge key by key, except for a component's entry, which a later source replaces whole:

Two files merged

common.yaml, the first source, gives motor_ctrl a step and a speed.

simulation.yaml is read after it and names motor_ctrl again.

A component's entry is replaced whole, so motor_ctrl keeps the later step and loses speed.

The merged result is checked once, before anything is built.

schema_version, frontend and services.transport say what kind of session this is, so every source must agree on them; a different value is an error. A subclass adds its sources after its base class's, so you write shared settings once:

class Instrument(QtSession):
    config = "common.yaml"


class Simulation(Instrument):
    config = "simulation.yaml"  # read after common.yaml

Every mistake in the configuration at once

The check runs on the merged result. A misspelled key or a value of the wrong type raises ConfigurationError, which lists every problem as section.key: what. Session file lists every key.

Session name¶

You set the name with the session key; without it, the session is named after its class. The name reaches three places:

Where the session name is used

Log files¶

Each run writes its log to a file under logs/<session> in the root folder the session's data goes under, and each launched service writes to a file of its own beside it. The files follow the root if it moves while the session runs, and close last at shutdown. Configure logging shows the layout.

Session protocols¶

A session is written against two protocols, and the classes redsun ships fill them in:

Session protocols and classes

A session with no frontend shows nothing, which is what a test wants: build() alone gives you every component without opening a window.