Callables¶
Introduction¶
Callables are used like a small programming language to define the programming logic within the
Automate system. All classes derived from ProgrammableSystemObject
have five
attributes that accept Callable type objects:
- Conditions
- Actions
Conditions determine when and actions, correspondingly, what to do.
Actions are triggered by triggers that are Sensors and Actuators. Triggers are collected
from Callables (conditions and actions) automatically, and their status changes are subscribed and followed
automatically by a
ProgrammableSystemObject
. Thus, condition statuses are evaluated automatically, and
actions are executed based on condition statuses.
Let us take a look at a small example that uses conditions and actions:
from automate import *
class CounterClock(System):
active_switch = UserBoolSensor()
periodical = IntervalTimerSensor(interval=1)
target_actuator = IntActuator()
prog = Program(
active_condition = Value(active_switch),
on_activate = SetStatus(target_actuator, 0),
on_update = SetStatus(target_actuator,
target_actuator + 1),
triggers = [periodical],
exclude_triggers = [target_actuator],
)
s = CounterClock(services=[WebService(read_only=False)])
When user has switched active_switch
sensor to True
, this simple program will start adding +1 to target_actuator value every
second. Because periodical
is not used as a trigger in any action/condition, we need to explicitly define it as a
trigger with triggers attribute. Correspondingly, target_actuator
is automatically collected as prog’s trigger (because
it is the second argument of SetStatus), so we need to explicitly exclude it with exclude_triggers
attribute.
Tip
Try the code yourself! Just cpaste the code into your IPython shell and go to http://localhost:8080 in your browser! Screenshot:
Deriving Custom Callables¶
A collection of useful Callables is provided by builtin_callables
module.
It is also easy to derive custom callables from AbstractCallable
baseclass.
For most cases it is enough to re-define call()
method.
If Callable utilizes threads (like
Delay
,
WaitUntil
and
While
)
and continues as an background process after returning from call method, it is also necessary
to define cancel()
that notifies threads that their processing
must be stopped. These threaded Callables can store their threads and other information in
state
dictionary, which stores information per
caller Program. Per-caller state information is fetched via
get_state()
. After data is no longer needed, it must be cleared with
del_state()
method.
Arguments given to Callable are stored in
_args
and keyword arguments in
_kwargs
. There are the following shortcuts that may
be used:
obj
,
value
and
objects
. When accessing these, it is necessary (almost) always
to use call_eval()
method, which evaluates concurrent status value
out of Callable, StatusObject, or string that represents name of an object residing in System namespace.
See more in the following section.
Trigger and Target Collection¶
Triggers and targets are automatically collected from Callables recursively.
All Callable types can specify which arguments are considered as triggers and which
are considered as targets, by defining
_give_triggers()
and
_give_targets()
, correspondingly.
As a general rule, Callable should not consider criteria conditions as triggers
(for example the conditions of
If
,
Switch
etc).
Referring to Other Objects in Callables¶
Various system objects can be referred either by name (string), or by object references. Name is preferred, because it allows to refer to objects that are defined in different scopes (i.e. those that are defined either in Groups or later in the code).
If desired, automatic name referencing can be also disabled by setting
allow_name_referencing
False. Then it is possible
to refer to other objects by using special construct Object(‘name’).
All variables passed to Callables are/must be evaluated through
call_eval()
method, i.e.
if Callables are used as arguments, they are evaluated by their
call()
method
and StatusObject
‘s status attribute is used, respectively.
Callable Abstract Base Class definition¶
Callable classes are are subclassed of AbstractCallable
.
-
class
automate.callable.
AbstractCallable
(*args, **kwargs)[source]¶ A base class for subclassing Callables that are used in Program conditions and action attributes.
Callables are configured by giving them arguments and keyword arguments.They must always define
call()
method which defines their functionality.-
triggers
= None¶ Property that gives set of all triggers of this callable and it’s children callables. Triggers are all those StatusObjects that alter the status (return value of
call()
) of Callable.
-
targets
= None¶ Property that gives set of all targets of this callable and it’s children callables. Targets are all those StatusObjects of which status the callable might alter in
call()
.
-
status
= None¶ Read-only status property of the callable. Usefull only when callable is used as a condition. This automatically depends on all the StatusObjects below the Callable tree.
-
state
= None¶ State dictionary that is used by
call()
andcancel()
if some state variables are needed to be saved Remember to clean data in subclasses when it is no longer needed.
-
on_setup_callable
= None¶ Event that can be used to execute code right after callable setup. See
OfType
. Something that needs to be done manually this way, because Traits does not allow defining the order of subscribed function calls.
-
call_eval
(value, caller, return_value=True, **kwargs)[source]¶ Value might be either name registered in System namespace, or object, either StatusObject or Callable. If Callable, evaluate
call()
method. If StatusObject, return status.
-
setup_callable_system
(system, init=False)[source]¶ This function basically sets up
system
, if it is not yet set up. After that, other Callable initialization actions are performed.Parameters: init – value True
is given when running this at the initialization phase. Then system attribute is set already, but callable needs to be initialized otherwise.
-
call
(*args, **kwargs)[source]¶ The basic functionality of the Callable is implemented in this function. Needs to be defined in derived subclasses.
If callable is used as a Program condition, this must return the value of the condition (see for example conditions
And
,Sum
etc.), otherwise return value is optional.
-
objects
¶ Shortcut to
_args
.
-
obj
¶ Shortcut property to the first stored object.
-
value
¶ Shortcut property to the second stored object.
-
collect
(target)[source]¶ Recursively collect all potential triggers/targets in this node and its children. Define targets and triggers of this particular callable in
_give_triggers()
and_give_targets()
.Parameters: target (str) – valid values: 'targets'
and'triggers'
-
children
¶ A property giving a generator that goes through all the children of this Callable (not recursive)
-
cancel
(caller)[source]¶ Recursively cancel all threaded background processes of this Callable. This is called automatically for actions if program deactivates.
-
give_str_indented
(tags=False)[source]¶ Give indented string representation of the callable. This is used in Web User Interface for Automate.
-