A collection of tutorials to develop Python extensions.
To get started with developing Python Node Extensions, you need to have conda
installed (via Anaconda or Miniconda). Here is the quickest way:
- Go to https://docs.conda.io/en/latest/miniconda.html
- Download the appropriate installer for your OS.
- For Windows and macOS: run the installer executable.
- For Linux: execute the script in terminal (see here for help)
Download this directory (basic
). In the basic
folder, you should see the following files:
.
├── tutorial_extension
│ │── icon.png
│ │── knime.yml
│ │── LICENSE.TXT
│ └── my_extension.py
├── config.yml
├── Example_with_Python_node.knwf
└── README.md
This is a quickstart guide that will walk you through the essential steps of writing and running your first Python Node Extension. We will use tutorial_extension
as the basis. The steps of the tutorial requiring modification of the Python code in my_extension.py
have corresponding comments in the file, for convenience.
For an extensive overview of the full API, please refer to the Defining a KNIME Node in Python: Full API section, as well as our Read the Docs page.
-
Install the KNIME Analytics Platform version 4.6.0 or higher, or a Nightly version (if Nightly before the release of 4.6.0, use the master update site. See here for help with Nightlies and update sites.)
-
Go to File -> Install KNIME Extensions…, enter "Python" in the search field, and look for
KNIME Python Node Development Extension (Labs)
. Alternatively you can manually navigate to theKNIME Labs Extensions
category and find the extension there. Select it and proceed with installation. -
The
tutorial_extension
will be your new extension. Familiarise yourself with the files contained in that folder, in particular:knime.yml
, which contains important metadata about your extension.my_extension.py
, which contains Python definitions of the nodes of your extension.config.yml
, just outside of the folder, contains information that binds your extension and the correspondingconda
/Python environment with KNIME Analytics Platform.
-
Create a
conda
/Python environment containing theknime-python-base
metapackage, together with the node development APIknime-extension
, andpackaging
. If you are usingconda
, you can create the environment by running the following command in your terminal (macOS/Linux) or Anaconda Prompt (Windows):conda create -n my_python_env python=3.9 packaging knime-python-base knime-extension -c knime -c conda-forge
If you would like to install
knime-python-base
andpackaging
into an already existing environment, you can run the following command from within that environment:conda install knime-python-base knime-extension packaging -c knime -c conda-forge
Note that you must append both the
knime
andconda-forge
channels to the commands in order for them to work. -
Edit the
config.yml
file located just outside of thetutorial_extension
(for this example, the file already exists with prefilled fields and values, but you would need to manually create it for future extensions that you develop). The contents should be as follows:<extension_id>: src: path/to/folder/of/template conda_env_path: path/to/my_python_env debug_mode: true
where:
<extension_id>
should be replaced with thegroup_id
andname
values specified inknime.yml
, combined with a dot.
For our example extension, the value for
group_id
isorg.knime
, and the value forname
isfluent_extension
, therefore the<extension_id>
placeholder should be replaced withorg.knime.fluent_extension
.-
the
src
field should specify the path to thetutorial_extension
folder. -
similarly, the
conda_env_path
field should specify the path to theconda
/Python environment created in Step 4. To get this path, run theconda env list
command in your Terminal/Anaconda Prompt, and copy the path next to the appropriate environment (my_python_env
in our case). -
the
debug_mode
is an optional field, which, if set totrue
, will tell KNIME Analytics Platform to use the latest changes in theconfigure
andexecute
methods of your Python node class whenever those methods are called.
-
We need to let KNIME Analytics Platform know where the
config.yml
is in order to allow it to use our extension and its Python environment. To do this, you need to edit theknime.ini
of your KNIME Analytics Platform installation, which is located at<path-to-your-KAP>/Contents/Eclipse/knime.ini
.Append the following line to the end, and modify it to have the correct path to
config.yml
:-Dknime.python.extension.config=path/to/your/config.yml
-
Start your KNIME Analytics Platform.
-
The "My Template Node" node should now be visible in the Node Repository.
-
Import and open the
Example_with_Python_node.knwf
workflow, which contains our test node:- Get familiar with the table.
- Study the code in
my_extension.py
and compare it with the node you see in KNIME Analytics Platform. In particular, understand where the node name and description, as well as its inputs and outputs, come from. - Execute the node and make sure that it produces an output table.
-
Build your first configuration dialog!
In
my_extension.py
, uncomment the definitions of parameters (marked by the "Tutorial Step 10" comment). Restart your KNIME Analytics Platform,, then drag&drop the node again into the workflow and you should be able to double-click the node and see configurable parameters - congrats!Take a minute to see how the names, descriptions, and default values compare between their definitions in
my_extension.py
and the node dialog. -
Add your first port!
To add a second input table to the node, follow these steps (marked by the "Tutorial Step 11" comment, you will need to restart):
- Uncomment the
@knext.input_table
decorator. - Change the
configure
method's definition to reflect the changes in the schema. - Change the
execute
method to reflect the addition of the second input table.
- Uncomment the
-
Add some functionality to the node!
With the following steps, we will append a new column to the first table and output the new table (the lines requiring to be changed are marked by the "Tutorial Step 12" comment):
- To inform downstream nodes of the changed schema, we need to change it in the return statement of the
configure
method; for this, we append metadata about a column to the output schema. - Everything else is done in the
execute
method:- we transform both input tables to pandas dataframes and append a new column to the first dataframe
- we transform that dataframe back to a KNIME table and return it
- To inform downstream nodes of the changed schema, we need to change it in the return statement of the
-
Use your parameters!
In the
execute
method, uncomment the lines marked by the "Tutorial Step 13" comment:Use a parameter to change some table content; we will add the value of the
double_param
parameter to every cell of a column. -
Start logging and setting warnings!
In the
execute
method, uncomment the lines marked by the "Tutorial Step 14" comment: Use the LOGGER functionality to inform users, or for debugging. Use theexecute_context.set_warning("A warning")
to inform the user about unusual behaviour If you want the node to fail, you can useraise ValueError("This node failed just because")
-
Congratulations, you have built your first functioning node entirely in Python!