director Package

director Package

director – Manages the evasion processes

Platforms: Unix, MacOSX, Windows

The director provides a number of modules:

config – This supervises then agents under its control.

Platforms: Unix, MacOSX, Windows

This module provides the director configuration parsing and handling.

exception evasion.director.config.ConfigInvalid

Raised when the config doesn’t have the director section or other things we require.

exception evasion.director.config.ConfigNotSetup

Raised when set_cfg hasn’t been called to set up the configuration.

exception evasion.director.config.ConfigError

This is raised for problems with loading and using the configuration.

exception evasion.director.config.ControllerReloadError

Raise by reload_controller for problems it encounters.

class evasion.director.config.ConfigStore(raw, cfg, configobj, filename)

An instance of this is used to store the original raw config and the ConfigObj instance.

The original config data is stored as the ‘raw’ member variable.

The list of configuration objects is stored in the cfg member variable.

The ConfigObj instance is stored as the ‘configobj’ member variable.

The director, broker, agency and webadmin are members which will not be None. These will be set up if the are present in the cfg configuration objects.

findInstances()

Locate director, broker, agency and webadmin instances in the cfg objects and store them as attributes for easy access.

evasion.director.config.clear()

Remove the stored config, this is used mainly by unittesting.

If get_cfg() is called now ConfigNotSetup will be raised.

evasion.director.config.get_cfg()

Called to return a reference to the currenlty set up configuration.

If no config has been set up, via a call to set_config, then ConfigNotSetup will be raised to indicate so.

evasion.director.config.set_cfg(raw, filename='')

Called to set up the configuration used for the project.

Parameters:raw – this is a string representing the raw

configuration data read from the config file.

Parameters:filename – this is a the file name and path

of the original configuration file. This will be used to save or reload the configuration from if needed at a later stage.

evasion.director.config.update_objs(cfg_objs)

Called to updated the current store of config objs.

Parameters:cfg_objs – this is a list of configuration objects

as returned by a call from recover_objects.

This function will typically be done after a load_agents, load_controllers or reload_controller.

If no config has been set up, via a call to set_config, then ConfigNotSetup will be raised to indicate so.

manager – Main director control code.

Platforms: Unix, MacOSX, Windows

class evasion.director.manager.Manager

Manages the running services determined by the configuration that was loaded.

The manager expects to find a [director] section in the configuration. For more on this see director.configobjs.Director doc string.

appmain(isExit)

Run the main program loop.

Parameters:isExit – This is a function that will return true

when its time to exit.

Note: this is a thread which we are running in and the messenger will determine when its time to exit.

appmainSetup()

Called from appmain or from testing to set up the signal handling and other items ready for a run / test run.

Returns:poll_time used by the director as a sleep

between controller checks.

controllerSetup()

Called to load the director configuration from the raw config data. This will then recover and load only the relevant controller sections.

After loading the controllers each one’s setUp will be called, passing it its own local section of the configuration.

The controllers recovered will be stored in the internal controllers member variable.

Returns:None.

exit()

Called after shutdown() to tell twisted to exit causing the program to quit normally.

formatError()

Return a string representing the last traceback.

main(director_testing=False)

The main thread in which twisted and the messagin system runs. The manager main run inside its own thread. The appman(...) is the main of the director.

shutdown()

Shutdown any remaining services and call their tearDown methods.

This is called before exit() is called.

step()

Perform a single pass through the controllers maintenance steps.

This is used by appmain or from the tests.

config Module

config – This supervises then agents under its control.

Platforms: Unix, MacOSX, Windows

This module provides the director configuration parsing and handling.

exception evasion.director.config.ConfigInvalid

Raised when the config doesn’t have the director section or other things we require.

exception evasion.director.config.ConfigNotSetup

Raised when set_cfg hasn’t been called to set up the configuration.

exception evasion.director.config.ConfigError

This is raised for problems with loading and using the configuration.

exception evasion.director.config.ControllerReloadError

Raise by reload_controller for problems it encounters.

class evasion.director.config.ConfigStore(raw, cfg, configobj, filename)

An instance of this is used to store the original raw config and the ConfigObj instance.

The original config data is stored as the ‘raw’ member variable.

The list of configuration objects is stored in the cfg member variable.

The ConfigObj instance is stored as the ‘configobj’ member variable.

The director, broker, agency and webadmin are members which will not be None. These will be set up if the are present in the cfg configuration objects.

findInstances()

Locate director, broker, agency and webadmin instances in the cfg objects and store them as attributes for easy access.

evasion.director.config.clear()

Remove the stored config, this is used mainly by unittesting.

If get_cfg() is called now ConfigNotSetup will be raised.

evasion.director.config.get_cfg()

Called to return a reference to the currenlty set up configuration.

If no config has been set up, via a call to set_config, then ConfigNotSetup will be raised to indicate so.

evasion.director.config.set_cfg(raw, filename='')

Called to set up the configuration used for the project.

Parameters:raw – this is a string representing the raw

configuration data read from the config file.

Parameters:filename – this is a the file name and path

of the original configuration file. This will be used to save or reload the configuration from if needed at a later stage.

evasion.director.config.update_objs(cfg_objs)

Called to updated the current store of config objs.

Parameters:cfg_objs – this is a list of configuration objects

as returned by a call from recover_objects.

This function will typically be done after a load_agents, load_controllers or reload_controller.

If no config has been set up, via a call to set_config, then ConfigNotSetup will be raised to indicate so.

exception evasion.director.config.ConfigError

Bases: exceptions.Exception

This is raised for problems with loading and using the configuration.

exception evasion.director.config.ConfigInvalid

Bases: exceptions.Exception

Raised when the config doesn’t have the director section or other things we require.

exception evasion.director.config.ConfigNotSetup

Bases: exceptions.Exception

Raised when set_cfg hasn’t been called to set up the configuration.

class evasion.director.config.ConfigStore(raw, cfg, configobj, filename)

An instance of this is used to store the original raw config and the ConfigObj instance.

The original config data is stored as the ‘raw’ member variable.

The list of configuration objects is stored in the cfg member variable.

The ConfigObj instance is stored as the ‘configobj’ member variable.

The director, broker, agency and webadmin are members which will not be None. These will be set up if the are present in the cfg configuration objects.

findInstances()

Locate director, broker, agency and webadmin instances in the cfg objects and store them as attributes for easy access.

exception evasion.director.config.ControllerReloadError

Bases: exceptions.Exception

Raise by reload_controller for problems it encounters.

evasion.director.config.clear()

Remove the stored config, this is used mainly by unittesting.

If get_cfg() is called now ConfigNotSetup will be raised.

evasion.director.config.export_configuration()

Called to return the get_cfg() in a form that can travel i.e. pickle

Returns:

returned = dict(

cfg = [..list of controller dicts from export call..], filename = ‘..name and path of config..’, director = ‘’ | director.export(), agency = ‘’ | agency.export(), broker = ‘’ | broker.export(), webadmin = ‘’ | webadmin.export(),

)

evasion.director.config.get_cfg()

Called to return a reference to the currenlty set up configuration.

If no config has been set up, via a call to set_config, then ConfigNotSetup will be raised to indicate so.

evasion.director.config.get_log()

evasion.director.config.import_module(import_type, obj)

Called to import a module as recovered from the agent or controller attribute.

Parameters:import_type – ‘agent’ or ‘controller’

The agent or controller attributes must contain the absolute import path. I.e <mypackage>.<mymodule>

The import must contain a class called Agent or Controller.

evasion.director.config.load_agents(config_objs)

Called to test and then load the agents from the configuration.

If the [agency] is disabled then no agents will be present to load. The agency is enabled by default, so any agents entries will be present in the agency’s agents member.

config_objs:

This is a list as returned by recover_objects()

returned:

This returns a list of config containers loaded with the entries recovered from the device’s section.

evasion.director.config.load_controllers(config_objs, ignore_exceptions=False)

Called to test and then load the controllers from the configuration.

Parameters:

• config_objs – This is a list as returned by recover_objects()
• ignore_exceptions – True means a module will be ignored if it causes an exception will being loaded.

Note: the broker, agency and webadmin are also considered controllers in addition to the explicit controllers.

returned:

This returns the given config_objs with the mod field of each controller entry updated with the imported module.

evasion.director.config.recover_objects(config)

Called to walk through the configuration and convert the sections into their equivalent configobjs.

This function does not attempt to import any modules, it simply creates the main containers. The load_modules() function does this on this functions output.

Parameters:config – This is a string representing the contents

of the configuration file.

returned:

A list of configuration objects which with the default ordering will usually contain

returned = [

Director instance, Broker instance, Agency instance, WebAdmin instance, : other controllers in there order

]

The Agency will contain the list of agents as part of its agents member and these will be ordered by defaults or by the order attribute if it was used.

ConfigError will be raised if the configuration contains two sections with the same name.

If the configuration does not contain the [director] section the ConfigError will be raised.

evasion.director.config.reload_controller(name, new_config)

Called replace a controller entry and (re)load the controller based on

Params name:This is the string section name as

found in the configuration which is also the controller name.

Params new_config:  This is any valid dict representing

a valid entry as a controller. For Example:

new_config = dict(
        order = 4,
        name = "mycontroller",
        disabled = 'no',
        controller = 'mypackage.mycontroller2'
        :
        user args
    )

Returns:None

The system wide configuration will have been updated with the new controller.

evasion.director.config.save_cfg(filename=None)

Called to write the configuration to disk after updating the internal configobj instance.

evasion.director.config.set_cfg(raw, filename='')

Called to set up the configuration used for the project.

Parameters:raw – this is a string representing the raw

configuration data read from the config file.

Parameters:filename – this is a the file name and path

of the original configuration file. This will be used to save or reload the configuration from if needed at a later stage.

evasion.director.config.update_objs(cfg_objs)

Called to updated the current store of config objs.

Parameters:cfg_objs – this is a list of configuration objects

as returned by a call from recover_objects.

This function will typically be done after a load_agents, load_controllers or reload_controller.

If no config has been set up, via a call to set_config, then ConfigNotSetup will be raised to indicate so.

configobjs Module

configobjs – Provides objects that represent config sections

Platforms: Unix, MacOSX, Windows

This module provides the director configuration parsing and handling.

class evasion.director.configobjs.Director

This represents a director section as recovered from the configuration section.

A config section can have the following options:

[director]
# The broker connection details. Required if disable_broker = 'no' (default):
msg_host = "127.0.0.1"
# If internal_broker is 'yes' then this will also be the port
# the internal_broker binds to listen on:
msg_port = 61613
msg_username = ''
msg_password = ''
msg_channel = 'evasion'
msg_interface = '127.0.0.1'

# Start a light weight broker running as part of the
# director process. This simplies certain installs
internal_broker = 'yes'

# (OPTIONAL): Set this to 'yes' if you wish to stop the director connecting to the broker.
disable_broker = 'no'

# (OPTIONAL) Prevent director busy waiting. This just limits the time between maintenances checks.
# This is in seconds or fractions of seconds, the default being 0.1s.
poll_time = 1

# (OPTIONAL): To disable the special proxy dispatch set this to 'yes'
noproxydispatch = 'no'

# (OPTIONAL): Web app local reply dispatch XML-RPC service i.e. http://localhost:<this port>/RPC2.
proxy_dispatch_port = 1901

# (OPTIONAL): This is the option web interface to be used if webadmin is used.
webadmin = 'director.webadmin'

# Notes:
#
# The director has an implicit order of 0
# order = 0
#
# Other customer configuration can also be put in each
# section. I just look for the above alone and ignore
# anything else.

export()

Called to return an exportable dict representing this object

class evasion.director.configobjs.Broker

This represents a broker section as recovered from the configuration.

A config section can have the following options:

[broker]
# OPTIONAL: This is the order in which it will be started.
# The default is 1 to come after the directors implicit 0.
order = 1

# OPTIONAL: The broker is using the command line controller
# for the moment. The controller/command/workingdir are args
# for the commandline controller. In future the broker may
# run as a thread under the director.
#
controller = 'evasion.director.controllers.commandline'
command = "morbidsvr -p 61613 -i 127.0.0.1"
workingdir = ""

# OPTIONAL: disable the start/stop of the controller. It will
# still be loaded and created.
disabled = 'yes' | 'no'

export()

Called to return an exportable dict representing this object

class evasion.director.configobjs.WebAdmin

This represents a broker section as recovered from the configuration.

A config section can have the following options:

[webadmin]
# OPTIONAL: This is the order in which it will be started.
order = 3

# OPTIONAL: disable the start/stop of the controller. It will
# still be loaded and created.
disabled = 'yes' | 'no'

class evasion.director.configobjs.Controller

This represents a controller section as recovered from the configuration section.

A config section can have the following options:

[name]
# Order in which to start programs (must be unique)
# order = 10+

# The python path to agent to import e.g.
controller = 'evasion.director.controllers.program'

# OPTIONAL: disable the start/stop of the controller. It will
# still be loaded and created.
disabled = 'yes' | 'no'

# Other customer configuration can also be put in each
# section. I just look for the above alone and ignore
# anything else.

class evasion.director.configobjs.Agent

This represents an agent configuration section as recoverd from the agent configuration.

A config section can have the following options:

[name]
# The python path to agent to import For example
agent = 'evasion.agency.testing.fake'

# A category from agency.AGENT_CATEGORIES
cat = 'general'

# OPTIONAL: the order in which the agent will be
# started. By default it will be given an order
# based on when it was recoverd.
# order = 1+

# OPTIONAL: a unique number which can be used instead of name
# to refer to this agent.
alias = 1

# OPTIONAL: disable the setup/tearDown/start/stop of the
# agent. It will still be loaded and created.
disabled = 'yes' | 'no'

export()

Called to return an exportable dict representing this object

class evasion.director.configobjs.Agency

Bases: evasion.director.configobjs.Base

This represents the Agency configuration as recoverd from the configuration.

A config section can have the following options:

[agency]
order = 2

# OPTIONAL: This is the default controller for the agency
controller = 'evasion.director.controllers.agencyctrl'

# OPTIONAL: disable the setup/tearDown/start/stop of the
# agent. It will still be loaded and created.
disabled = 'yes' | 'no'

Note: the ‘agents’ member will contain a list agent instances recovered.

export()

Called to return an exportable dict representing this object

class evasion.director.configobjs.Agent

Bases: evasion.director.configobjs.Base

This represents an agent configuration section as recoverd from the agent configuration.

A config section can have the following options:

[name]
# The python path to agent to import For example
agent = 'evasion.agency.testing.fake'

# A category from agency.AGENT_CATEGORIES
cat = 'general'

# OPTIONAL: the order in which the agent will be
# started. By default it will be given an order
# based on when it was recoverd.
# order = 1+

# OPTIONAL: a unique number which can be used instead of name
# to refer to this agent.
alias = 1

# OPTIONAL: disable the setup/tearDown/start/stop of the
# agent. It will still be loaded and created.
disabled = 'yes' | 'no'

export()

Called to return an exportable dict representing this object

class evasion.director.configobjs.Base

Bases: object

This is the base for all objects converted to from configuration sections.

export()

Called to return an exportable dict representing this object

validate()

Called to check that all the required fields have been provided.

If one or more aren’t provided then SectionError will be raised to indicate so.

class evasion.director.configobjs.Broker

Bases: evasion.director.configobjs.Base

This represents a broker section as recovered from the configuration.

A config section can have the following options:

[broker]
# OPTIONAL: This is the order in which it will be started.
# The default is 1 to come after the directors implicit 0.
order = 1

# OPTIONAL: The broker is using the command line controller
# for the moment. The controller/command/workingdir are args
# for the commandline controller. In future the broker may
# run as a thread under the director.
#
controller = 'evasion.director.controllers.commandline'
command = "morbidsvr -p 61613 -i 127.0.0.1"
workingdir = ""

# OPTIONAL: disable the start/stop of the controller. It will
# still be loaded and created.
disabled = 'yes' | 'no'

export()

Called to return an exportable dict representing this object

class evasion.director.configobjs.Controller

Bases: evasion.director.configobjs.Base

This represents a controller section as recovered from the configuration section.

A config section can have the following options:

[name]
# Order in which to start programs (must be unique)
# order = 10+

# The python path to agent to import e.g.
controller = 'evasion.director.controllers.program'

# OPTIONAL: disable the start/stop of the controller. It will
# still be loaded and created.
disabled = 'yes' | 'no'

# Other customer configuration can also be put in each
# section. I just look for the above alone and ignore
# anything else.

class evasion.director.configobjs.Director

Bases: evasion.director.configobjs.Base

This represents a director section as recovered from the configuration section.

A config section can have the following options:

[director]
# The broker connection details. Required if disable_broker = 'no' (default):
msg_host = "127.0.0.1"
# If internal_broker is 'yes' then this will also be the port
# the internal_broker binds to listen on:
msg_port = 61613
msg_username = ''
msg_password = ''
msg_channel = 'evasion'
msg_interface = '127.0.0.1'

# Start a light weight broker running as part of the
# director process. This simplies certain installs
internal_broker = 'yes'

# (OPTIONAL): Set this to 'yes' if you wish to stop the director connecting to the broker.
disable_broker = 'no'

# (OPTIONAL) Prevent director busy waiting. This just limits the time between maintenances checks.
# This is in seconds or fractions of seconds, the default being 0.1s.
poll_time = 1

# (OPTIONAL): To disable the special proxy dispatch set this to 'yes'
noproxydispatch = 'no'

# (OPTIONAL): Web app local reply dispatch XML-RPC service i.e. http://localhost:<this port>/RPC2.
proxy_dispatch_port = 1901

# (OPTIONAL): This is the option web interface to be used if webadmin is used.
webadmin = 'director.webadmin'

# Notes:
#
# The director has an implicit order of 0
# order = 0
#
# Other customer configuration can also be put in each
# section. I just look for the above alone and ignore
# anything else.

export()

Called to return an exportable dict representing this object

exception evasion.director.configobjs.SectionError

Bases: exceptions.Exception

This is raised for problems with loading and using the configuration.

class evasion.director.configobjs.WebAdmin

Bases: evasion.director.configobjs.Base

This represents a broker section as recovered from the configuration.

A config section can have the following options:

[webadmin]
# OPTIONAL: This is the order in which it will be started.
order = 3

# OPTIONAL: disable the start/stop of the controller. It will
# still be loaded and created.
disabled = 'yes' | 'no'

events Module

helper Module

lockabledict Module

class evasion.director.lockabledict.LockableDict

A dictionary with locking. ‘nuff said

Uses threading.Lock to make itself more thread safe.

This dictionary is intended for use when multiple append/del/get actions will be done by various threads.

has_key(key)

keys()

values()

manager Module

manager – Main director control code.

Platforms: Unix, MacOSX, Windows

class evasion.director.manager.Manager

Manages the running services determined by the configuration that was loaded.

The manager expects to find a [director] section in the configuration. For more on this see director.configobjs.Director doc string.

appmain(isExit)

Run the main program loop.

Parameters:isExit – This is a function that will return true

when its time to exit.

Note: this is a thread which we are running in and the messenger will determine when its time to exit.

appmainSetup()

Called from appmain or from testing to set up the signal handling and other items ready for a run / test run.

Returns:poll_time used by the director as a sleep

between controller checks.

controllerSetup()

Called to load the director configuration from the raw config data. This will then recover and load only the relevant controller sections.

After loading the controllers each one’s setUp will be called, passing it its own local section of the configuration.

The controllers recovered will be stored in the internal controllers member variable.

Returns:None.

exit()

Called after shutdown() to tell twisted to exit causing the program to quit normally.

formatError()

Return a string representing the last traceback.

main(director_testing=False)

The main thread in which twisted and the messagin system runs. The manager main run inside its own thread. The appman(...) is the main of the director.

shutdown()

Shutdown any remaining services and call their tearDown methods.

This is called before exit() is called.

step()

Perform a single pass through the controllers maintenance steps.

This is used by appmain or from the tests.

class evasion.director.manager.Manager

Bases: object

Manages the running services determined by the configuration that was loaded.

The manager expects to find a [director] section in the configuration. For more on this see director.configobjs.Director doc string.

appmain(isExit)

Run the main program loop.

Parameters:isExit – This is a function that will return true

when its time to exit.

Note: this is a thread which we are running in and the messenger will determine when its time to exit.

appmainSetup()

Called from appmain or from testing to set up the signal handling and other items ready for a run / test run.

Returns:poll_time used by the director as a sleep

between controller checks.

controllerSetup()

Called to load the director configuration from the raw config data. This will then recover and load only the relevant controller sections.

After loading the controllers each one’s setUp will be called, passing it its own local section of the configuration.

The controllers recovered will be stored in the internal controllers member variable.

Returns:None.

exit()

Called after shutdown() to tell twisted to exit causing the program to quit normally.

formatError()

Return a string representing the last traceback.

main(director_testing=False)

The main thread in which twisted and the messagin system runs. The manager main run inside its own thread. The appman(...) is the main of the director.

shutdown()

Shutdown any remaining services and call their tearDown methods.

This is called before exit() is called.

step()

Perform a single pass through the controllers maintenance steps.

This is used by appmain or from the tests.

evasion.director.manager.get_log()

morbid Module

class evasion.director.morbid.Queue(name)

Bases: object

empty()

send(headers, body)

subscribe(proto)

unsubscribe(proto)

class evasion.director.morbid.StompFactory

Bases: twisted.internet.protocol.Factory

connected(proto)

disconnected(proto)

protocol

alias of StompProtocol

send(dest_name, body, headers={})

subscribe(proto, name)

unsubscribe(proto, name)

class evasion.director.morbid.StompProtocol

Bases: twisted.internet.protocol.Protocol

connectionLost(reason)

dataReceived(data)

frame_disconnect(headers, body)

frame_send(headers, body)

frame_subscribe(headers, body)

frame_unsubscribe(headers, body)

read_connected(cmd, headers, body)

read_initial(cmd, headers, body)

sendError(e)

sendFrame(cmd, headers, body)

class evasion.director.morbid.Topic(name)

Bases: object

empty()

send(headers, body)

subscribe(proto)

unsubscribe(proto)

evasion.director.morbid.main()

evasion.director.morbid.setup(reactor, port, interface)

Create a listenTCP entry in the reactor, which if twisted is running will start the stomp broker handling client connections.

Parameters:

• reactor – twisted reactor.
• port – TCP port on which to listen.
• interface – The interface on which to bind.

proxydispatch Module

class evasion.director.proxydispatch.XmlRpcServer

xmlrpc_dispatch(reply_evt, data)

Dispatch the given data as a reply event.

xmlrpc_exitall()

Sends a EVT_DIRECTOR_EXIT_ALL which will tell the director to shut all parts down in an orderly fashion.

xmlrpc_ping()

Allow others to check we’re running.

xmlrpc_viewpoint_shutdown()

Broadcasts a EVT_VIEWPOINT_SHUTDOWN message if anyone is listening they will react.

xmlrpc_viewpoint_startup()

Broadcasts a EVT_VIEWPOINT_STARTUP message if anyone is listening they will react.

evasion.director.proxydispatch.setup(port, testing=False)

signals Module

signals – Signals handled by the director

Platforms: Unix, MacOSX, Windows

class evasion.director.signals.SignalTimeout

Raise by the SignalsSender when no reponse has been receieved to a signal within a certain period of time.

class evasion.director.signals.SignalsReceiver(manager)

This class is used by the director’s Manager to implement behaviour in reponse to signals/events we receive locally or remotely over the message bus.

formatError()

Return a string representing the last traceback.

resultDict(data, result='ok')

Return an empty signal response which will be filled out

Parameters:

• result – ‘ok’ or ‘error’
• data – any given data type that can be pickled.

Returns:

dict(result=result, data=data)

setup()

Called to set up the signal handlers which subscribe to all the events this class currently supports.

signalConfiguration(signal, sender, **data)

Called to handle the EVT_DIRECTOR_CONFIGURATION signal, which is used to return the current director configuration.

Parameters:data[‘data] – None Returns:a call result dict.

rc[‘result’] = ‘ok’ | ‘error’

For ok result:

rc[‘data’] = [...]

For error result:

rc[‘data’] = ‘Error / Exception message’

Event Dispatched: EVT_DIRECTOR_CONFIGURATION

signalControllerReload(signal, sender, **data)

Called to handle the EVT_DIRECTOR_CTRLRELOAD signal, which is used to return the result of a stop command.

Parameters:data[‘data] – This will contain the name and

new configuration dict to use.

Returns:a call result dict.

rc[‘result’] = ‘ok’ | ‘error’

For ok result:

rc[‘data’] = ‘’

For error result:

rc[‘data’] = ‘Error / Exception message’

Note: this will stop and tearDown the current controller mod. The new mod will be (re)loaded and recreated based on the new config dict given.

Event Dispatched: EVT_DIRECTOR_CTRLRELOAD

signalControllerStart(signal, sender, **data)

Called to handle the EVT_DIRECTOR_CTRLSTART signal, which is used to return the result of a start command.

Parameters:data[‘data] – This will contain the name of the

controller to be started. This name is the same name as that in the configuration section.

Returns:a call result dict.

rc[‘result’] = ‘ok’ | ‘error’

For ok result:

rc[‘data’] = ‘’

For error result:

rc[‘data’] = ‘Error / Exception message’

Note: this will contain every controller except the director controller.

Event Dispatched: EVT_DIRECTOR_CTRLSTART

signalControllerState(signal, sender, **data)

Called to handle the EVT_DIRECTOR_CTRLSTATE signal, which is used to return the state of all controllers listed in the configuration.

Param :None Returns:a call result dict.

rc[‘result’] = ‘ok’ | ‘error’

For ok result:

rc[‘data’] = [

dict(name=’..name..’, disabled=’no’|’yes’, started=False | True, config={...}), : etc

]

For error result:

rc[‘data’] = ‘Error / Exception message’

Note: this will contain every controller except the director controller.

Event Dispatched: EVT_DIRECTOR_CTRLSTATE

signalControllerStop(signal, sender, **data)

Called to handle the EVT_DIRECTOR_CTRLSTOP signal, which is used to return the result of a stop command.

Parameters:data[‘data] – This will contain the name of the

controller to be started. This name is the same name as that in the configuration section.

Returns:a call result dict.

rc[‘result’] = ‘ok’ | ‘error’

For ok result:

rc[‘data’] = ‘’

For error result:

rc[‘data’] = ‘Error / Exception message’

Note: this will contain every controller except the director controller.

Event Dispatched: EVT_DIRECTOR_CTRLSTOP

signalExit(signal, sender, **data)

Called to handle the EVT_DIRECTOR_EXIT_ALL signal, which tells the director to shutdown normally.

signalPing(signal, sender, **data)

Called to handle the EVT_DIRECTOR_PING signal, which is used by other to see if the director is present and responding to signals.

Parameters:data[‘data] – should contain some string the callee

wished to receive back. If the SignalsSender.ping() was called then this will be a uuid string. The ping function will warn if the same uuid is not returned.

Returns:a call result dict.

rc[‘result’] = ‘ok’

rc[‘data’] = the token we were given.

class evasion.director.signals.SignalsSender

This class implements the API others can use to talk to the director via signals. This API hides the lower level details of sending and waiting for replies from the end user.

configuration(timeout=60)

Called to return the director configuration.

Parameters:timeout – This is the amount of time (in seconds)

used to wait for the director to respond. If a response isn’t received within this then SignalTimeout will be raised.

Returns:See SignalReceiver configuration.

Event Dispatched: EVT_DIRECTOR_CONFIGURATION

controllerReload(name, new_config, timeout=60)

Called to tell a controller reload and use the new configuration.

This will stop it if its running, tear it down and replace it with whatever the new_config contains.

Parameters:name – This will contain the name of the controller

to be started. This name is the same name as that in the configuration section.

Parameters:new_config – This is any valid controller

configuration

Parameters:timeout – This is the amount of time (in seconds)

used to wait for the director to respond. If a response isn’t received within this then SignalTimeout will be raised.

Returns:See SignalReceiver controllerReload.

Event Dispatched: EVT_DIRECTOR_CTRLRELOAD

controllerStart(name, timeout=60)

Called to tell a controller to start running.

Parameters:name – This will contain the name of the controller

to be started. This name is the same name as that in the configuration section.

Parameters:timeout – This is the amount of time (in seconds)

used to wait for the director to respond. If a response isn’t received within this then SignalTimeout will be raised.

Returns:See SignalReceiver controllerStart.

Event Dispatched: EVT_DIRECTOR_CTRLSTART

controllerState(timeout=60)

Called to return the state of all controllers listed in the configuration.

Parameters:timeout – This is the amount of time (in seconds)

used to wait for the director to respond. If a response isn’t received within this then SignalTimeout will be raised.

Returns:See SignalReceiver controllerState.

Event Dispatched: EVT_DIRECTOR_CTRLSTATE

controllerStop(name, timeout=60)

Called to tell a controller to stop running.

Parameters:name – This will contain the name of the controller

to be started. This name is the same name as that in the configuration section.

Parameters:timeout – This is the amount of time (in seconds)

used to wait for the director to respond. If a response isn’t received within this then SignalTimeout will be raised.

Returns:See SignalReceiver controllerStop.

Event Dispatched: EVT_DIRECTOR_CTRLSTOP

exitAll(timeout=10)

Called to tell the director to shutdown stopped ALL controllers and child processes.

Parameters:timeout – This is the amount of time (in seconds)

used to wait for the director to respond. If a response isn’t received within this then SignalTimeout will be raised.

Event Dispatched: EVT_DIRECTOR_EXIT_ALL

ping(timeout=10, testing=None)

Called to check if the director is actually there and responding, otherwise we could be waiting forever for nothing to happen.

Parameters:timeout – This is the amount of time (in seconds)

used to wait for the director to respond. If a response isn’t received within this then SignalTimeout will be raised.

Event Dispatched: EVT_DIRECTOR_PING

exception evasion.director.signals.SignalTimeout

Bases: exceptions.Exception

Raise by the SignalsSender when no reponse has been receieved to a signal within a certain period of time.

class evasion.director.signals.SignalsReceiver(manager)

Bases: object

This class is used by the director’s Manager to implement behaviour in reponse to signals/events we receive locally or remotely over the message bus.

formatError()

Return a string representing the last traceback.

resultDict(data, result='ok')

Return an empty signal response which will be filled out

Parameters:

• result – ‘ok’ or ‘error’
• data – any given data type that can be pickled.

Returns:

dict(result=result, data=data)

setup()

Called to set up the signal handlers which subscribe to all the events this class currently supports.

signalConfiguration(signal, sender, **data)

Called to handle the EVT_DIRECTOR_CONFIGURATION signal, which is used to return the current director configuration.

Parameters:data[‘data] – None Returns:a call result dict.

rc[‘result’] = ‘ok’ | ‘error’

For ok result:

rc[‘data’] = [...]

For error result:

rc[‘data’] = ‘Error / Exception message’

Event Dispatched: EVT_DIRECTOR_CONFIGURATION

signalControllerReload(signal, sender, **data)

Called to handle the EVT_DIRECTOR_CTRLRELOAD signal, which is used to return the result of a stop command.

Parameters:data[‘data] – This will contain the name and

new configuration dict to use.

Returns:a call result dict.

rc[‘result’] = ‘ok’ | ‘error’

For ok result:

rc[‘data’] = ‘’

For error result:

rc[‘data’] = ‘Error / Exception message’

Note: this will stop and tearDown the current controller mod. The new mod will be (re)loaded and recreated based on the new config dict given.

Event Dispatched: EVT_DIRECTOR_CTRLRELOAD

signalControllerStart(signal, sender, **data)

Called to handle the EVT_DIRECTOR_CTRLSTART signal, which is used to return the result of a start command.

Parameters:data[‘data] – This will contain the name of the

controller to be started. This name is the same name as that in the configuration section.

Returns:a call result dict.

rc[‘result’] = ‘ok’ | ‘error’

For ok result:

rc[‘data’] = ‘’

For error result:

rc[‘data’] = ‘Error / Exception message’

Note: this will contain every controller except the director controller.

Event Dispatched: EVT_DIRECTOR_CTRLSTART

signalControllerState(signal, sender, **data)

Called to handle the EVT_DIRECTOR_CTRLSTATE signal, which is used to return the state of all controllers listed in the configuration.

Param :None Returns:a call result dict.

rc[‘result’] = ‘ok’ | ‘error’

For ok result:

rc[‘data’] = [

dict(name=’..name..’, disabled=’no’|’yes’, started=False | True, config={...}), : etc

]

For error result:

rc[‘data’] = ‘Error / Exception message’

Note: this will contain every controller except the director controller.

Event Dispatched: EVT_DIRECTOR_CTRLSTATE

signalControllerStop(signal, sender, **data)

Called to handle the EVT_DIRECTOR_CTRLSTOP signal, which is used to return the result of a stop command.

Parameters:data[‘data] – This will contain the name of the

controller to be started. This name is the same name as that in the configuration section.

Returns:a call result dict.

rc[‘result’] = ‘ok’ | ‘error’

For ok result:

rc[‘data’] = ‘’

For error result:

rc[‘data’] = ‘Error / Exception message’

Note: this will contain every controller except the director controller.

Event Dispatched: EVT_DIRECTOR_CTRLSTOP

signalExit(signal, sender, **data)

Called to handle the EVT_DIRECTOR_EXIT_ALL signal, which tells the director to shutdown normally.

signalPing(signal, sender, **data)

Called to handle the EVT_DIRECTOR_PING signal, which is used by other to see if the director is present and responding to signals.

Parameters:data[‘data] – should contain some string the callee

wished to receive back. If the SignalsSender.ping() was called then this will be a uuid string. The ping function will warn if the same uuid is not returned.

Returns:a call result dict.

rc[‘result’] = ‘ok’

rc[‘data’] = the token we were given.

class evasion.director.signals.SignalsSender

Bases: object

This class implements the API others can use to talk to the director via signals. This API hides the lower level details of sending and waiting for replies from the end user.

configuration(timeout=60)

Called to return the director configuration.

Parameters:timeout – This is the amount of time (in seconds)

used to wait for the director to respond. If a response isn’t received within this then SignalTimeout will be raised.

Returns:See SignalReceiver configuration.

Event Dispatched: EVT_DIRECTOR_CONFIGURATION

controllerReload(name, new_config, timeout=60)

Called to tell a controller reload and use the new configuration.

This will stop it if its running, tear it down and replace it with whatever the new_config contains.

Parameters:name – This will contain the name of the controller

to be started. This name is the same name as that in the configuration section.

Parameters:new_config – This is any valid controller

configuration

Parameters:timeout – This is the amount of time (in seconds)

used to wait for the director to respond. If a response isn’t received within this then SignalTimeout will be raised.

Returns:See SignalReceiver controllerReload.

Event Dispatched: EVT_DIRECTOR_CTRLRELOAD

controllerStart(name, timeout=60)

Called to tell a controller to start running.

Parameters:name – This will contain the name of the controller

to be started. This name is the same name as that in the configuration section.

Parameters:timeout – This is the amount of time (in seconds)

used to wait for the director to respond. If a response isn’t received within this then SignalTimeout will be raised.

Returns:See SignalReceiver controllerStart.

Event Dispatched: EVT_DIRECTOR_CTRLSTART

controllerState(timeout=60)

Called to return the state of all controllers listed in the configuration.

Parameters:timeout – This is the amount of time (in seconds)

used to wait for the director to respond. If a response isn’t received within this then SignalTimeout will be raised.

Returns:See SignalReceiver controllerState.

Event Dispatched: EVT_DIRECTOR_CTRLSTATE

controllerStop(name, timeout=60)

Called to tell a controller to stop running.

Parameters:name – This will contain the name of the controller

to be started. This name is the same name as that in the configuration section.

Parameters:timeout – This is the amount of time (in seconds)

used to wait for the director to respond. If a response isn’t received within this then SignalTimeout will be raised.

Returns:See SignalReceiver controllerStop.

Event Dispatched: EVT_DIRECTOR_CTRLSTOP

exitAll(timeout=10)

Called to tell the director to shutdown stopped ALL controllers and child processes.

Parameters:timeout – This is the amount of time (in seconds)

used to wait for the director to respond. If a response isn’t received within this then SignalTimeout will be raised.

Event Dispatched: EVT_DIRECTOR_EXIT_ALL

ping(timeout=10, testing=None)

Called to check if the director is actually there and responding, otherwise we could be waiting forever for nothing to happen.

Parameters:timeout – This is the amount of time (in seconds)

used to wait for the director to respond. If a response isn’t received within this then SignalTimeout will be raised.

Event Dispatched: EVT_DIRECTOR_PING

testing Module

testing – This provides some handy testing controllers.

Platforms: Unix, MacOSX, Windows

class evasion.director.testing.FakeViewpoint(uri)

This provides a ‘viewpoint’ signal handler you can use in test to receive events that would normally be handled by the evasion-viewpoint.

onGetUri(signal, sender, **kw)

Call to handle the VIEWPOINT_GET_URI event.

onReplace(signal, sender, **kw)

Call to handle the VIEWPOINT_REPLACE event.

onSetUri(signal, sender, **kw)

Call to handle the VIEWPOINT_SET_URI event.

reply(messenger_event, data)

Called to handle the reply for a VIEWPOINT_* command event.

class evasion.director.testing.FakeViewpoint(uri)

Bases: object

This provides a ‘viewpoint’ signal handler you can use in test to receive events that would normally be handled by the evasion-viewpoint.

onGetUri(signal, sender, **kw)

Call to handle the VIEWPOINT_GET_URI event.

onReplace(signal, sender, **kw)

Call to handle the VIEWPOINT_REPLACE event.

onSetUri(signal, sender, **kw)

Call to handle the VIEWPOINT_SET_URI event.

reply(messenger_event, data)

Called to handle the reply for a VIEWPOINT_* command event.

evasion.director.testing.director_setup(test_config, **kw)

Create a director manager instance which can be used from unit/acceptance/functional tests.

Parameters:test_config – this is a valid director config

string as you would have in its config file.

Returns:A instance of director.manager:Manager

evasion.director.testing.setup_broker(port=61613, interface='127.0.0.1')

Called to start the internal broker listening via twisted’s reactor.

Parameters:

• port – TCP port to listen on (default 61613)
• interface – The interface to bind to (default

127.0.0.1):

Returns:This returns a listening port instance

on which deferred = listener.stopListening() can be called.

Ref: http://twistedmatrix.com/documents/8.2.0/api/twisted.internet.interfaces.IReactorTCP.listenTCP.html

utils Module

evasion.director.utils.log_init(level)

Used mainly in testing to create a default catch all logging set up

This set up catches all channels regardless of whether they are in other projects or in our own project.

viewpointcontrol Module

This module provides an interface to the XUL control viewpoint. This version of the viewpoint is on the message bus and is controlled via events. To hide some of the complexity involved and provide a series of easy to use functions, similar to those available in the viewpoint direct module.

Oisin Mulvihill 2009-11-05

class evasion.director.viewpointcontrol.BrowserCalls

Bases: object

This instructs the browser to act on instructions via the message bus.

This class is used in conjection with the ‘viewpointxulcontrol’. This module is the ‘other side’ of the message bus and sets up the event handlers we send to.

getBrowserUri()

Called to recover where the viewpoint browser is looking currently.

This method sends the VIEWPOINT_GET_URI event and returns its response.

replaceContent(content_id, content)

Called to replace content inside the viewpoint browser with the given content fragment.

This method sends the VIEWPOINT_REPLACE event along with the content_id & content returning its response.

setBrowserUri(uri)

Called to the viewpoint browser which URI to load.

This method sends the VIEWPOINT_SET_URI event along with the new_uri and returns its response.

viewpointQuit()

Called to instruct the viewpoint to close and exit normally.

This method sends the VIEWPOINT_QUIT event.

viewpointdirect Module

exception evasion.director.viewpointdirect.BrowserCallReplyTimeout

Bases: exceptions.Exception

Raised when the call callBrowserWaitReply() when the timeout for a reply occurs.

exception evasion.director.viewpointdirect.BrowserNotPresent

Bases: exceptions.Exception

Raised when the call callBrowserWaitReply() cannot connect to the browser/viewpoint control port.

class evasion.director.viewpointdirect.DirectBrowserCalls(port=7055, interface='127.0.0.1')

Bases: object

This directly instructs the browser to act on instructions via its control port 7055 (default).

browserQuit(replyto='no-one')

Called to recover where the browser is looking currently.

callBrowserWaitReply(sessionid, call_str, timeout=180)

Call the browser and set up the callback handler on which we will receive the browser’s response.

call_str:

This must be a valid javascript call in web page which viewpoint is currently displaying.

timeout:

The amount of seconds to wait before giving up on a response.

Note:

If no reponse is received within timeout seconds then a messenger.EventTimeout will be raised.

callFunction(args, replyto='no-one')

Call a javascript function in the browser.

getBrowserUri(replyto='no-one')

Called to recover where the browser is looking currently.

newSessionId()

Generate a sessionid for a callBrowserWaitReply.

This is used to generate the reply_<...> call back and passed as the first argument to the javascript function.

replaceContent(content_id, content, replyto='no-one')

Called to replace content inside the viewpoint browser window with the given content fragment.

setBrowserUri(args, replyto='no-one')

Called to tell the XUL Browser where to point

update(port, interface)

Update the direct browser communications details for a different location.

port:

This is the viewpoint TCP port (default: 7055)

interface:

This is the viewpoint interface (default: ‘127.0.0.1’)

waitForReady(retries=0, retry_period=5.0)

Called to wait until the viewpoint interface is ready on the host and port.

retries: (default: 0)

The number of attempts before giving up on connecting to the browser.

If this is 0 then we will wait forever for the browser to appear.

retry_period: (default: 5.0)

The amount of seconds to wait before the next connection attempt.

returned:

True: success Failed: failed to connect after maximum retries.

write(data, RECV=2048)

Do a socket send and wait to receive directly to the xul browser.

This side steps the broker if its not running already.

evasion.director.viewpointdirect.main()

Command line interface to remote call

Subpackages

• controllers Package
  • controllers Package
  • agencyctrl Module
    • agency – This runs the agency without needing to spawnit under another python process.
  • base Module
    • base – This is the base interface for a controller which the director can load.
  • commandline Module
    • commandline – This provides the interface to command line processes.
  • viewpoint Module
    • viewpointctrl – This is the director compatible controller for the viewpoint.
  • viewpointpassive Module
    • viewpointpassive – This doesn’t start a viewpoint but controls one if runnning.
  • viewpointxulcontrol Module
    • viewpointpassive – This doesn’t start a viewpoint but controls one if runnning.
  • webadminctrl Module
• scripts Package
  • main Module
• tests Package
  • testdirector Module
  • testdirectorconfig Module
  • testlockabledict Module
• tools Package
  • tools Package
  • net Module
    • net – This provides handy utiliy functions for network services.
  • proc Module
    • proc – This provides handy utiliy functions dealing with processes.