Node interface reference

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. If they are defined, author, copyright, and version also need to be defined. If any of those three are missing an error message is generated while loading the library. Omitting name and nodeid can therefore be useful for creating a base class which should itself not be generated as a node.


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 should contain a name and email to the author, (e.g. 'John Smith <>'). If there are several authors to a node, separate them with semi colons.



A copyright notice (e.g. '(c) 2014 Example Organization').



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.
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.


To create nodes that are compatible with both Sympathy version 1.2 and 1.3 you should subclass synode.ManagedNode. It has the same overridable node methods except that they all end with _managed, e.g. execute_managed() or exec_parameter_view_managed(). See Library compatibility between 1.2 and 1.3 for more information.

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, old_params)
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 doesn’t 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.

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.


When creating nodes that should be compatible with both Sympathy version 1.2 and 1.3, it is important to note that the field parameters will be of different type in the different versions. In 1.2 it was a dictionary which you would wrap in synode.parameters() whereas in 1.3 it is already a ParameterRoot object. The solution is to always wrap the parameters in synode.parameters(). See Library compatibility between 1.2 and 1.3 for more information.