chainlet.chainlink module

class chainlet.chainlink.ChainLink

Bases: object

BaseClass for elements in a chain

A chain is created by binding ChainLinks together. This is a directional process: a binding is always made between parent and child. Each child can be the parent to another child, and vice versa.

The direction dictates how data is passed along the chain:

• A parent may send() a data chunk to a child.
• A child may pull the next() data chunk from the parent.

Chaining is done with >> and << operators as parent >> child and child << parent. Forking and joining of chains requires a sequence of multiple elements as parent or child.

parent >> child

child << parent

Bind child and parent. Both directions of the statement are equivalent: if a is made a child of b, then b` is made a parent of a, and vice versa.

parent >> (child_a, child_b, ...)

parent >> [child_a, child_b, ...]

parent >> {child_a, child_b, ...}

Bind child_a, child_b, etc. as children of parent.

(parent_a, parent_b, ...) >> child

[parent_a, parent_b, ...] >> child

{parent_a, parent_b, ...} >> child

Bind parent_a, parent_b, etc. as parents of child.

Aside from binding, every ChainLink implements the Generator-Iterator Methods interface:

iter(link)

Create an iterator over all data chunks that can be created. Empty results are ignored.

link.__next__()

link.send(None)

next(link)

Create a new chunk of data. Raise StopIteration if there are no more chunks. Implicitly used by next(link).

link.send(chunk)

Process a data chunk, and return the result.

Note

The next variants contrast with iter by also returning empty chunks. Use variations of next(iter(link)) for an explicit iteration.

link.chainlet_send(chunk)

Process a data chunk locally, and return the result.

This method implements data processing in an element; subclasses must overwrite it to define how they handle data.

This method should only be called to explicitly traverse elements in a chain. Client code should use next(link) and link.send(chunk) instead.

link.throw(type[, value[, traceback]])

Raises an exception of type inside the link. The link may either return a final result (including None), raise StopIteration if there are no more results, or propagate any other, unhandled exception.

link.close()

Close the link, cleaning up any resources.. A closed link may raise RuntimeError if data is requested via next or processed via send.

When used in a chain, each ChainLink is distinguished by its handling of input and output. There are two attributes to signal the behaviour when chained. These specify whether the element performs a 1 -> 1, n -> 1, 1 -> m or n -> m processing of data.

chain_join

A bool indicating that the element expects the values of all preceding elements at once. That is, the chunk passed in via send() is an iterable providing the return values of the previous elements.

chain_fork

A bool indicating that the element produces several values at once. That is, the return value is an iterable of data chunks, each of which should be passed on independently.

To prematurely stop the traversal of a chain, 1 -> n and n -> m elements should return an empty container. Any 1 -> 1 and n -> 1 element must raise StopTraversal.

chain_fork = False

whether this element produces several data chunks at once

chain_join = False

whether this element processes several data chunks at once

chain_types = <chainlet.primitives.linker.LinkPrimitives object>

chainlet_send(value=None)

Send a value to this element for processing

close()

Close this element, freeing resources and possibly blocking further interactions

dispatch(values)

Dispatch multiple values to this element for processing

next()

send(value=None)

Send a single value to this element for processing

static throw(type, value=None, traceback=None)

Throw an exception in this element

class chainlet.chainlink.Bundle(elements)

Bases: chainlet.primitives.compound.CompoundLink

A group of chainlets that concurrently process each data chunk

chain_fork = True

chain_join

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

chainlet_send(value=None)

Send a value to this element for processing

class chainlet.chainlink.FlatChain(elements)

Bases: chainlet.primitives.chain.Chain

A specialised Chain which never forks or joins internally

chain_fork = False

chain_join = False

chainlet_send(value=None)

Send a value to this element for processing

send(value=None)

class chainlet.chainlink.Chain(elements)

Bases: chainlet.primitives.compound.CompoundLink

A group of chainlets that sequentially process each data chunk

Parameters:elements (iterable[ChainLink]) – the chainlets making up this chain Note:If elements contains a Chain, this is flattened and any sub-elements are directly included in the new Chain.

Slicing a chain guarantees consistency of the sum of parts and the chain. Linking an ordered, complete sequence of subslices recreates an equivalent chain.

chain == chain[:i] >> chain[i:]

Also, splitting a chain allows to pass values along the parts for equal results. This is useful if you want to inspect a chain at a specific position.

chain_result = chain.send(value)
temp_value = chain[:i].send(value)
split_result = chain[i:].send(temp_value)
chain_result == temp_value

Note:Some optimised chainlets may assimilate subsequent chainlets during linking. The rules for splitting chains still apply, though the actual chain elements may differ from the provided ones.

chain_fork

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

chain_join

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

chainlet_send(value=None)

Send a value to this element for processing

class chainlet.chainlink.LinkPrimitives

Bases: object

Primitives used in a linker domain

Warning:This is an internal, WIP helper. Names, APIs and signatures are subject to change.

classmethod add_converter(converter)

Add a converter to this Converter type and all its children

Each converter is a callable with the signature

converter(element: object) → :py:class:`ChainLink`

and must create a ChainLink for any valid element input. For any element that is not valid input, NotImplemented must be returned.

base_bundle_type = None

the basic bundle type holding groups of concurrent chainlinks

base_chain_type = None

the basic chain type holding sequences of chainlinks

base_link_type = None

the basic chainlink type from which all primitives of this domain derive

convert(element)

Convert an element to a chainlink

converters

flat_chain_type = None

the flat chain type holding sequences of simple chainlinks

link(parent, child)

neutral_link_type = None

a neutral link that does not change a chain

supersedes(other)