Python Engine

These functionalities use a Python standalone webservice, which allows to submit widgets and datasets scripts and get result from a Python environment already installed on the machine where the webservice runs. For this reason, Python environments need to be installed and configured on the same machine of Knowage server or even on a remote one, and the Python webservice has to be running inside that same environment. This implies that, in order to use this functionalities, you have to install Python properly (depending on the OS) on the same machine where the service will be running. You can find all information about Python installation at https://www.python.org. The official supported version is Python >=3.8.

Install knowage-python webservice

The knowage-python package contains the source code of the webservice that has to be installed and run on the server. You can download it via pip with the command:

pip install knowage-python=={knowage_version_number}

or simply you can find it in the Knowage-Server GitHub repository under the Knowage-Python folder.

If you downloaded knowage-python via pip, use “pip show knowage-python” to find the pip package installation location. Then copy the source file from this folder to your own custom folder such as /opt/knowagepython.

You will now have to create a file called hmackey that contains the value of the HMACkey in plaintext, and place it inside the <KNOWAGE_PYTHON_HOME>/src/app folder. It must be the same value specified in TOMCAT_HOME/conf/server.xml file.

Run knowage-python webservice

Once you have installed all the requirements, you need to get the python-webservice running. The Python service for KNOWAGE is a Flask application: please take a look at the official documentation. In order to do so, you should rely on a WSGI Server.

On Linux with Gunicorn

If you are working on a Linux environment, take a look at Gunicorn.

The entry point for the application is <KNOWAGE_PYTHON_HOME>/src/knowage-python.py and the default port is 5000.

Important

Webservice permissions

The knowage-python webservice must have the OS rights to read/write in its own folders.

Following you can find an example that shows you how to run knowage-python with gunicorn. First you need to create a configuration file called gunicorn.conf.py and place it under <KNOWAGE_PYTHON_HOME>/src folder.

import multiprocessing
bind = "0.0.0.0:5000"
workers = multiprocessing.cpu_count() * 2 + 1
timeout = 30
keepalive = 2
user = <user>
group = <group>
loglevel = 'info'
accesslog = '/var/log/gunicorn-access.log'
errorlog = '/var/log/gunicorn-error.log'
access_log_format = '%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s"'

Then to start the service run the following command inside the <KNOWAGE_PYTHON_HOME>/src/app folder.

/usr/local/bin/gunicorn -c file:gunicorn.conf.py knowage-python
/usr/local/bin/gunicorn --certfile cert.pem -c file:gunicorn.conf.py knowage-python

You can now create a service to start/stop Gunicorn: see your operating system documentation for that.

On Windows with Waitress

If you are working on a Windows environment, take a look at Waitress.

Create a waitress_server.py in <KNOWAGE_PYTHON_HOME>/src folder with the following content:

import multiprocessing
from waitress import serve
import importlib

knowage = importlib.import_module("knowage-python")

serve(knowage.application,
    channel_timeout=30,
    host='0.0.0.0',
    port=5000,
    threads=multiprocessing.cpu_count() * 2 + 1
)

Then run:

python waitress_server.py

Configure Knowage to enable Python/R functionalities

From the Knowage interface you can now enable the Python/R functionalities.

Go to the Roles management section, in the Authorizations tab under Widgets check the Edit Python Scripts option. Now you will be able to see the Python and R Dataset and Widget among the list of available ones.

Go to the Configuration management section, and create new variables of category PYTHON_CONFIGURATION and R_CONFIGURATION. For the label you can use python.default.environment.url. The value of this variables will specify the addresses of the Python and R webservices (es. python.webservice.address.com/domain). Now you will be able to see the addresses of the so configured environments when creating a Dataset or a Widget.