# circuits.core.events module

This module defines the basic event class and common events.

class circuits.core.events.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.events.exception(type, value, traceback, handler=None, fevent=None)

  Bases: `Event`

  exception Event

  This event is sent for any exceptions that occur during the execution of an event Handler that is not SystemExit or KeyboardInterrupt.

  Parameters:

    - type (type) – type of exception

    - value (exceptions.Exceptions) – exception object

    - traceback (traceback) – traceback of exception

    - handler (@handler(<method>)) – handler that raised the exception

    - fevent (event) – event that failed

  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.

  format_traceback(traceback)

class circuits.core.events.started(manager)

  Bases: `Event`

  started Event

  This Event is sent when a Component or Manager has started running.

  Parameters:

    manager (Component or Manager) – The component or manager that was started

  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.

class circuits.core.events.stopped(manager)

  Bases: `Event`

  stopped Event

  This Event is sent when a Component or Manager has stopped running.

  Parameters:

    manager (Component or Manager) – The component or manager that has stopped

  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.

class circuits.core.events.signal(signo, stack)

  Bases: `Event`

  signal Event

  This Event is sent when a Component receives a signal.

  Parameters:

    - signo – The signal number received.

    - stack – The interrupted stack frame.

  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.

class circuits.core.events.registered(component, manager)

  Bases: `Event`

  registered Event

  This Event is sent when a Component has registered with another Component or Manager. This Event is only sent if the Component or Manager being registered which is not itself.

  Parameters:

    - component (Component) – The Component being registered

    - manager (Component or Manager) – The Component or Manager being registered with

  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.

class circuits.core.events.unregistered(*args, **kwargs)

  Bases: `Event`

  unregistered Event

  This Event is sent when a Component has been unregistered from its Component or Manager.

  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.

class circuits.core.events.generate_events(lock, max_wait)

  Bases: `Event`

  generate_events Event

  This Event is sent by the circuits core. All components that generate timed events or events from external sources (e.g. data becoming available) should fire any pending events in their “generate_events” handler.

  The handler must either call `stop()` (preventing other handlers from being called in the same iteration) or must invoke `reduce_time_left()` with parameter 0.

  Parameters:

    max_wait – maximum time available for generating events.

  Components that actually consume time waiting for events to be generated, thus suspending normal execution, must provide a method `resume` that interrupts waiting for events.

  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.

  property time_left

    The time left for generating events. A value less than 0 indicates unlimited time. You should have only one component in your system (usually a poller component) that spends up to “time left” until it generates an event.

  reduce_time_left(time_left)

    Update the time left for generating events. This is typically used by event generators that currently don’t want to generate an event but know that they will within a certain time. By reducing the time left, they make sure that they are reinvoked when the time for generating the event has come (at the latest).

    This method can only be used to reduce the time left. If the parameter is larger than the current value of time left, it is ignored.

    If the time left is reduced to 0 and the event is currently being handled, the handler’s resume method is invoked.

  property lock