circuits.core.components module

This module defines the BaseComponent and its subclass Component.

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

Bases: circuits.core.manager.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.

unregister_pending

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

Bases: circuits.core.components.BaseComponent

initializes x; see x.__class__.__doc__ for signature

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

Bases: circuits.core.events.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

complete = True

in_subtree(component)

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