libtcspc.Graph

class libtcspc.Graph

Bases: object

Processing graph.

A processing graph is a directed acyclic graph of Node objects. Each node is also assigned a name for later reference and retrieval.

Edges of the graph connect a specific output port of one node to a specific input port of another (in that direction). Any given input or output port may have at most a single edge connected to it.

At any point in time, the graph may contain nodes with unconnected input or output ports. These ports are the input and output ports of the graph as a whole.

Note: It is not possible to add a connection between a graph input and a graph output that does not have an intermediate node. But this can be worked around by using a SelectAll (i.e., no-op) node.

add_node(name, node, *, upstream=None, downstream=None)

Add a node to the graph, optionally connecting it to an existing node.

Parameters:

• name (str or None) – Name under which the node will be retrievable. If None, an auto-generated name of the form "{ClassName}-{N}" is assigned, where N is the smallest non-negative integer making the name unique.

• node (Node) – The node to add.

• upstream (tuple[str, str] or str or None) – If given, connect upstream to the new node’s "input" port. A (node_name, port_name) tuple selects an explicit output port; a bare node name defaults to its "output" port.

• downstream (tuple[str, str] or str or None) – If given, connect the new node’s "output" port to downstream. A (node_name, port_name) tuple selects an explicit input port; a bare node name defaults to its "input" port.

Returns:

The name under which the node was added (the auto-generated name if name was None, otherwise name).

Return type:

str

Raises:

ValueError – If name already exists in the graph, if a requested connection’s port types do not match, or if a requested connection would introduce a cycle.

add_sequence(nodes, *, upstream=None, downstream=None)

Add a sequence of single-input single-output nodes connected in series.

Parameters:

• nodes (Sequence[tuple[str, Node] or Node]) – The nodes to add, in order. Each element is either a (name, node) tuple or a bare Node; in the latter case a name is auto-generated as by add_node.

• upstream (tuple[str, str] or str or None) – If given, connect upstream to the first added node’s input port. The shorthand rules of add_node apply.

• downstream (tuple[str, str] or str or None) – If given, connect the last added node’s output port to downstream. The shorthand rules of add_node apply.

Raises:

ValueError – If any node does not have exactly one input and one output port, or if any requested connection fails.

Return type:

None

Notes

If nodes is empty and both upstream and downstream are given, upstream is connected directly to downstream.

connect(producer, consumer)

Connect an output port to an input port.

Parameters:

• producer (tuple[str, str] or str) – A (node_name, port_name) tuple selecting the producing node and its output port. A bare node name is shorthand for (name, "output").

• consumer (tuple[str, str] or str) – A (node_name, port_name) tuple selecting the consuming node and its input port. A bare node name is shorthand for (name, "input").

Raises:

ValueError – If either port is already connected, if the producer’s output event set is not compatible with the consumer’s input, or if the connection would introduce a cycle.

Return type:

None

Notes

Validation is performed immediately. If the connection is rejected, the graph is restored to its previous state before the exception propagates.

inputs()

Return the graph’s external input ports — those without an incoming edge.

Returns:

A tuple of (node_name, port_name) pairs, in node-addition order.

Return type:

tuple[tuple[str, str], …]

outputs()

Return the graph’s external output ports — those without an outgoing edge.

Returns:

A tuple of (node_name, port_name) pairs, in node-addition order.

Return type:

tuple[tuple[str, str], …]

visit_nodes(visitor)

Invoke visitor on every node in the graph.

Parameters:

visitor (Callable[[str, Node], None]) – Called once per node with (node_name, node). The return value is ignored.

Return type:

None

Notes

Traversal is in node-addition order, not topological order.