# circuits.core package

## Submodules

- circuits.core.bridge module
  - `ipc`
  - `Bridge`
    - `Bridge.channel`
    - `Bridge.init()`
- circuits.core.components module
  - `prepare_unregister`
    - `prepare_unregister.complete`
    - `prepare_unregister.in_subtree()`
  - `BaseComponent`
    - `BaseComponent.channel`
    - `BaseComponent.register()`
    - `BaseComponent.unregister()`
    - `BaseComponent.unregister_pending`
    - `BaseComponent.handlers()`
    - `BaseComponent.events()`
    - `BaseComponent.handles()`
  - `Component`
- circuits.core.debugger module
  - `Debugger`
    - `Debugger.IgnoreEvents`
    - `Debugger.IgnoreChannels`
- circuits.core.events module
  - `Event`
    - `Event.channels`
    - `Event.parent`
    - `Event.notify`
    - `Event.success`
    - `Event.failure`
    - `Event.complete`
    - `Event.alert_done`
    - `Event.waitingHandlers`
    - `Event.create()`
    - `Event.child()`
    - `Event.cancel()`
    - `Event.stop()`
  - `exception`
    - `exception.format_traceback()`
  - `started`
  - `stopped`
  - `signal`
  - `registered`
  - `unregistered`
  - `generate_events`
    - `generate_events.time_left`
    - `generate_events.reduce_time_left()`
    - `generate_events.lock`
- circuits.core.handlers module
  - `handler()`
  - `Unknown`
  - `reprhandler()`
  - `HandlerMetaClass`
- circuits.core.helpers module
  - `FallBackGenerator`
    - `FallBackGenerator.resume()`
  - `FallBackExceptionHandler`
  - `FallBackSignalHandler`
- circuits.core.loader module
  - `Loader`
    - `Loader.channel`
    - `Loader.load()`
- circuits.core.manager module
  - `UnregistrableError`
  - `TimeoutError`
  - `CallValue`
  - `ExceptionWrapper`
    - `ExceptionWrapper.extract()`
  - `Sleep`
    - `Sleep.expired`
    - `Sleep.task`
  - `sleep()`
  - `Manager`
    - `Manager.name`
    - `Manager.running`
    - `Manager.pid`
    - `Manager.getHandlers()`
    - `Manager.addHandler()`
    - `Manager.removeHandler()`
    - `Manager.registerChild()`
    - `Manager.unregisterChild()`
    - `Manager.fireEvent()`
    - `Manager.fire()`
    - `Manager.registerTask()`
    - `Manager.unregisterTask()`
    - `Manager.waitEvent()`
    - `Manager.wait()`
    - `Manager.callEvent()`
    - `Manager.call()`
    - `Manager.flushEvents()`
    - `Manager.flush()`
    - `Manager.start()`
    - `Manager.join()`
    - `Manager.stop()`
    - `Manager.processTask()`
    - `Manager.tick()`
    - `Manager.run()`
- circuits.core.pollers module
  - `BasePoller`
    - `BasePoller.channel`
    - `BasePoller.resume()`
    - `BasePoller.addReader()`
    - `BasePoller.addWriter()`
    - `BasePoller.removeReader()`
    - `BasePoller.removeWriter()`
    - `BasePoller.isReading()`
    - `BasePoller.isWriting()`
    - `BasePoller.discard()`
    - `BasePoller.getTarget()`
  - `EPoll`
    - `EPoll.channel`
    - `EPoll.addReader()`
    - `EPoll.addWriter()`
    - `EPoll.removeReader()`
    - `EPoll.removeWriter()`
    - `EPoll.discard()`
  - `KQueue`
    - `KQueue.channel`
    - `KQueue.addReader()`
    - `KQueue.addWriter()`
    - `KQueue.removeReader()`
    - `KQueue.removeWriter()`
    - `KQueue.discard()`
  - `Poll`
    - `Poll.channel`
    - `Poll.addReader()`
    - `Poll.addWriter()`
    - `Poll.removeReader()`
    - `Poll.removeWriter()`
    - `Poll.discard()`
  - `Poller`
  - `Select`
    - `Select.channel`
- circuits.core.timers module
  - `Timer`
    - `Timer.reset()`
    - `Timer.expiry`
- circuits.core.utils module
  - `flatten()`
  - `findchannel()`
  - `findtype()`
  - `findcmp()`
  - `findroot()`
  - `safeimport()`
- circuits.core.values module
  - `Value`
    - `Value.inform()`
    - `Value.getValue()`
    - `Value.setValue()`
    - `Value.value`
- circuits.core.workers module
  - `task`
    - `task.success`
    - `task.failure`
  - `Worker`
    - `Worker.channel`
    - `Worker.init()`

## 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 = '*'
  classmethod events()

    Returns a list of all events this Component listens to

  classmethod handlers()

    Returns a list of all event handlers for this Component

  classmethod handles(*names)

    Returns True if all names are event handlers of this Component

  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

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

  Bases: `BaseComponent`

  Initializes x; see x.__class__.__doc__ for signature

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.

  alert_done = False
  cancel()

    Cancel the event from being processed (if not already)

  channels = ()

    The channels this message is sent to.

  child(name, *args, **kwargs)
  complete = False
  classmethod create(_name, *args, **kwargs)
  failure = False
  notify = False
  parent = None
  stop()

    Stop further processing of this event

  success = False
  waitingHandlers = 0

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

  failure = True
  success = 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

  IgnoreChannels = []
  IgnoreEvents = ['generate_events']

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`

  property expiry
  reset(interval=None)

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

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

  addHandler(f)
  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()`).

  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()`).

  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 (“*”).

  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 (“*”).

  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.

  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.

  getHandlers(event, channel, **kwargs)
  join()
  property name

    Return the name of this Component/Manager

  property pid

    Return the process id of this Component/Manager

  processTask(event, task, parent=None)
  registerChild(component)
  registerTask(g)
  removeHandler(method, event=None)
  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.

  property running

    Return the running state of this Component/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.

  stop(code=None)

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

  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.

  unregisterChild(component)
  unregisterTask(g)
  wait(event, *channels, **kwargs)
  waitEvent(event, *channels, **kwargs)

exception circuits.core.TimeoutError

  Bases: `Exception`

  Raised if wait event timeout occurred