Calling Python methods
Create Python Worker object
Create a new object variable and inherit from the Python Worker, grouped under the OW3 Worker Objects. For more control, you might prefer to create a new object class in your library and inherit from the Python worker through the $superclass property.
Initialise and start the worker
Once you have an object or an object reference to the Python Worker, you need initialise and then start the worker:
Do pyWorker.$init(,'/path/to/python3')
Do pyWorker.$start() Returns #F
A new thread will be launched upon calling $start where the Python process will wait until we give it methods to execute. Furthermore, you only need to call $start as you can make multiple method calls to the same worker.
The first parameter to $init takes overrides the search path, which is usually best to leave to default. The second parameter however is very useful: you can use it to specify the exact Python executable you wish to use. Please note whichever Python executable you try to use, it will need to have the packages from the requirements file installed, otherwise it will fail to start.
If the second parameter to $init is omitted, we default to /usr/bin/python3 on Linux and macOS. On Windows, we attempt to load the python3.dll which works if it's available in the PATH, then try loading the python3.exe in the same directory as the python3.dll.
To avoid failures when starting the Python Worker, we advise you point the Worker to your python3 executable through the second parameter to $init.
Call a method
If your Python worker has started successfully, we can use $callmethod(cModule, cMethod) where cModule is the name of the module we wish to use and cMethod is the name of the method inside our module we want to execute:
Do pyWorker.$callmethod('omnis_test', 'test') Returns #F
Passing parameters
Parameters passed to the Python worker are in the form of a list or row.
You can pass the list or row in the $callmethod:
Do lRow.$cols.$add('message',kCharacter,kSimplechar)
Do lRow.$assigncols('hello world')
Do pyWorker.$callmethod("omnis_test","test",lRow) Returns #F
In order to access parameters on the Python module side, use the param parameter of your method:
from omnis_calls import sendResponse, sendError
def test(param):
return sendResponse(param['value'])
Please note Omnis rows will create a Python dictionary param and Omnis lists will create a Python list param.
Method results
When the Python Worker returns, the $methodreturn callback is called with a row parameter.
Inside the row parameter, you can find the returned data from your method as well as any tags supplied to $callmethod.
For example, calling the test method in the omnis_test module will result in Unicode characters to be returned inside the unicode column in the first row parameter of $methodreturn.
Cancel call
If you have called a Python method but wish to cancel it, use the $cancel method on the Python worker:
Do pyWorker.$cancel()
Cancelling a call might be useful if you think it has been running for too long and wish to stop it.
Waiting on a call
The $callmethod is asynchronous by default, but there might be times where you wish to block the main thread until the Python Worker finishes its job, in which case you can pass kTrue to the bWait parameter of $callmethod (4th parameter):
Do pyWorker.$callmethod('omnis_test','test',,kTrue) Returns #F
When bWait is true, the Python Worker will block the main thread until it returns.
Tagging method calls
The same Python Worker instance can be used for multiple method calls since Python methods can be made asynchronous, as such it may come in useful the ability of tagging each call with an identifiable number.
The 6th parameter of $callmethod can accept a tag which will be returned in the $methodreturn:
Do pyWorker.$callmethod('omnis_test','test',,,,lTagID) Returns #F
A __tag column is added to the row parameter of $methodreturn if a tag was given to $callmethod, allowing you to identify the results.