Overview

This project uses the Observer Pattern as its primary means of integration with other code. This is handled by the python-dispatch library which provides methods of subscribing to events and property changes.

Tally Object

The primary object used for sending or receiving tally information is the Tally object.

Indicator Properties

It has properties which hold the color for the three indicator values (Tally.lh_tally, Tally.txt_tally and Tally.rh_tally) among others.

These are Property objects which act as observable descriptors, meaning callbacks can be invoked when their values change.

The Tally.set_color() and Tally.get_color() methods can also be used to get and set the values.

Container Support

The indicator properties can be retrieved and assigned using subscription notation (color = tally[key], tally[key] = color). In this form, the expected key and value types match that of Tally.set_color() and the return values match the description in Tally.get_color().

The example shown in Tally.get_color() could be rewritten as:

>>> from tslumd import Tally
>>> tally = Tally(0)
>>> tally['rh_tally']
<TallyColor.OFF: 0>
>>> tally['rh_tally'] = 'red'
>>> tally['rh_tally']
<TallyColor.RED: 1>
>>> tally['txt_tally'] = 'red'
>>> tally['rh_tally|txt_tally']
<TallyColor.RED: 1>
>>> tally['all']
<TallyColor.RED: 1>
>>> tally['lh_tally'] = 'green'
>>> tally['lh_tally']
<TallyColor.GREEN: 2>
>>> tally['all']
<TallyColor.AMBER: 3>

Events

When receiving, the Tally object will emit an Tally.on_update event on any change of state with the Tally instance as the first argument and the property names as the second:

>>> from tslumd import Tally, TallyColor
>>> def my_callback(tally: Tally, props_changed, **kwargs):
...     for name in props_changed:
...         value = getattr(tally, name)
...         print(f'my_callback: {tally!r}.{name} = {value}')
>>> tally = Tally(0)
>>> # bind `my_callback` to the `on_update` event
>>> tally.bind(on_update=my_callback)
>>> # rh_tally is initialized to "OFF"
>>> tally.rh_tally
<TallyColor.OFF: 0>
>>> tally.rh_tally = TallyColor.RED
my_callback: <Tally: (0 - "")>.rh_tally = RED

One can also subscribe to any of the properties individually:

>>> from tslumd import Tally, TallyColor
>>> def my_callback(tally: Tally, value, **kwargs):
...     prop = kwargs['property']
...     print(f'my_callback: {tally!r}.{prop.name} = {value}')
>>> tally = Tally(0, text='foo')
>>> tally
<Tally: (0 - "foo")>
>>> # bind `my_callback` to the `text` property
>>> tally.bind(text=my_callback)
>>> # does not reach the callback
>>> tally.rh_tally = TallyColor.RED
>>> # but this does
>>> tally.text = 'bar'
my_callback: <Tally: (0 - "bar")>.text = bar

Screen Object

Tally objects should never be created directly (as in the examples above). They are instead created by the Screen object and stored in its Screen.tallies dictionary, using the Tally’s index as the key.

When receiving, they are created automatically when necessary (when data is received). The Screen.on_tally_added event can be used to listen for new Tally objects.

Screens also propagate the “on_update” event for all of their Tally objects and emit their own Screen.on_tally_update event. This can reduce the amount of code and callbacks when handling multiple tallies.

When sending, Tally objects are created by using either the Screen.add_tally() and Screen.get_or_create_tally() methods.

Glossary

TallyKey

Combination of Screen.index and Tally.index used to uniquely identify a single tally (or Display) within a single Screen.

TallyKey is a 2-tuple of integers and is available as the Tally.id.

TallyType

TallyType is an enum used to aid in mapping the three Tally Tally Indicators to the Tally.lh_tally, Tally.txt_tally and Tally.rh_tally attributes

TallyColor

TallyColor is an enum defining the four allowable colors for an indicator (including “off”)