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_chain(nodes, *, upstream=None, downstream=None)

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

The last node may be a sink — that is, it may have zero outputs in addition to its single input. The first and middle nodes must have exactly one input and one output.

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. Must be None if the last node is a sink (zero outputs).

Raises:

ValueError – If the first or any middle node does not have exactly one input and one output; if the last node does not have exactly one input and (zero or one) outputs; if downstream is given but the last node has zero outputs; 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.

If any requested connection or node fails, all nodes and connections made by the call are removed and the exception propagates, leaving the graph unchanged.

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 Mapping 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. May also be a mapping from this node’s input port names to connection sources, connecting several inputs at once; each value follows the same shorthand (bare name → that node’s "output" port, or an explicit (name, port) tuple).

• downstream (tuple[str, str] or str or Mapping 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. May also be a mapping from this node’s output port names to connection targets, connecting several outputs at once; each value follows the same shorthand (bare name → that node’s "input" port, or an explicit (name, port) tuple).

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.

Notes

If any requested connection fails, the node and all connections made by the call are removed and the exception propagates, leaving the graph unchanged.

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], …]

to_graphviz(*, flatten=False)

Return a Graphviz DOT representation of the graph for visualization.

The output is intended for debugging and visualization only. The exact format is not stable and should not be consumed programmatically.

Nodes correspond 1:1 to the Python Node objects in the graph; any expansion that occurs during C++ code generation is not reflected. Partially-built graphs (unconnected ports, etc.) are supported — no validation is performed.

Edges are colored by thread region: all edges driven on the same thread share one color, and a Buffer or RealTimeBuffer boundary introduces a new color for the events it re-emits on its pump thread (so the producer and consumer halves are visually distinct). A node whose inputs illegally arrive on different threads — for example a Merge fed through a buffer on only one branch — is outlined in red. Like the rest of the output, the specific colors and this scheme may change without notice in future versions.

Parameters:

flatten (bool, optional) – If False (the default), each Subgraph is rendered as a Graphviz cluster_… subgraph surrounding its inner nodes. If True, Subgraph boundaries are not drawn and inner nodes appear directly in their containing graph.

Returns:

A complete digraph { ... } block in Graphviz DOT format.

Return type:

str