chainlet.primitives.link module

class chainlet.primitives.link.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