IoticAgent.ThingRunner module¶

class IoticAgent.ThingRunner.RetryingThingRunner(config=None, retry_timeout=15)¶

Bases: IoticAgent.ThingRunner.ThingRunner

Automatically re-tries on_startup & on_main on network & timeout related failures only.

on_exception(ctx, exc_info)¶

Called when an exception occurs within runner methods (or initialisation). If the return value evalutes to True, the method in question will be re-tried (after retry_timeout seconds wait). Otherwise the exception will be re-raised (the default). Note that KeyboardInterrupt will not result in this method being called and instead cause a shutdown.

ctx One of RunContext. Indicates at what point exception occurred. exc_info Tuple (as for sys.exc_info()) of the exception

class IoticAgent.ThingRunner.RunContext¶

Bases: enum.Enum

Passed to ThingRunner.on_exception

MAIN = 'main'¶

ON_STARTUP = 'on_startup'¶

class IoticAgent.ThingRunner.ThingRunner(config=None, retry_timeout=15)¶

Bases: object

Automates, starting, stopping and running of an Agent instance, either in the foreground (blocking) or background. Create a subclass to use, e.g.:

class MyRunner(ThingRunner):
    # only required if want to add own fields to class instance
    def __init__(self, other, arguments, config=None):
        super(ThingRunner, self).__init__(config=config)
        # own class setup goes here

    def main(self):
        while True:
            # do stuff here

            # end on shutdown request
            if self.wait_for_shutdown(1):
                break

# runs in foreground, blocking
MyRunner('other', 'arguments', config='agent.ini').run()

Optionally implement on_startup or on_shutdown to perform one-off actions at the beginning/end of the agent’s run cycle.

client¶: IoticAgent.IOT.Client module instance in use by this runner

main()¶: Application logic goes here. Should return (or raise exception) to end program run. Should check whether the shutdown_requested property is True an return if this is the case.

on_exception(ctx, exc_info)¶

Called when an exception occurs within runner methods (or initialisation). If the return value evalutes to True, the method in question will be re-tried (after retry_timeout seconds wait). Otherwise the exception will be re-raised (the default). Note that KeyboardInterrupt will not result in this method being called and instead cause a shutdown.

ctx One of RunContext. Indicates at what point exception occurred. exc_info Tuple (as for sys.exc_info()) of the exception

on_shutdown(exc_info)¶: One-off tasks to perform on just before agent shutdown. exc_info is a tuple (as for sys.exc_info()) of the exception which caused the shutdown (from the main() function) or None if the shutdown was graceful. This is useful if one only wants to perform certains tasks on success. This is not called if on_startup() was not successful. It is possible that due to e.g. network problems the agent cannot be used at this point. If the return value evalutes to False, the exception will be re-raised (the default). Note that KeyboardInterrupt will not be passed to this method (but will result in this method being called).

on_startup()¶: One-off tasks to perform straight after agent startup.

run(background=False)¶: Runs on_startup, main and on_shutdown, blocking until finished, unless background is set.

shutdown_requested¶: Whether stop() has been called, an exception has occurred (which does not result in a retry) or the implemented main loop has finished and thus the device should be shutting down.

stop(timeout=None)¶

Requests device to stop running, waiting at most the given timout in seconds (fractional). Has no effect if run() was not called with background=True set.

Returns:	True if successfully stopped (or already not running).

wait_for_shutdown(timeout=None)¶: Blocks until shutdown has been requested (or the timeout has been reached, if specified). False is returned for the latter, True otherwise.