# circuits 2.1.0 documentation

# `circuits.core.components` – Components

This module defines the BaseComponent and its subclass Component.

## Classes

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

  `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 `PrepareUnregister` 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 `PrepareUnregister` event has completed, the component is removed from the tree and an `Unregistered` event is fired.

  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

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

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

## Components

none

## Events

class `circuits.core.components.``PrepareUnregister`(*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

  `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.``SingletonError`

  Bases: `exceptions.Exception`

  Raised if a Component with the singleton class attribute is True.

## Functions

none