How to migrate from 0.13¶

Release 0.14 replaced the container layer of 0.13 (redsun.containers, redsun.virtual, AppContainer) with sessions. Nothing of the old layer is kept under its old name, so this page lists each change and what to write instead.

Imports¶

Declaring components¶

# 0.13
class MyApp(QtAppContainer):
    motor = declare_device(MyStage, axis=["X", "Y"])
    motor_ctrl = declare_presenter(MotorPresenter)
    motor_widget = declare_view(MotorView, step_size=5.0)


# now
class MyApp(QtSession):
    motor: Annotated[AsDevice[MyStage], Declare(axis=["X", "Y"])]
    motor_ctrl: AsPresenter[MotorPresenter]
    motor_widget: Annotated[AsView[MotorView], Declare(step_size=5.0)]

• The config= class keyword is now a class attribute: config = "session.yaml".
• from_config="key" is FromConfig("key"), and a different registered name is Alias("name"), both inside Annotated.
• MyApp(session="lab") is MyApp({"session": "lab"}): a session takes its settings as a configuration source.

Presenters¶

A presenter no longer starts with (name, devices), and it inherits nothing. The session calls it with every argument by keyword and fills each parameter by type:

# 0.13
class MotorPresenter(Presenter):
    def __init__(
        self, name: str, devices: Mapping[str, Device], /, step: float = 1.0
    ) -> None:
        super().__init__(name, devices)
        self.step = step


# now
class MotorPresenter:
    def __init__(self, name: str, *, devices: DeviceMapping, step: float = 1.0) -> None:
        self.name = name
        self.devices = devices
        self.step = step

Ask for DevicesOf[P] to get only the devices satisfying a protocol.

Views¶

A view is a QWidget whose constructor starts with (name: str, parent: QWidget), and which says where it goes with a placement:

# 0.13
class MotorView(QtView):
    def __init__(self, name: str, /, **kwargs: Any) -> None:
        super().__init__(name)

    @property
    def view_position(self) -> ViewPosition:
        return ViewPosition.LEFT


# now
class MotorView(QWidget):
    placement: Placement = Dock("left")

    def __init__(self, name: str, parent: QWidget) -> None:
        super().__init__(parent)
        self.name = name

ViewPosition.CENTER is Central(). A view's slots still run on the main thread, as QtView's did.

Sharing values between components¶

register_providers, inject_dependencies, ProviderKey and the provide/require/try_require calls are gone. The type is the key:

# 0.13
MOTOR_READINGS = ProviderKey(instance_of=MotorReadings)


def register_providers(self, container):
    container.provide(MOTOR_READINGS, self._readings)


def inject_dependencies(self, container):
    self.readings = container.require(MOTOR_READINGS)


# now
@provides
def readings(self) -> MotorReadings:
    return self._readings


def setup(self, readings: MotorReadings) -> None:
    self.readings = readings

try_require(KEY) becomes a parameter x: X | None = None. See Share a value.

The keys redsun.path_provider.PATH_PROVIDER, redsun.catalog.CATALOG and redsun.engine.DEFERRALS are removed. Ask for the type instead: a SessionPathProvider or CatalogAddress | None parameter, and Deferrals from the component that shares it.

Wiring¶

wire no longer connects anything itself. It's a generator that yields each link as a signal and the slot it reaches, and the session makes the connection. connect, subscribe and connect_paths are gone. You yield a psygnal signal and an ophyd-async device signal the same way, and the session tells them apart:

# 0.13
def wire(self) -> None:
    self.connect(self.ctrl.sig_moved, self.widget.refresh)
    self.virtual_container.subscribe(self.stage.readback, self.widget.on_reading)


# now
def wire(self) -> Iterator[Link]:
    yield self.ctrl.sig_moved, self.widget.refresh
    yield self.stage.readback, self.widget.on_reading

The wiring section of a session file is now a mapping from a signal path to one slot path or a list of them, not a list of from:/to: entries:

# 0.13
wiring:
  - from: ctrl.sig_moved
    to: widget.refresh

# now
wiring:
  ctrl.sig_moved: widget.refresh

The virtual container's other members moved too:

The session skips and logs a link to a component that failed to build, instead of raising.

Hooks¶

# 0.13
class MyApp(QtAppContainer):
    configure_application = declare_hook(DarkTheme, accent="#d47f4c")


# now
class MyApp(QtSession):
    configure_application: Annotated[AsHook[DarkTheme], Declare(accent="#d47f4c")]

• A hook can no longer be given as a built object; pass the class and its arguments.
• One provider for several points uses Serves(...), not the same object declared twice.
• QtCreatesApplication, QtConfiguresApplication, QtWrapsBuild and QtConfiguresMainView are removed. QtHook names the points, and their protocols are CreatesApplication, ConfiguresApplication, WrapsBuild and ConfiguresMainView, imported from redsun.
• during_build now covers the build steps only, not the window's first paint.

Services¶

# 0.13
class MyApp(AppContainer):
    transport = "pv-access"
    camera_ioc = declare_service(
        module="mylab.iocs.camera", ready="serving", prefix="CAM:"
    )


# now
class MyApp(Session):
    config = {"services": {"transport": "pv-access"}}
    camera_ioc: Annotated[
        AsService, Launch("mylab.iocs.camera", ready="serving", prefix="CAM:")
    ]

A service without a module is Attach("BL01:"). Services start in the first build step, so you can no longer call start_services before build.

Session files¶

New keys: strict, mock, providers, actions, color_scheme. See Write a session file.

Plans¶

# 0.13
@continous(togglable=True, pausable=True)
def live(detectors: Sequence[DetectorProtocol]) -> MsgGenerator[None]: ...


# now
@continuous(pausable=True)
def live(detectors: Sequence[DetectorProtocol]) -> MsgGenerator[None]: ...

• wait_for_actions never timed out, and still does not: the argument is the time between two checkpoints.
• wait_for_actions raises ValueError when events is empty.
• actions is an ActionManager from redsun.engine.actions, made by whoever owns the plans. See Actions while a plan runs.
• PlanAction is frozen, and PlanAction.toggle_states defaults to None where it defaulted to ("On", "Off").
• create_plan_spec raises ValueError for a plan declaring two actions of one name.

Other changes¶

• The experimental extra is gone; in-n-out is a dependency of redsun, and dependency-injector is no longer one.
• The session opens its log files when the build reads the configuration, not when the session object is made.
• The main window no longer starts maximised; it opens where the user last left it.
• AppContainer.config, the merged configuration, is Session.serialize().
• run exists only on a session with a frontend.
• DescriptorTreeView.update_reading and confirm_change are replaced by set_value(key, value), which shows what the device read back and settles a pending edit, and revert(key), for an edit the device refused.
• redsun.engine.Status is removed; import it from bluesky.protocols.
• connect_devices is removed. A session file setting mock: true connects every autoconnect device to a simulated backend during the build, and a device declared with autoconnect: false is connected by the component that uses it.