circuits.core package

Submodules

Module contents

Core

This package contains the essential core parts of the circuits framework.

circuits.core.handler(*names, **kwargs)

Creates an Event Handler

This decorator can be applied to methods of classes derived from circuits.core.components.BaseComponent. It marks the method as a handler for the events passed as arguments to the @handler decorator. The events are specified by their name.

The decorated method’s arguments must match the arguments passed to the circuits.core.events.Event on creation. Optionally, the method may have an additional first argument named event. If declared, the event object that caused the handler to be invoked is assigned to it.

By default, the handler is invoked by the component’s root Manager for events that are propagated on the channel determined by the BaseComponent’s channel attribute. This may be overridden by specifying a different channel as a keyword parameter of the decorator (channel=...).

Keyword argument priority influences the order in which handlers for a specific event are invoked. The higher the priority, the earlier the handler is executed.

If you want to override a handler defined in a base class of your component, you must specify override=True, else your method becomes an additional handler for the event.

Return value

Normally, the results returned by the handlers for an event are simply collected in the circuits.core.events.Event’s value attribute. As a special case, a handler may return a types.GeneratorType. This signals to the dispatcher that the handler isn’t ready to deliver a result yet. Rather, it has interrupted it’s execution with a yield None statement, thus preserving its current execution state.

The dispatcher saves the returned generator object as a task. All tasks are reexamined (i.e. their next() method is invoked) when the pending events have been executed.

This feature avoids an unnecessarily complicated chaining of event handlers. Imagine a handler A that needs the results from firing an event E in order to complete. Then without this feature, the final action of A would be to fire event E, and another handler for an event SuccessE would be required to complete handler A’s operation, now having the result from invoking E available (actually it’s even a bit more complicated).

Using this “suspend” feature, the handler simply fires event E and then yields None until e.g. it finds a result in E’s value attribute. For the simplest scenario, there even is a utility method circuits.core.manager.Manager.callEvent() that combines firing and waiting.

class circuits.core.BaseComponent(*args, **kwargs)

Bases: Manager

This is the base class for all components in a circuits based application. Components can (and should, except for root components) be registered with a parent component.

BaseComponents can declare methods as event handlers using the handler decoration (see circuits.core.handlers.handler()). The handlers are invoked for matching events from the component’s channel (specified as the component’s channel attribute).

BaseComponents inherit from circuits.core.manager.Manager. This provides components with the circuits.core.manager.Manager.fireEvent() method that can be used to fire events as the result of some computation.

Apart from the fireEvent() method, the Manager nature is important for root components that are started or run.

Variables

channel – a component can be associated with a specific channel by setting this attribute. This should either be done by specifying a class attribute channel in the derived class or by passing a keyword parameter channel=”…” to __init__. If specified, the component’s handlers receive events on the specified channel only, and events fired by the component will be sent on the specified channel (this behavior may be overridden, see Event, fireEvent() and handler()). By default, the channel attribute is set to “*”, meaning that events are fired on all channels and received from all channels.

initializes x; see x.__class__.__doc__ for signature

channel = '*'
register(parent)

Inserts this component in the component tree as a child of the given parent node.

Parameters

parent (Manager) – the parent component after registration has completed.

This method fires a Registered event to inform other components in the tree about the new member.

unregister()

Removes this component from the component tree.

Removing a component from the component tree is a two stage process. First, the component is marked as to be removed, which prevents it from receiving further events, and a prepare_unregister event is fired. This allows other components to e.g. release references to the component to be removed before it is actually removed from the component tree.

After the processing of the prepare_unregister event has completed, the component is removed from the tree and an unregistered event is fired.

property unregister_pending
classmethod handlers()

Returns a list of all event handlers for this Component

classmethod events()

Returns a list of all events this Component listens to

classmethod handles(*names)

Returns True if all names are event handlers of this Component

class circuits.core.Component(*args, **kwargs)

Bases: BaseComponent

If you use Component instead of BaseComponent as base class for your own component class, then all methods that are not marked as private (i.e: start with an underscore) are automatically decorated as handlers.

The methods are invoked for all events from the component’s channel where the event’s name matches the method’s name.

class circuits.core.Event(*args, **kwargs)

Bases: object

An event is a message send to one or more channels. It is eventually dispatched to all components that have handlers for one of the channels and the event type.

All normal arguments and keyword arguments passed to the constructor of an event are passed on to the handler. When declaring a handler, its argument list must therefore match the arguments used for creating the event.

Every event has a name attribute that is used for matching the event with the handlers.

Variables

  • channels –

    an optional attribute that may be set before firing the event. If defined (usually as a class variable), the attribute specifies the channels that the event should be delivered to as a tuple. This overrides the default behavior of sending the event to the firing component’s channel.

    When an event is fired, the value in this attribute is replaced for the instance with the channels that the event is actually sent to. This information may be used e.g. when the event is passed as a parameter to a handler.

  • value – this is a circuits.core.values.Value object that holds the results returned by the handlers invoked for the event.

  • success – if this optional attribute is set to True, an associated event success (original name with “_success” appended) will automatically be fired when all handlers for the event have been invoked successfully.

  • success_channels – the success event is, by default, delivered to same channels as the successfully dispatched event itself. This may be overridden by specifying an alternative list of destinations using this attribute.

  • complete – if this optional attribute is set to True, an associated event complete (original name with “_complete” appended) will automatically be fired when all handlers for the event and all events fired by these handlers (recursively) have been invoked successfully.

  • complete_channels – the complete event is, by default, delivered to same channels as the initially dispatched event itself. This may be overridden by specifying an alternative list of destinations using this attribute.

channels = ()

The channels this message is sent to.

parent = None
notify = False
success = False
failure = False
complete = False
alert_done = False
waitingHandlers = 0
classmethod create(_name, *args, **kwargs)
child(name, *args, **kwargs)
cancel()

Cancel the event from being processed (if not already)

stop()

Stop further processing of this event

class circuits.core.task(f, *args, **kwargs)

Bases: Event

task Event

This Event is used to initiate a new task to be performed by a Worker

Parameters

  • f (function) – The function to be executed.

  • args (tuple) – Arguments to pass to the function

  • kwargs (dict) – Keyword Arguments to pass to the function

x.__init__(…) initializes x; see x.__class__.__doc__ for signature

success = True
failure = True
class circuits.core.Worker(*args, **kwargs)

Bases: BaseComponent

A thread/process Worker Component

This Component creates a pool of workers (either a thread or process) and executures the supplied function from a task() event passing supplied arguments and keyword-arguments to the function.

A task_success event is fired upon successful execution of the function and task_failure if it failed and threw an exception. The task() event can also be “waited” upon by using the .call() and .wait() primitives.

Parameters

process (bool) – True to start this Worker as a process (Thread otherwise)

initializes x; see x.__class__.__doc__ for signature

channel = 'worker'
init(process=False, workers=None, channel='worker')
class circuits.core.ipc(event, channel=None)

Bases: Event

ipc Event

Send an event to a child/parent process

Parameters

  • event (circuits.core.events.Event) – Event to execute remotely.

  • channel (str) – IPC Channel (channel to use on child/parent).

class circuits.core.Bridge(*args, **kwargs)

Bases: BaseComponent

initializes x; see x.__class__.__doc__ for signature

channel = 'bridge'
init(socket, channel='bridge')
class circuits.core.Debugger(*args, **kwargs)

Bases: BaseComponent

Create a new Debugger Component

Creates a new Debugger Component that listens to all events in the system printing each event to sys.stderr or a Logger Component.

Variables

  • IgnoreEvents – list of events (str) to ignore

  • IgnoreChannels – list of channels (str) to ignore

  • enabled – Enabled/Disabled flag

Parameters

log – Logger Component instance or None (default)

initializes x; see x.__class__.__doc__ for signature

IgnoreEvents = ['generate_events']
IgnoreChannels = []
class circuits.core.Timer(*args, **kwargs)

Bases: BaseComponent

Timer Component

A timer is a component that fires an event once after a certain delay or periodically at a regular interval.

Parameters

  • interval (datetime or number of seconds as a float) – the delay or interval to wait for until the event is fired. If interval is specified as datetime, the interval is recalculated as the time span from now to the given datetime.

  • event (Event) – the event to fire.

  • persist (bool) – An optional keyword argument which if True will cause the event to be fired repeatedly once per configured interval until the timer is unregistered. If False, the event fires exactly once after the specified interval, and the timer is unregistered. Default: False

reset(interval=None)

Reset the timer, i.e. clear the amount of time already waited for.

property expiry
class circuits.core.Manager(*args, **kwargs)

Bases: object

The manager class has two roles. As a base class for component implementation, it provides methods for event and handler management. The method fireEvent() appends a new event at the end of the event queue for later execution. waitEvent() suspends the execution of a handler until all handlers for a given event have been invoked. callEvent() combines the last two methods in a single method.

The methods addHandler() and removeHandler() allow handlers for events to be added and removed dynamically. (The more common way to register a handler is to use the handler() decorator or derive the class from Component.)

In its second role, the Manager takes the role of the event executor. Every component hierarchy has a root component that maintains a queue of events. Firing an event effectively means appending it to the event queue maintained by the root manager. The flush() method removes all pending events from the queue and, for each event, invokes all the handlers. Usually, flush() is indirectly invoked by run().

The manager optionally provides information about the execution of events as automatically generated events. If an Event has its success attribute set to True, the manager fires a Success event if all handlers have been executed without error. Note that this event will be enqueued (and dispatched) immediately after the events that have been fired by the event’s handlers. So the success event indicates both the successful invocation of all handlers for the event and the processing of the immediate follow-up events fired by those handlers.

Sometimes it is not sufficient to know that an event and its immediate follow-up events have been processed. Rather, it is important to know when all state changes triggered by an event, directly or indirectly, have been performed. This also includes the processing of events that have been fired when invoking the handlers for the follow-up events and the processing of events that have again been fired by those handlers and so on. The completion of the processing of an event and all its direct or indirect follow-up events may be indicated by a Complete event. This event is generated by the manager if Event has its complete attribute set to True.

Apart from the event queue, the root manager also maintains a list of tasks, actually Python generators, that are updated when the event queue has been flushed.

initializes x; see x.__class__.__doc__ for signature

property name

Return the name of this Component/Manager

property running

Return the running state of this Component/Manager

property pid

Return the process id of this Component/Manager

getHandlers(event, channel, **kwargs)
addHandler(f)
removeHandler(method, event=None)
registerChild(component)
unregisterChild(component)
fireEvent(event, *channels, **kwargs)

Fire an event into the system.

Parameters

  • event – The event that is to be fired.

  • channels – The channels that this event is delivered on. If no channels are specified, the event is delivered to the channels found in the event’s channel attribute. If this attribute is not set, the event is delivered to the firing component’s channel. And eventually, when set neither, the event is delivered on all channels (“*”).

fire(event, *channels, **kwargs)

Fire an event into the system.

Parameters

  • event – The event that is to be fired.

  • channels – The channels that this event is delivered on. If no channels are specified, the event is delivered to the channels found in the event’s channel attribute. If this attribute is not set, the event is delivered to the firing component’s channel. And eventually, when set neither, the event is delivered on all channels (“*”).

registerTask(g)
unregisterTask(g)
waitEvent(event, *channels, **kwargs)
wait(event, *channels, **kwargs)
callEvent(event, *channels, **kwargs)

Fire the given event to the specified channels and suspend execution until it has been dispatched. This method may only be invoked as argument to a yield on the top execution level of a handler (e.g. “yield self.callEvent(event)”). It effectively creates and returns a generator that will be invoked by the main loop until the event has been dispatched (see circuits.core.handlers.handler()).

call(event, *channels, **kwargs)

Fire the given event to the specified channels and suspend execution until it has been dispatched. This method may only be invoked as argument to a yield on the top execution level of a handler (e.g. “yield self.callEvent(event)”). It effectively creates and returns a generator that will be invoked by the main loop until the event has been dispatched (see circuits.core.handlers.handler()).

flushEvents()

Flush all Events in the Event Queue. If called on a manager that is not the root of an object hierarchy, the invocation is delegated to the root manager.

flush()

Flush all Events in the Event Queue. If called on a manager that is not the root of an object hierarchy, the invocation is delegated to the root manager.

start(process=False, link=None)

Start a new thread or process that invokes this manager’s run() method. The invocation of this method returns immediately after the task or process has been started.

join()
stop(code=None)

Stop this manager. Invoking this method causes an invocation of run() to return.

processTask(event, task, parent=None)
tick(timeout=-1)

Execute all possible actions once. Process all registered tasks and flush the event queue. If the application is running fire a GenerateEvents to get new events from sources.

This method is usually invoked from run(). It may also be used to build an application specific main loop.

Parameters

timeout (float, measuring seconds) – the maximum waiting time spent in this method. If negative, the method may block until at least one action has been taken.

run(socket=None)

Run this manager. The method fires the Started event and then continuously calls tick().

The method returns when the manager’s stop() method is invoked.

If invoked by a programs main thread, a signal handler for the INT and TERM signals is installed. This handler fires the corresponding Signal events and then calls stop() for the manager.

exception circuits.core.TimeoutError

Bases: Exception

Raised if wait event timeout occurred