Node interface reference

A node is defined as a Python class which inherits from sympathy.api.node.Node. All node definitions should be in files with filenames matching node_*.py and be placed in the Library folder of a node library. Nodes can be placed in subfolders and multiple nodes can be defined in the same file.

Node definition

The following class variables make up the definition of a node.


Sympathy treats the different required class variables slightly differently. name and nodeid are needed to generate the node. If these two are missing any attempt at creating this node stops immediately without any error message.


Required to generate a node.

The name of the node, is what the user will rely on to identify the node. It will show in the library view and in the node’s tooltip. It will also be used as the default label of any instance of the node in a flow.

Try to keep the name short and to the point. For example adding “node” to the name of the node is rather pointless. It is also recommended to never have two nodes with the same name as they will be all but impossible for a user to tell apart.


Required to generate the node.

The nodeid is the identifier of the node. The node identifier needs to be unique for each node. It should look something like this: 'com.example.boblib.helloworld'. The node id should represent a kind of “path” to the node. It usually consists of the Internet domain name of your organization, the library name, perhaps an internal filepath in the library, and lastly the node name. It should not contain any spaces.

The author of the node may contain name(s) of the author(s) of the node. It is only intended to give attribution to those who wrote the node. The current maintainer of the node can be specified in the library information in library.ini.
A version number of the node, as a string. For example version = '1.0'.

Path to a an icon to be displayed on the node, in SVG format (e.g. 'path/to/icon.svg').

Always use paths relative to the node in order for your library to be portable. Preferably use forward slashes as directory separators regardless of operating system.

To create svg icons you can, for instance, use the free software Inkscape.

The description variable is a short explanation of what the node does. This explanation is shown in the Library view and other places in the GUI to help users find the right node.
A copyright notice for this node. Note that this is generally not needed as a copyright notice can more easily be set for an entire library via Library meta data.
inputs and outputs
The input and output ports of the node. Should be instances of sympathy.api.nodeconfig.Ports. See Adding input and output ports for an introduction to how you add ports to nodes.
Parameter definition. Can be either a dictionary or an OrderedDict. See Adding a configuration GUI for an introduction.
Controller definition. Gives a bit of extra control over the automatic configuration GUI. See Controllers.

Overridable node methods

Override the following methods to specify the behavior of a node.

adjust_parameters(self, node_context)
Adjust the parameters depending on the input data. See Adjust parameters for more details.
execute(self, node_context)


Called when executing the node.

exec_parameter_view(self, node_context)
Return a custom configuration widget. If this method is not implemented, a configuration widget is built automatically from the parameter definition. See Custom GUIs for more details.
update_parameters(self, parameters)
Update the parameters of an old instance of the node to the new node definition, by making changes to the argument old_params. Note that this method does not receive a node context object. It only receives the current parameters of the node. See Managing node updates for more details.
verify_parameters(self, node_context)
Verify the parameters and return True if node is ready to be executed. As long as this method returns False the node will be in an invalid state and can not be executed. The configuration dialog can also not be accepted as long as this method returns False.

Callable node methods

Utility methods available in the node methods.


Tell the user how many percent of the node’s execution have been completed. The value should be between 0 and 100 inclusive. It is considered good practice to add calls to this method for any non-instant operations. For an example, see Progress example.

Calling this method in other node methods than execute has no effect.

Node context reference

The node context object that is sent to most node methods has five fields:

input and output

Input and output ports. See Adding input and output ports for an introduction to the use of ports.

Each port will be an object of the data type of that port. A reference of each data type can be found here: Data type APIs.

In execute the input ports will always have data, but in all other node methods it is possible that there is not yet any data on the input ports. See Adjust parameters for the basics of how to check if there is data available.

The parameters of this instance of the node, as a parameter root object. See Adding a configuration GUI for an introduction to the use of parameters, and Parameter helper reference for a full reference of parameters in Sympathy.
Dictionary containing the full node definition.
Currently unused.