core.compound

pyctools.core.compound.Compound	Encapsulate several components into one.
pyctools.core.compound.RunnableNetwork	Encapsulate several components into one.

class Compound(config={}, config_map={}, linkages={}, **kw)

Bases: RunnableNetwork

Encapsulate several components into one.

Closely modeled on Kamaelia’s ‘Graphline’ component. Components are linked within the compound and to the outside world according to the linkages parameter.

For example, you could create an image resizer by connecting a FilterGenerator to a Resize as follows:

def ImageResizer(config={}, **kwds):
    cfg = {'aperture': 16}
    cfg.update(config)
    cfg.update(kwds)
    return Compound(
        filgen = FilterGenerator(),
        resize = Resize(),
        config = cfg,
        config_map = {
            'up'      : ('filgen.xup',   'resize.xup',
                         'filgen.yup',   'resize.yup'),
            'down'    : ('filgen.xdown', 'resize.xdown',
                         'filgen.ydown', 'resize.ydown'),
            'aperture': ('filgen.xaperture', 'filgen.yaperture'),
            },
        linkages = {
            ('self',   'input')  : ('resize', 'input'),
            ('filgen', 'output') : ('resize', 'filter'),
            ('resize', 'output') : ('self',    'output'),
            }
        )

Note the use of 'self' in the linkages parameter to denote the compound object’s own inputs and outputs. These are connected directly to the child components with no runtime overhead. There is no performance disadvantage from using compound objects. The 'self' inboxes and outboxes are added to the component’s inputs and outputs lists.

All the child components’ configuration objects are gathered into one ConfigParent. The child names are used to index the ConfigParent’s dict. This allows access to any config item in any child:

cfg = image_resizer.get_config()
cfg.filgen.xup = 3
cfg.filgen.xdown = 8
cfg.filgen.yup = 3
cfg.filgen.ydown = 8
cfg.resize.xup = 3
cfg.resize.xdown = 8
cfg.resize.yup = 3
cfg.resize.ydown = 8
image_resizer.set_config(cfg)

Compound components to be nested to any depth whilst still making their configuration available at the top level.

The config_map allows multiple child components to be controlled by one configuration item. For each item there is a list of child config items, in parent.child form. For example, to change the scaling factor of the image resizer shown above (even while it’s running!) you might do this:

cfg = image_resizer.get_config()
cfg.up = 3
cfg.down = 8
image_resizer.set_config(cfg)

You can also adjust the configuration when the compound component is created by passing a dict containing additional values. This allows the component’s user to over-ride the default values.

The compound component’s child components are stored in the children dict. This must not be modified but may be useful if you need to know about the component’s internals.

The component’s internal links are stored in the links list. This also must not be modified but can be used for introspection. Each element is a (src_name, outbox), (dest_name, inbox) tuple.

Parameters:

• name (Component) – Add Component to the network as name. Can be repeated with different values of name.

• linkages (dict) – A mapping from component outputs to component inputs.

• config (dict) – Additional configuration to be applied to the components before they are connected.

• config_map (dict) – Mapping of top level configuration names to child component configuration names.

connect(output_name, input_method)

Connect an output to any callable object.

Parameters:

• output_name (str) – the output to connect. Must be one of the 'self' outputs in the linkages parameter.

• input_method (callable) – the thread-safe callable to invoke when send is called.

bind(source, dest, destmeth)

Guild compatible version of connect.

This allows Pyctools compound components to be used in Guild pipelines.

get_config()

See pyctools.core.config.ConfigMixin.get_config.

set_config(config)

See pyctools.core.config.ConfigMixin.set_config.

class RunnableNetwork(linkages={}, **kw)

Bases: object

Encapsulate several components into one.

This is the basic runnable network part of a Compound component.

Parameters:

• name (Component) – Add Component to the network as name. Can be repeated with different values of name.

• linkages (dict) – A mapping from component outputs to component inputs.

inputs = []

outputs = []

children = {}

links = []

go()

Guild compatible version of start.

start()

Start the component running.

stop()

Thread-safe method to stop the component.

join(end_comps=False)

Wait for the compound component’s children to stop running.

Parameters:

end_comps (bool) – only wait for the components that end a pipeline. This is useful for complex graphs where it is normal for some components not to terminate.

---

Comments or questions? Please email jim@jim-easterbrook.me.uk.