# circuits.core.handlers module

This module define the @handler decorator/function and the HandlesType type.

circuits.core.handlers.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.handlers.Unknown

  Bases: `object`

  Unknown Dummy Component

circuits.core.handlers.reprhandler(handler)

class circuits.core.handlers.HandlerMetaClass(name, bases, ns)

  Bases: `type`