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 nodes folder of a node library. See Libraries for information about where to put nodes in your 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.


The fields name and nodeid are needed to generate the node. If any of these two are missing any attempt at creating this node stops immediately without any error message. This can be a good way of e.g. creating a superclass for multiple node classes.



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.



The nodeid is the identifier of the node. The node identifier must 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 some grouping 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 tooltips in the GUI as well as in the documentation for the node. It is intended to help the user find out what the node does.

It can be a paragraph of more than one line, but should still be short enough to be managable in a tootip in the GUI. It is recommended to write the description in imperative case (e.g. “Split Table row wise (vertically), grouping unique values of an index column.”) with full punctuated sentences. When writing the description you can assume that the user has good knowledge of Sympathy in general, but knows nothing of what this specific node does. To keep it shorter it is recommended to only describe the most common mode(s) of operation for the node and not go into any details about edge cases, rarely used configuration options etc. Save those for the extended documentation (the docstring).


A list of nodeids to nodes that are related to this one. Only used in documentation to guide the user to learn about nodes. If this node has several variants (e.g. a table variant and a [table] variant) it should list all of them here. If a node lists itself in related, that nodeid is ignored. If a related node has several variants it is recommended to only list the most “basic” one in related.


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.

Node docstring

The docstring of a node class is used for documentation. This is a good place to go into details about what the node does, its most important configuration and (if applicable) how it handles errors; anything the user might need to know about the node.

Note that the node’s description is inserted at the top of the documentation so the docstring doesn’t need to repeat the description.

The docstring may include Sphinx ReStructuredText syntax. If you want to use ReST headings in your node documenation you should use the equal sign (=) and hyphen (-) levels.

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

During configuration it is possible that there is not yet any data on the input ports. See Adjust parameters for the basics of how to manage what data is available during configuration.


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 Parameters for a full reference of parameters in Sympathy.


Dictionary containing the full node definition.


Currently unused.

Node helper functions

sympathy.api.node_helper.list_node_decorator(input_keys, output_keys)

Use this decorator to automatically create a list version of a node.

As arguments to the decorator you should supply the input ports and output port that should be looped over, either using string keys or numberic indices. The new node class should also inherit from the non-list node class, overriding nodeid and name. It may also override any other field or method that needs to be special cased for the list version of the node.

The specified ports are automatically changed to lists in the list version of the node, and the methods execute and exec_parameter_view are suitably adapted to deal with this. Note that the adjust_parameters is not adapted, but so long as you use the adjust function it should work for both nodes.