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 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)])
_images/callables.svg

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:

_images/counter_app.png

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() and cancel() if some state variables are needed to be saved Remember to clean data in subclasses when it is no longer needed.

get_state(caller)[source]

Get per-program state.

del_state(caller)[source]

Delete per-program state.

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.

name_to_system_object(value)[source]

Return object for given name registered in System namespace.

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)

_give_triggers()[source]

Give all triggers of this object (non-recursive)

_give_targets()[source]

Give all targets of this object (non-recursive)

cancel(caller)[source]

Recursively cancel all threaded background processes of this Callable. This is called automatically for actions if program deactivates.

give_str()[source]

Give string representation of the callable.

give_str_indented(tags=False)[source]

Give indented string representation of the callable. This is used in Web User Interface for Automate.