circuits.core.components module

This module defines the BaseComponent and its subclass Component.

class circuits.core.components.prepare_unregister(*args, **kwargs)

Bases: Event

This event is fired when a component is about to be unregistered from the component tree. Unregistering a component actually detaches the complete subtree that the unregistered component is the root of. Components that need to know if they are removed from the main tree (e.g. because they maintain relationships to other components in the tree) handle this event, check if the component being unregistered is one of their ancestors and act accordingly.

Parameters

component – the component that will be unregistered

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.

complete = True
in_subtree(component)

Convenience method that checks if the given component is in the subtree that is about to be detached.

class circuits.core.components.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.components.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.