sunflare.controller

Controllers come in two forms:

• typing.Protocol classes:

  • no inheritance required, allows full customization of the controller;

  • users will have to implement each interface on their own in a controller class;

  • available protocols:

    • ControllerProtocol (for class initialization)

    • HasShutdown (for clearing held resources)

    • HasRegistration (for registering signals)

    • HasConnection (for connecting signals to local methods)

• boilerplate mixin classes:

  • minimal, reusable components to provide a specific functionality

  • inheritance is required

  • available mixins:

    • Controller (minimal base controller)

    • Sender (implements HasRegistration protocol)

    • Receiver (implements HasConnection protocol)

    • SenderReceiver (union of previous two mixins)

class sunflare.controller.ControllerProtocol(ctrl_info, models, virtual_bus)

Controller protocol class.

Provides the interface for a class that Redsun can recognize as a controller.

Parameters:

• ctrl_info (ControllerInfo) – Controller information.

• models (Mapping[str, ModelProtocol]) – Models currently loaded in the active Redsun session.

• virtual_bus (VirtualBus) – Virtual bus.

class sunflare.controller.Controller(ctrl_info, models, virtual_bus)

A boilerplate base class for quick development.

Users may subclass from this controller and provide their custom ControllerInfo implementation.

Example usage:

from sunflare.controller import Controller
from sunflare.config import ControllerInfo
from attrs import define


@define
class MyControllerInfo(ControllerInfo):
    str_param: str
    bool_param: bool
    # any other parameters...


class MyController(Controller[MyControllerInfo]):
    def __init__(
        self,
        ctrl_info: MyControllerInfo,
        models: Mapping[str, ModelProtocol],
        virtual_bus: VirtualBus,
    ) -> None:
        super().__init__(ctrl_info, models, virtual_bus)
        # any other initialization code...

Parameters:

• ctrl_info (CI) – Instance of ControllerInfo subclass.

• models (Mapping[str, ModelProtocol]) – Reference to the models used in the controller.

• virtual_bus (VirtualBus) – Reference to the virtual bus.

class sunflare.controller.Sender(ctrl_info, models, virtual_bus, *, signals=None)

A controller capable of emitting signals to the virtual bus.

Provides an additional signals parameter to the constructor to optionally register a group of the controller’s defined signals.

Users may subclass from this controller and provide their custom ControllerInfo implementation.

Example usage:

from sunflare.controller import SignalerController
from sunflare.config import ControllerInfo
from attrs import define


@define
class MyControllerInfo(ControllerInfo):
    str_param: str
    bool_param: bool
    # any other parameters...


class MyController(SignalerController[MyControllerInfo]):
    sigRegisteredSignal = Signal(str)
    sigUnregisteredSignal = Signal(int)

    def __init__(
        self,
        ctrl_info: MyControllerInfo,
        models: Mapping[str, ModelProtocol],
        virtual_bus: VirtualBus,
    ) -> None:
        signals = ["sigRegisteredSignal"]
        super().__init__(ctrl_info, models, virtual_bus, signals)
        # any other initialization code...

See Controller for parent information.

Note

Users should carefully document the data transmitted by the signals to ensure other endpoints can easily connect to them.

Parameters:

• ctrl_info (CI) – Instance of a ControllerInfo subclass.

• models (Mapping[str, ModelProtocol]) – Reference to the models used in the controller.

• virtual_bus (VirtualBus) – Reference to the virtual bus.

• signals (Iterable[str], keyword-only, optional) – Iterable of signals to register. Default is None (no signals registered).

signals

Iterable of registered signals.

Type:

Iterable[str], optional

registration_phase()

Register the signals defined in self.signals.

This method is called from Redsun during application initialization.

Return type:

None

class sunflare.controller.Receiver(ctrl_info, models, virtual_bus, *, connection_map=None)

A controller capable of connecting signals exposed in the virtual bus to local slots.

Provides an additional connection_map parameter to the constructor to optionally connect a group of the controller’s defined signals to local slots.

Users may subclass from this controller and provide their custom ControllerInfo implementation.

Example usage:

from sunflare.controller import ReceiverController
from sunflare.config import ControllerInfo
from attrs import define

@define
class MyControllerInfo(ControllerInfo):
    str_param: str
    bool_param: bool
    # any other parameters...

class MyController(ReceiverController[MyControllerInfo]):
    def __init__(
        self,
        ctrl_info: MyControllerInfo,
        models: Mapping[str, ModelProtocol],
        virtual_bus: VirtualBus,
    ) -> None:
        connection_map = {
            "WidgetEmitter": [
                Connection("sigWidgetSignal1", self.widget_slot),
                Connection("sigWidgetSignal2", self.other_widget_slot)
            ],
            "ControllerEmitter": [
                Connection("sigControllerSignal", self.controller_slot),
            ],
        }
        super().__init__(ctrl_info, models, virtual_bus, connection_map)
        # any other initialization code...

    def widget_slot(self, *args, **kwargs) -> None:
        # your logic here...

    def other_widget_slot(self, *args, **kwargs) -> None:
        # your logic here...

    def controller_slot(self, *args, **kwargs) -> None:
        # your logic here...

.. note::

    The controller slots should respect the signals' signatures
    in order to correctly receive the emitted signals.
    Make sure to review any provided documentation
    about the nature of the signals being connected.

See Controller for parent information.

Parameters:

• ctrl_info (CI) – Instance of a ControllerInfo subclass.

• models (Mapping[str, ModelProtocol]) – Reference to the models used in the controller.

• virtual_bus (VirtualBus) – Reference to the virtual bus.

• connection_map (Mapping[str, list[Connection]], optional) – Mapping of emitters to a list of connections. Default is None (no connections).

connection_map

Mapping of emitters to a list of connections.

Type:

Mapping[str, list[Connection]], keyword-only, optional

connection_phase()

Connect the signals defined in self.connection_map.

This method is called from Redsun during application initialization.

Return type:

None

class sunflare.controller.SenderReceiver(ctrl_info, models, virtual_bus, *, signals=None, connection_map=None)

Combines the functionality of Sender and Receiver.

Users may subclass from this controller and provide their custom ControllerInfo implementation.

Example usage:

from sunflare.controller import SenderReceiverController
from sunflare.config import ControllerInfo
from attrs import define

@define
class MyControllerInfo(ControllerInfo):
    str_param: str
    bool_param: bool
    # any other parameters...

class MyController(SenderReceiverController[MyControllerInfo]):
    sigRegisteredSignal = Signal(str)
    sigUnregisteredSignal = Signal(int)

    def __init__(
        self,
        ctrl_info: MyControllerInfo,
        models: Mapping[str, ModelProtocol],
        virtual_bus: VirtualBus,
    ) -> None:
        signals = ["sigRegisteredSignal"]
        connection_map = {
            "WidgetEmitter": [
                Connection("sigWidgetSignal1", self.widget_slot),
                # you can recover the slot with "getattr(self, <slot_name>)" too
                Connection("sigWidgetSignal2", getattr(self, "other_widget_slot"))
            ],
            "ControllerEmitter": [
                Connection("sigControllerSignal", self.controller_slot),
            ],
        }
        super().__init__(ctrl_info, models, virtual_bus, signals, connection_map)
        # any other initialization code...

    def widget_slot(self, *args, **kwargs) -> None:
        # your logic here...

    def other_widget_slot(self, *args, **kwargs) -> None:
        # your logic here...

    def controller_slot(self, *args, **kwargs) -> None:
        # your logic here...

.. note::

    The controller slots should respect the signals' signatures
    in order to correctly receive the emitted signals.
    Make sure to review any provided documentation
    about the nature of the signals being connected.

Parameters:

• ctrl_info (CI) – Instance of a ControllerInfo subclass.

• models (Mapping[str, ModelProtocol]) – Reference to the models used in the controller.

• virtual_bus (VirtualBus) – Reference to the virtual bus.

• signals (Iterable[str], optional) – Iterable of signals to register. Default is None (no signals registered).

• connection_map (Mapping[str, list[Connection]], optional) – Mapping of emitters to a list of connections. Default is None (no connections).

signals

Iterable of registered signals.

Type:

Iterable[str], optional

connection_map

Mapping of emitters to a list of connections.

Type:

Mapping[str, list[Connection]], optional

registration_phase()

Register the signals defined in self.signals.

This method is called from Redsun during application initialization.

Return type:

None

connection_phase()

Connect the signals defined in self.connection_map.

This method is called from Redsun during application initialization.

Return type:

None

class sunflare.controller.Connection(signal, slot)

Connection tuple.

Provides a type-hinted helper for describing a connection between a virtual bus signal and a local slot.

Usable with Receiver and SenderReceiver to set the connection_map parameter.

Parameters:

• signal (str) – Signal name.

• slot (Callable) – Slot to connect to.

signal: str

Alias for field number 0

slot: Callable[[...], None]

Alias for field number 1