API Reference


The NodeWidget class provides the main entry point to the nodeworks library. The class provides a QWidget that can be inserted into Qt based applications. The NodeWidget contains methods for adding/removing Nodes and Connections as well as saving, loading, exporting, and solving the network.

class nodeworks.nodewidget.NodeWidget(parent: None = None, parentNode: None = None, showtoolbar: bool = True, onlypositivecoords: bool = False, threaded: bool = False, prompt: bool = True)[source]

Main widget for the displaying and editing a Node Chart.

addConnection(from_, to, controlpoints=None)[source]

Add a new connection

addNode(path=[], pos=None, geometry=None, uniquename=None, node=None)[source]

Add a node to the scene.


Process dependencies of Nodes, determine order.


Copy the currently selected Nodes


Copies and designates the currently selected Nodes for deletion


Delete all Nodes.


Delete the cut Nodes.


Delete the currently selected Nodes.


Deselect Everything


Run the nodes.

keyboardPress(key, data)[source]

Handle keyboard press events from the view. Only lets control modified keys through, except for delete.

keyboardSearch(pos, text=None)[source]

Display a Node search tool when typing.


Every time a new connection is made, or widget value changes, run this code.

open(event=None, path=None, nodeDict=None, customParams=None)[source]

Open a node chart or nodeDict


Paste the currently copied Nodes.


Delete items from scene

resizeEvent(self, QResizeEvent)[source]
save(event=None, path=None, customParams=None)[source]

Save the node chart


Select Everything


Stop the run


Sort the dependency tree. Inspired by: http://code.activestate.com/recipes/578272-topological-sort/

NodeWidget Support

class nodeworks.nodewidget.GraphicsScene(parent=None)[source]

Custom QGraphicsScene.

focusInEvent(self, QFocusEvent)[source]
focusOutEvent(self, QFocusEvent)[source]
mousePressEvent(self, QGraphicsSceneMouseEvent)[source]
mouseReleaseEvent(self, QGraphicsSceneMouseEvent)[source]
class nodeworks.nodewidget.StructureScene(parent=None)[source]

Custom QGraphicsScene for structures.

class nodeworks.nodewidget.GraphicsView(scene: nodeworks.nodewidget.GraphicsScene, parent: None = None)[source]

Custom QGraphicsScene.


Handle key press events

leaveEvent(self, QEvent)[source]
mouseMoveEvent(self, QMouseEvent)[source]
mousePressEvent(event: PyQt5.QtGui.QMouseEvent)[source]

Catch mouse events.

mouseReleaseEvent(self, QMouseEvent)[source]
save_to_image(fname, scale=1)[source]

Save the image to a file.


Handle zooming with the mouse wheel.

class nodeworks.nodewidget.PreviewView(scene: nodeworks.nodewidget.GraphicsScene, parent: Optional[NodeWidget] = None, view: Optional[nodeworks.nodewidget.GraphicsView] = None)[source]

Custom QGraphicsScene.

mouseDoubleClickEvent(self, QMouseEvent)[source]
mouseMoveEvent(self, QMouseEvent)[source]
mousePressEvent(self, QMouseEvent)[source]
mouseReleaseEvent(self, QMouseEvent)[source]
resizeEvent(self, QResizeEvent)[source]
class nodeworks.nodewidget.SearchNodeWidget(parent: Optional[NodeWidget] = None, nodelist: List[Any] = [])[source]

Provide a search interface for the nodes

class nodeworks.nodewidget.WorkerThread(function, parent=None)[source]


The Node provides the top-level methods for a node.

class nodeworks.node.Node(parent=None, style={})[source]

Main class for a Node.

parent (QObject):

parent of the node, typically nodeworks.nodewidget.NodeWidget (default None)

style (dict):

a dictionary describing the style of the node


This method is called when options for a terminal exist in the state however, the terminal does not exist in the Node. This method is meant to be overridden.

terminal (dict):

a dictionary of options

addTerminal(name, opts={}, insert=None)[source]

Add a terminal to the Node.

name (str):

the name of the Terminal, and the index of the Terminal in terminals

opts (dict):

a dictionary of Terminal options (default dict())

insert (int):

the position to insert the Terminal at.

term (Terminal):

the created terminal

addWidget(widget, insert=None)[source]

Add an arbitrary widget to the Node.

widget (QWidget):

the widget to be added to the node. Can be any QtWidgets.QWidget based class such as QtWidgets.QLineEdit, QtWidgets.QPushButton, etc.

insert (int):

the position to insert the wiget at.


Clear the Node’s error state, allow to run.


Set the Node is not running.


Collapse/expand the node down to only the connected terminals.

hide (bool):

a boolean that determines if the terminals should be hidden


Collect and return the dependencies of the Node

depSet (set):

a set nodes that this node depends on


Have the dependencies of the Node been processed


are the dependencies finished


Override this function with code to check for errors.


Loop over terminals and flip them to/from left and right


This method is called when users select options that need to hide or show terminals based on selected options within the Node. This method is meant to be overridden.


Call this method to run the self.process method threaded.


Override this function with the code to be called when the Node is executed.


Remove all terminals from the Node.


Remove all connections from the Node.


Remove the terminal from the Node.

name (str):

name of the terminal to be removed


Run the node. This function updates connections, clears any errors, checks for errors, finally if there are no errors and the input values have changed, calls the process method

ran (bool):

False if process was not called (error) else True

setError(message='None', terminal=None)[source]

Set the Node in an error state, will not let Node execute.

message (str):

an error message to be displayed for user information

terminal (str):

name of the terminal to highlight in red


Set the Node is running.

setState(state, customParams=None)[source]

Set the state. The uniquename, position, and connections are set through the addNode method of NodeWidget.

state (dict):

a dictionary containing information to set the terminal values


Set the style of the Node, as well as the terminals

style (dict):

a dictionary describing the style


Set the unique name of the node. This name is used in NodeWidget.nodeDict.

name (str):

the unique name


Display the help documentation


The current state of the node (position, values, connections, path)

stateDict (dict):

a JSON encodable dictionary


A function that is called if a value is changed. This enables the node for processing

value (Object):

the value to emit with the valueChanged signal


Loop through terminals, updating inputs

Node Support

class nodeworks.node.NodeGraphic(node, parent=None, style={})[source]

This class handles all the graphics for a Node.

node (Node):

the Node that this NodeGraphic is part of

parent (QObject):

parent (default None)

style (dict):

dictionary containing options

rightClickEvent (QGraphicsEvent):

emits when a user right clicks on a node but not over a Terminal

addTerminal(opts, style={}, insert=None)[source]

Add a terminal to the Node.

opts (dict):

a dictionary with options to define the terminal

style (dict):

a dictionary descripting the style of the terminal

insert (int):

the position in the layout to insert the terminal at. Index starts at 0. Thfirst item in the layout is typical the label for the node (default None)

term (Terminal):

the Terminal that was just created

addTerminalPad(pos=None, connect=True, rect=None, name=None, inout=None, dtype=None, padtype='pass', load=False)[source]

Add an arbitrary terminal pad to the Node

pos (QtCore.QPoint):

position where to add the pad (default None)

connect (bool):

True to emit a new connection event (default True)

rect (QtCore.QRectF):

rectangle describing the geometry of the pad (default None)

name (str):

name of the pad (default None)

inout (str):

‘in’ for an input pad, ‘out’ for an output pad.

dtype (type):

dtype of the pad

padtype (str):

type of the pad either ‘pass’, ‘index’, or ‘shift’ for a pass through terminal, an indexed terminal, or a shifted terminal.

addWidget(widget, insert=None)[source]

Allows arbitrary widgets to be added to a Node.

widget (QWidget):

the widget to be added

insert (int):

the position in the layout to insert the terminal at. Index starts at 0. Thfirst item in the layout is typical the label for the node (default None)


Create a QLineEdit to edit the Nodes name.


Delete the pad


Handle Drop Events

hoverEnterEvent(self, QGraphicsSceneHoverEvent)[source]
hoverLeaveEvent(self, QGraphicsSceneHoverEvent)[source]
hoverMoveEvent(self, QGraphicsSceneHoverEvent)[source]
itemChange(self, QGraphicsItem.GraphicsItemChange, Any) → Any[source]
keyPressEvent(self, QKeyEvent)[source]

Capture double click event


Handle mouse move events.


Capture mouse press events and find where the mouse was pressed on the object.


Capture mouse Release events.


Move Node to position.

pos (QPointF):

position to move the NodeGraphic to.

paint(self, QPainter, QStyleOptionGraphicsItem, QWidget)[source]

Remove a terminal from the node.

term (Terminal):

the terminal object to remove from the NodeGraphic


Rename the node.

name (str):

string to change the node name to


Resize the NodeGraphic to the minimum size allowed by the widgets in the node.


calculates the upper left hand corner of a node regardless of layering of structures


Set a QWidget to act as an editor for renaming the node.

widget (QWidget):

A QWidget to be called when the user edits the node name. This widget must have a lostFocus signal that is emitted when the widget as a new name to set the Node name to.

setStyle(self, QStyle)[source]
showRightClickMenu(globalpos, otheractions=None)[source]

Creates, configures, and sets right click menu.

globalpos (QPoint):

the QPoint object that represents the position of the mouse when the function is called

otheractions (list):

a list of additional QAction items that should be added to the right click menu for the node

update(self, rect: QRectF = QRectF())[source]

update(self, float, float, float, float)


Update Connections


Update Connections


Update Connections

class nodeworks.node.Terminal(opts, node, style={})[source]

This class draws a terminal.

opts (dict):

a dictionary of options for a terminal

node (Node):

the Node that this terminal is a part of

style (dict):

a dictionary of termianl options (default {})


a signal that emits the the current value every time that the value is changed

compare(value1, value2)[source]

Compare two values to see if they are the same. True means the values are NOT equal.

paintEvent(self, QPaintEvent)[source]

Remove all connections. Called at node delete event.


Remove a specific connection. The connection should already be removed from the scene.

removeconnection (Connection):

the connection to be removed.

setStyle(self, QStyle)[source]
setValue(value, trigger_update=False)[source]

Set the current value.


If there is an input connection, update the value.

property value

The current value.


The Connection provides connections between Terminals of Nodes

class nodeworks.node.Connection(nodeWidget=None, style=None, parent=None)[source]

This class draws connections between Terminals on Nodes.


Return the bounding rectangle of the connection.


Generate a path following points

points (list):

a list of QtCore.QPoint points for the connection line to follow


Check if the connection has both a start and stop terminal. It it does, return True, else return False.

mouseDoubleClickEvent(self, QGraphicsSceneMouseEvent)[source]

Capture the mouse press event

event ():

mouse event

paint(painter, *args)[source]

Paint the line.


Remove self from connected Nodes.


Remove the starting terminal


Remove the stop terminal


Set the starting terminal for a connection.


Set the starting terminal for a connection.


Calculate and return the shape of the connection. This shape is used for determining if the mouse is “over” the connection. This is used for mouseEvents and HoverEvents.


The current state of the node (position, values, connections, path)

stateDict (dict):

a JSON encodable dictionary


Update the line. If mousePos, use as missing point (start, stop).

mousePos (QtCore.QPoint):

a position to use as the missing point if


The NodeLibrary provides methods for building and maintaining a collection of Nodes that can be added to a network.

class nodeworks.nodelibrary.NodeLibrary[source]

Collection of Nodes

addNode(node, path)[source]

Add a Node to the library

addNodeLibrary(name, library)[source]

add a node library


build the default node library


Return the node at path

Base Widgets

Base widgets provide unified value and setValue methods as well as ValueChanged Signals for a collection of QWidgets.


A collection of helper functions.