Builtin Callables

Module builtin_callables provides classes that may be used to various purposes in Automate Program, in condition and action attributes. They are loaded automatically into automate.callables along with callables from possible installed extensions.

Builtin Callable Types

class automate.callables.builtin_callables.Empty(*args, **kwargs)[source]

Do nothing but return None. Default action in Programs.

Usage:

Empty()
class automate.callables.builtin_callables.AbstractAction(*args, **kwargs)[source]

Abstract base class for actions (i.e. callables that do something but do not necessarily return anything.

class automate.callables.builtin_callables.Attrib(*args, **kwargs)[source]

Give specified attribute of a object.

Parameters:bool (no_eval) – if True, evaluation of object is skipped – use this to access attributes of SystemObjects

Usage & example:

Attrib(obj, 'attributename')
Attrib(sensor_name, 'status', no_eval=True)
class automate.callables.builtin_callables.Method(*args, **kwargs)[source]

Call method in an object with specified args

Usage:

Method(obj, 'methodname')
class automate.callables.builtin_callables.Func(*args, **kwargs)[source]

Call function with given arguments.

Usage & example:

Func(function, *args, **kwargs)
Func(time.sleep, 2)
Parameters:add_caller (bool) – if True, then caller program is passed as first argument.
class automate.callables.builtin_callables.OnlyTriggers(*args, **kwargs)[source]

Baseclass for actions that do not have any targets (i.e. almost all actions).

class automate.callables.builtin_callables.Log(*args, **kwargs)[source]

Print callable argument outputs / other arguments to the log.

Usage:

Log(object1, object2, 'string1'...)
Parameters:log_level (str) – Log level (i.e. logging function name) (default ‘info’)
class automate.callables.builtin_callables.Debug(*args, **kwargs)[source]

Same as Log but with debug logging level.

class automate.callables.builtin_callables.ToStr(*args, **kwargs)[source]

Return string representation of given arguments evaluated. Usage:

ToStr('formatstring {} {}', callable1, statusobject1)
Parameters:no_sub (bool) – if True, removes format string from argument list. Then usage is simply:
ToStr(callable1, statusobject1, no_sub=True)
class automate.callables.builtin_callables.Eval(*args, **kwargs)[source]

Execute python command given as a string with eval (or exec).

Usage:

Eval("print time.{param}()", pre_exec="import time", param="time")

First argument: python command to be evaluated. If it can be evaluated by eval() then return value is the evaluated value. Otherwise, exec() is used and True is returned.

Parameters:
  • pre_exec (str) – pre-execution string. For example necessary import commands.
  • namespace (dict) – Namespace. Defaults to locals() in builtin_callables.

Optionally, other keyword arguments can be given, and they are replaced in the first argument by format().

See also (and prefer using): Func

class automate.callables.builtin_callables.Exec(*args, **kwargs)[source]

Synonym to Eval

class automate.callables.builtin_callables.GetService(*args, **kwargs)[source]

Get service by name and number.

Usage:

GetService(name)
GetService(name, number)

Usage examples:

GetService('WebService')
GetService('WebService', 1)
class automate.callables.builtin_callables.ReloadService(*args, **kwargs)[source]

Reload given service.

Usage:

ReloadService(name, number)
ReloadService(name)

Usage examples:

ReloadService('WebService', 0)
ReloadService('ArduinoService')
class automate.callables.builtin_callables.Shell(*args, **kwargs)[source]

Execute shell command and return string value

Parameters:
  • no_wait (bool) – if True, execute shell command in new thread and return pid
  • output (bool) – if True, execute will return the output written to stdout by shell command. By default, execution status (integer) is returned.
  • input (str) – if given, input is passed to stdin of the given shell command.

Usage examples:

Shell('/bin/echo test', output=True) # returns 'test'
Shell('mplayer something.mp3', no_wait=True) # returns PID of mplayer
                                             # process that keeps running
Shell('/bin/cat', input='test', output=True) # returns 'test'.
class automate.callables.builtin_callables.SetStatus(*args, **kwargs)[source]

Set sensor or actuator value

Usage:

SetStatus(target, source)
# sets status of target to the status of source.
SetStatus(target, source, Force=True)
# sets status to hardware level even if it is not changed
SetStatus([actuator1, actuator2], [sensor1, sensor2])
# sets status of actuator 1 to status of sensor1 and
# status of actuator2 to status of sensor2.
class automate.callables.builtin_callables.SetAttr(obj, **kwargs)[source]

Set object’s attributes

Usage:

SetAttr(obj, attr=value, attr2=value2)
# performs setattr(obj, attr, value) and setattr(obj, attr2, value2).
class automate.callables.builtin_callables.Changed(*args, **kwargs)[source]

Is value changed since evaluated last time? If this is the first time this Callable is called (i.e. comparison to last value cannot be made), return True.

Usage:

Changed(sensor1)
class automate.callables.builtin_callables.Swap(*args, **kwargs)[source]

Swap sensor or BinaryActuator status (False to True and True to False)

Usage:

Swap(actuator1)
class automate.callables.builtin_callables.AbstractRunner(*args, **kwargs)[source]

Abstract baseclass for Callables that are used primarily to run other Actions

class automate.callables.builtin_callables.Run(*args, **kwargs)[source]

Run specified Callables one at time. Return always True.

Usage:

Run(callable1, callable2, ...)
class automate.callables.builtin_callables.Delay(*args, **kwargs)[source]

Execute commands delayed by time (in seconds) in separate thread

Usage:

Delay(delay_in_seconds, action)
class automate.callables.builtin_callables.Threaded(*args, **kwargs)[source]

Execute commands in a single thread (in order)

Usage:

Threaded(action)
class automate.callables.builtin_callables.If(*args, **kwargs)[source]

Basic If statement

Usage:

If(x, y, z) # if x, then run y, z, where x, y, and z are Callables or StatusObjects
If(x, y)
class automate.callables.builtin_callables.IfElse(*args, **kwargs)[source]

Basic if - then - else statement

Usage:

IfElse(x, y, z) # if x, then run y, else run z, where x, y,
                # and z are Callables or StatusObjects
IfElse(x, y)
class automate.callables.builtin_callables.Switch(*args, **kwargs)[source]

Basic switch - case statement.

Two alternative usages:

  • First argument switch criterion (integer-valued) and others are cases OR
  • First argument is switch criterion and second argument is dictionary that contains all possible cases as keys and related actions as their values.

Usage:

Switch(criterion, choice1, choice2...) # where criteria is integer-valued
                                       # (Callable or StatusObject etc.)
                                       # and choice1, 2... are Callables.

Switch(criterion, {'value1': callable1, 'value2': 'callable2'})
class automate.callables.builtin_callables.TryExcept(*args, **kwargs)[source]

Try returning x, but if exception occurs in the value evaluation, then return y.

Usage:

Try(x, y) # where x and y are Callables or StatusObjects etc.
class automate.callables.builtin_callables.Min(*args, **kwargs)[source]

Give minimum number of given objects.

Usage:

Min(x, y, z...)
# where x,y,z are anything that can be
# evaluated as number (Callables, Statusobjects etc).
class automate.callables.builtin_callables.Max(*args, **kwargs)[source]

Give maximum number of given objects

Usage:

Max(x, y, z...)
# where x,y,z are anything that can be
# evaluated as number (Callables, Statusobjects etc).
class automate.callables.builtin_callables.Sum(*args, **kwargs)[source]

Give sum of given objects

Usage:

Sum(x, y, z...)
# where x,y,z are anything that can be
# evaluated as number (Callables, Statusobjects etc).
class automate.callables.builtin_callables.Product(*args, **kwargs)[source]

Give product of given objects

Usage:

Product(x, y, z...)
# where x,y,z are anything that can be
# evaluated as number (Callables, Statusobjects etc).
class automate.callables.builtin_callables.Mult(*args, **kwargs)[source]

Synonym of Product

class automate.callables.builtin_callables.Add(*args, **kwargs)[source]

Synonym of Sum

class automate.callables.builtin_callables.AbstractLogical(*args, **kwargs)[source]

Abstract class for logic operations (And, Or etc.)

class automate.callables.builtin_callables.Anything(*args, **kwargs)[source]

Condition which gives True always

Usage:

Anything(x,y,z...)
class automate.callables.builtin_callables.Or(*args, **kwargs)[source]

Or condition

Usage:

Or(x,y,z...) # gives truth value of x or y or z or ,,,
class automate.callables.builtin_callables.And(*args, **kwargs)[source]

And condition

Usage:

And(x,y,z...) # gives truth value of x and y and z and ...
class automate.callables.builtin_callables.Neg(*args, **kwargs)[source]

Give negative of specified callable (minus sign)

Usage:

Neg(x) # returns -x
class automate.callables.builtin_callables.Not(*args, **kwargs)[source]

Give negation of specified object

Usage:

Not(x) # returns not x
class automate.callables.builtin_callables.Equal(*args, **kwargs)[source]

Equality condition, i.e. is x == y

Usage:

Equal(x, y) # returns truth value of x == y
class automate.callables.builtin_callables.Less(*args, **kwargs)[source]

Condition: is x < y

Usage:

Less(x,y) # returns truth value of x < y
class automate.callables.builtin_callables.More(*args, **kwargs)[source]

Condition: is x > y

Usage:

More(x,y) # returns truth value of x > y
class automate.callables.builtin_callables.Value(*args, **kwargs)[source]

Give specified value

Usage:

Value(x) # returns value of x. Used to convert StatusObject into Callable,
         # for example, if StatusObject status needs to be used directly
         # as a condition of Program condition attributes.
class automate.callables.builtin_callables.AbstractQuery(*args, **kwargs)[source]

Baseclass for query type of Callables, i.e. those that return set of objects from system based on given conditions.

class automate.callables.builtin_callables.OfType(*args, **kwargs)[source]

Gives all objects of given type that are found in System

Usage & example:

OfType(type, **kwargs)
OfType(AbstractActuator, exclude=['actuator1', 'actuator2'])
# returns all actuators in system, except those named 'actuator1' and 'actuator2'.
Parameters:exclude (list) – list of instances to be excluded from the returned list.
class automate.callables.builtin_callables.RegexSearch(*args, **kwargs)[source]

Scan through string looking for a match to the pattern. Return matched parts of string by re.search().

Parameters:group (int) – Match group can be chosen by group number.

Usage & examples:

RegexSearch(match_string, content_to_search, **kwargs)

RegexSearch(r'(\d*)(\w*)', '12test')          # returns '12'
RegexSearch(r'(\d*)(\w*)', '12test', group=2) # returns 'test'
RegexSearch(r'testasfd', 'test')              # returns ''

Tip

More examples in unit tests

class automate.callables.builtin_callables.RegexMatch(*args, **kwargs)[source]

Try to apply the pattern at the start of the string. Return matched parts of string by re.match().

Parameters:group (int) – Match group can be chosen by group number.

Usage & examples from unit tests:

RegexMatch(match_string, content_to_search, **kwargs)

RegexMatch(r'heptest', 'heptest')                # returns 'heptest'
RegexMatch(r'heptest1', 'heptest')               # returns ''
RegexMatch(r'(hep)te(st1)', 'heptest1', group=1) # returns 'hep'
RegexMatch(r'(hep)te(st1)', 'heptest1', group=2) # returns 'st1'

Tip

More examples in unit tests

class automate.callables.builtin_callables.RemoteFunc(*args, **kwargs)[source]

Evaluate remote function via XMLRPC.

Usage:

RemoteFunc('host', 'funcname', *args, **kwargs)
class automate.callables.builtin_callables.WaitUntil(*args, **kwargs)[source]

Wait until sensor/actuator/callable status changes to True and then execute commands. WaitUntil will return immediately and only execute specified actions after criteria is fullfilled.

Usage:

WaitUntil(sensor_or_callable, Action1, Action2, etc)

Note

No triggers are collected from WaitUntil

class automate.callables.builtin_callables.While(*args, **kwargs)[source]

Executes commands (in thread) as long as criteria (sensor, actuator, callable status) remains true. Flushes worker queue between each iteration such that criteria is updated, if executed actions alter it.

Parameters:do_after (Callable) – given Callable is executed after while loop is finished.

Usage & example:

While(criteria, action1, action2, do_after=action3)

# Example loop that runs actions 10 times. Assumes s=UserIntSensor()
Run(
    SetStatus(s, 0),
    While(s < 10,
        SetStatus(s, s+1),
        other_actions
    )
)

Note

While execution is performed in separate thread

Note

No triggers are collected from While

class automate.callables.builtin_callables.TriggeredBy(*args, **kwargs)[source]

Return whether action was triggered by one of specified triggers or not

If no arguments, return the trigger.

Usage:

TriggeredBy() # -> returns the trigger
TriggeredBy(trig1, trig2...) #-> Returns if trigger is one of arguments