Skip to content

sunflare.presenter module

Presenters come in two forms:

Protocols

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:

Mixin Classes

Boilerplate mixin classes - minimal, reusable components to provide a specific functionality:

API Reference

Connection

Bases: NamedTuple

Connection tuple.

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

Usable with sunflare.presenter.Receiver and sunflare.presenter.SenderReceiver to set the connection_map parameter.

Attributes:

Name Type Description
signal ForwardRef('str')

Signal name.
slot ForwardRef('Callable[..., None]')

Slot to connect to.
Source code in src/sunflare/presenter/_base.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
class Connection(NamedTuple):
    """Connection tuple.

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

    Usable with [`sunflare.presenter.Receiver`]()
    and [`sunflare.presenter.SenderReceiver`]()
    to set the `connection_map` parameter.

    Attributes
    ----------
    signal : ``str``
        Signal name.
    slot : ``Callable[..., None]``
        Slot to connect to.
    """

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

PPresenter

Bases: Protocol

Presenter protocol class.

Provides the interface for a class that Redsun can recognize as a controller by implementing the defined attributes.

Attributes:

Name Type Description
ctrl_info PPresenterInfo

Presenter configuration information.
models Mapping[str, PModel]

Reference to the models used in the controller.
virtual_bus VirtualBus

Reference to the virtual bus.
Source code in src/sunflare/presenter/_base.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
@runtime_checkable
class PPresenter(Protocol):  # pragma: no cover
    """Presenter protocol class.

    Provides the interface for a class
    that Redsun can recognize as a controller by
    implementing the defined attributes.

    Attributes
    ----------
    ctrl_info : PPresenterInfo
        Presenter configuration information.
    models : Mapping[str, PModel]
        Reference to the models used in the controller.
    virtual_bus : VirtualBus
        Reference to the virtual bus.
    """

    ctrl_info: PPresenterInfo
    virtual_bus: VirtualBus
    models: Mapping[str, PModel]

Presenter

Bases: PPresenter, Generic[CI]

A boilerplate base class for quick development.

Users may subclass from this controller and provide their custom sunflare.config.PresenterInfo implementation.

Example usage:

from sunflare.presenter import Presenter
from sunflare.config import PresenterInfo
from attrs import define


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


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

Parameters:

Name Type Description Default
ctrl_info ``CI``

Instance of sunflare.config.PresenterInfo subclass.

 required
models ``Mapping[str, PModel]``

Reference to the models used in the controller.

 required
virtual_bus `sunflare.virtual.VirtualBus`

Reference to the virtual bus.

 required
Source code in src/sunflare/presenter/_base.py 
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
class Presenter(PPresenter, Generic[CI]):
    """A boilerplate base class for quick development.

    Users may subclass from this controller and provide their custom
    `sunflare.config.PresenterInfo` implementation.

    Example usage:

    ```python
    from sunflare.presenter import Presenter
    from sunflare.config import PresenterInfo
    from attrs import define


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


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

    Parameters
    ----------
    ctrl_info : ``CI``
        Instance of `sunflare.config.PresenterInfo` subclass.
    models : ``Mapping[str, PModel]``
        Reference to the models used in the controller.
    virtual_bus : `sunflare.virtual.VirtualBus`
        Reference to the virtual bus.
    """

    def __init__(
        self,
        ctrl_info: CI,
        models: Mapping[str, PModel],
        virtual_bus: VirtualBus,
    ) -> None:
        self.ctrl_info = ctrl_info
        self.models = models
        self.virtual_bus = virtual_bus

Receiver

Bases: Presenter[CI]

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 :class:~sunflare.config.PresenterInfo implementation.

Example usage:

from sunflare.presenter import ReceiverController
from sunflare.config import PresenterInfo
from attrs import define

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

class MyController(ReceiverController[MyControllerInfo]):
    def __init__(
        self,
        ctrl_info: MyControllerInfo,
        models: Mapping[str, PModel],
        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 sunflare.presenter.Presenter for parent information.

Parameters:

Name Type Description Default
ctrl_info ``CI``

Instance of a sunflare.config.PresenterInfo subclass.

 required
models ``Mapping[str, PModel]``

Reference to the models used in the controller.

 required
virtual_bus `sunflare.virtual.VirtualBus`

Reference to the virtual bus.

 required
connection_map ``Mapping[str, list[Connection]]``

Mapping of emitters to a list of connections. Default is None (no connections).

 None

Attributes:

Name Type Description
connection_map ``Mapping[str, list[Connection]]``, keyword-only, optional

Mapping of emitters to a list of connections.
Source code in src/sunflare/presenter/_base.py 
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
class Receiver(Presenter[CI]):
    """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
    :class:`~sunflare.config.PresenterInfo` implementation.

    Example usage:

    ```python
    from sunflare.presenter import ReceiverController
    from sunflare.config import PresenterInfo
    from attrs import define

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

    class MyController(ReceiverController[MyControllerInfo]):
        def __init__(
            self,
            ctrl_info: MyControllerInfo,
            models: Mapping[str, PModel],
            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 [`sunflare.presenter.Presenter`]() for parent information.

    Parameters
    ----------
    ctrl_info : ``CI``
        Instance of a `sunflare.config.PresenterInfo` subclass.
    models : ``Mapping[str, PModel]``
        Reference to the models used in the controller.
    virtual_bus : `sunflare.virtual.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).

    Attributes
    ----------
    connection_map : ``Mapping[str, list[Connection]]``, keyword-only, optional
        Mapping of emitters to a list of connections.
    """

    def __init__(
        self,
        ctrl_info: CI,
        models: Mapping[str, PModel],
        virtual_bus: VirtualBus,
        *,
        connection_map: Mapping[str, list[Connection]] | None = None,
    ) -> None:
        self.connection_map = connection_map
        super().__init__(ctrl_info, models, virtual_bus)

    def connection_phase(self) -> None:
        """Connect the signals defined in ``self.connection_map``.

        This method is called from Redsun during
        application initialization.
        """
        if self.connection_map is not None:
            for emitter, connections in self.connection_map.items():
                for connection in connections:
                    self.virtual_bus.signals[emitter][connection.signal].connect(
                        connection.slot
                    )

connection_phase 

connection_phase() -> None

Connect the signals defined in self.connection_map.

This method is called from Redsun during application initialization.

Source code in src/sunflare/presenter/_base.py 
296
297
298
299
300
301
302
303
304
305
306
307
def connection_phase(self) -> None:
    """Connect the signals defined in ``self.connection_map``.

    This method is called from Redsun during
    application initialization.
    """
    if self.connection_map is not None:
        for emitter, connections in self.connection_map.items():
            for connection in connections:
                self.virtual_bus.signals[emitter][connection.signal].connect(
                    connection.slot
                )

Sender

Bases: Presenter[CI]

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 sunflare.config.PresenterInfo implementation.

Example usage:

from sunflare.presenter import SignalerController
from sunflare.config import PresenterInfo
from attrs import define


@define
class MyControllerInfo(PresenterInfo):
    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, PModel],
        virtual_bus: VirtualBus,
    ) -> None:
        signals = ["sigRegisteredSignal"]
        super().__init__(ctrl_info, models, virtual_bus, signals)
        # any other initialization code...

See sunflare.presenter.Presenter for parent information.

Note

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

Parameters:

Name Type Description Default
ctrl_info ``CI``

Instance of a sunflare.config.PresenterInfo subclass.

 required
models ``Mapping[str, PModel]``

Reference to the models used in the controller.

 required
virtual_bus `sunflare.virtual.VirtualBus`

Reference to the virtual bus.

 required
signals ``Sequence[str]``, keyword-only

Sequence of signals to register. Default is None (no signals registered).

 None

Attributes:

Name Type Description
signals ``Sequence[str]``, optional

Sequence of registered signals.
Source code in src/sunflare/presenter/_base.py 
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
class Sender(Presenter[CI]):
    """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
    `sunflare.config.PresenterInfo` implementation.

    Example usage:

    ```python
    from sunflare.presenter import SignalerController
    from sunflare.config import PresenterInfo
    from attrs import define


    @define
    class MyControllerInfo(PresenterInfo):
        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, PModel],
            virtual_bus: VirtualBus,
        ) -> None:
            signals = ["sigRegisteredSignal"]
            super().__init__(ctrl_info, models, virtual_bus, signals)
            # any other initialization code...
    ```

    See [`sunflare.presenter.Presenter`]() 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 `sunflare.config.PresenterInfo` subclass.
    models : ``Mapping[str, PModel]``
        Reference to the models used in the controller.
    virtual_bus : `sunflare.virtual.VirtualBus`
        Reference to the virtual bus.
    signals : ``Sequence[str]``, keyword-only, optional
        Sequence of signals to register.
        Default is ``None`` (no signals registered).

    Attributes
    ----------
    signals : ``Sequence[str]``, optional
        Sequence of registered signals.
    """

    def __init__(
        self,
        ctrl_info: CI,
        models: Mapping[str, PModel],
        virtual_bus: VirtualBus,
        *,
        signals: Sequence[str] | None = None,
    ) -> None:
        self.signals = signals
        super().__init__(ctrl_info, models, virtual_bus)

    def registration_phase(self) -> None:
        """Register the signals defined in ``self.signals``.

        This method is called from Redsun during
        application initialization.
        """
        self.virtual_bus.register_signals(self, self.signals)

registration_phase 

registration_phase() -> None

Register the signals defined in self.signals.

This method is called from Redsun during application initialization.

Source code in src/sunflare/presenter/_base.py 
199
200
201
202
203
204
205
def registration_phase(self) -> None:
    """Register the signals defined in ``self.signals``.

    This method is called from Redsun during
    application initialization.
    """
    self.virtual_bus.register_signals(self, self.signals)

SenderReceiver

Bases: Presenter[CI]

Combines the functionality of sunflare.presenter.Sender and sunflare.presenter.Receiver.

Users may subclass from this controller and provide their custom sunflare.config.PresenterInfo implementation.

Example usage:

.. code-block:: python

from sunflare.presenter import SenderReceiverController
from sunflare.config import PresenterInfo
from attrs import define

@define
class MyControllerInfo(PresenterInfo):
    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, PModel],
        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:

Name Type Description Default
ctrl_info ``CI``

Instance of a sunflare.config.PresenterInfo subclass.

 required
models ``Mapping[str, PModel]``

Reference to the models used in the controller.

 required
virtual_bus `sunflare.virtual.VirtualBus`

Reference to the virtual bus.

 required
signals ``Sequence[str]``

Sequence of signals to register. Default is None (no signals registered).

 None
connection_map ``Mapping[str, list[Connection]]``

Mapping of emitters to a list of connections. Default is None (no connections).

 None

Attributes:

Name Type Description
signals ``Sequence[str]``, optional

Sequence of registered signals.
connection_map ``Mapping[str, list[Connection]]``, optional

Mapping of emitters to a list of connections.
Source code in src/sunflare/presenter/_base.py 
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
class SenderReceiver(Presenter[CI]):
    """Combines the functionality of [`sunflare.presenter.Sender`]() and [`sunflare.presenter.Receiver`]().

    Users may subclass from this controller and provide their custom
    `sunflare.config.PresenterInfo` implementation.

    Example usage:

    .. code-block:: python

        from sunflare.presenter import SenderReceiverController
        from sunflare.config import PresenterInfo
        from attrs import define

        @define
        class MyControllerInfo(PresenterInfo):
            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, PModel],
                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 `sunflare.config.PresenterInfo` subclass.
    models : ``Mapping[str, PModel]``
        Reference to the models used in the controller.
    virtual_bus : `sunflare.virtual.VirtualBus`
        Reference to the virtual bus.
    signals : ``Sequence[str]``, optional
        Sequence 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).

    Attributes
    ----------
    signals : ``Sequence[str]``, optional
        Sequence of registered signals.
    connection_map : ``Mapping[str, list[Connection]]``, optional
        Mapping of emitters to a list of connections.
    """

    def __init__(
        self,
        ctrl_info: CI,
        models: Mapping[str, PModel],
        virtual_bus: VirtualBus,
        *,
        signals: Sequence[str] | None = None,
        connection_map: Mapping[str, list[Connection]] | None = None,
    ) -> None:
        self.signals = signals
        self.connection_map = connection_map
        super().__init__(ctrl_info, models, virtual_bus)

    def registration_phase(self) -> None:
        """Register the signals defined in ``self.signals``.

        This method is called from Redsun during
        application initialization.
        """
        self.virtual_bus.register_signals(self, self.signals)

    def connection_phase(self) -> None:
        """Connect the signals defined in ``self.connection_map``.

        This method is called from Redsun during
        application initialization.
        """
        if self.connection_map is not None:
            for emitter, connections in self.connection_map.items():
                for connection in connections:
                    self.virtual_bus.signals[emitter][connection.signal].connect(
                        connection.slot
                    )

registration_phase 

registration_phase() -> None

Register the signals defined in self.signals.

This method is called from Redsun during application initialization.

Source code in src/sunflare/presenter/_base.py 
406
407
408
409
410
411
412
def registration_phase(self) -> None:
    """Register the signals defined in ``self.signals``.

    This method is called from Redsun during
    application initialization.
    """
    self.virtual_bus.register_signals(self, self.signals)

connection_phase 

connection_phase() -> None

Connect the signals defined in self.connection_map.

This method is called from Redsun during application initialization.

Source code in src/sunflare/presenter/_base.py 
414
415
416
417
418
419
420
421
422
423
424
425
def connection_phase(self) -> None:
    """Connect the signals defined in ``self.connection_map``.

    This method is called from Redsun during
    application initialization.
    """
    if self.connection_map is not None:
        for emitter, connections in self.connection_map.items():
            for connection in connections:
                self.virtual_bus.signals[emitter][connection.signal].connect(
                    connection.slot
                )