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
andTally.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 theTally.id
.- TallyType
TallyType
is an enum used to aid in mapping the three Tally Tally Indicators to theTally.lh_tally
,Tally.txt_tally
andTally.rh_tally
attributes- TallyColor
TallyColor
is an enum defining the four allowable colors for an indicator (including “off”)