liaison-py 1.0.0

Provides a way of interfacing with a Python backend by sending commands as JSON.

Liaison

Liaison provides a way of interfacing with a Python backend by sending commands as JSON.

History

Liaison was built by Open Science Tools Ltd. to provide an interface between the PsychoPy Studio app (a frontend built in Electron/Svelte) and the PsychoPy Python library. Owing to the general usefulness of being able to interface with Python via JSON commands, we decided to release it as its own package, for general use. Liaison is distributed under an MIT License.

While Liaison is designed to allow support for other communication methods to be added in future, and could hypothetically support any method over which a JSON string can be sent, it presently only supports sending/receiving messages over websocket as this is the implementation it was built for.

Liaison is not a generic data structure tool. It's a system for sending simple instructions to a Python instance and doing some basic namespace management. If you are interested in the exchange of serialised strcutured data, check out Google's Protocol Buffers or Cap'n Proto.

Getting started with Websocket Liaison

Installing

To use Liaison with websockets, you will need to install with the optional websocket dependencies:

pip install liaison-backend[websocket]

Then make sure you have something setup on your application frontend which can make command line calls, such as Node's child_process module.

Getting constants

Liaison uses a few constant values to communicate when it's started and stopped. While you could hardcode these, you can also get them from Liaison via command line:

python -m liaison.constants

which will return a JSON string:

{"START_MARKER": "LIAISON:CONNECTED", "STOP_MARKER": "LIAISON:DISCONNECTED"}

When Liaison starts, it will send the START_MARKER, and will send the STOP_MARKER when it stops, so looking out for these values lets you keep track of the life cycle of the Liaison backend.

Starting Liaison

To start a Liaison backend on a particular websocket address, just call:

python -m liaison.websocket <address>

This will run continuously until told to stop, listening for messages on the given websocket address. It will send the START_MARKER constant to its stdout upon starting, and will send the STOP_MARKER constant upon stopping.

Example: Starting a Liaison backend from a Node (JavaScript) app

import proc from "child_process";

// binary decoder for websocket messages
const decoder = new TextDecoder();
// choose an address to open the websocket on
const address = "localhost:8003";
// get liaison constants
const liaisonConstants = JSON.parse(
    proc.execSync(
        "python -m liaison.constants"
    )
);
// start process running liaison
const liaisonProcess = proc.spawn(
    `python -m liaison.websocket ${address}`
);
// wait for started message
var liaisonStarted = Promise.withResolvers()
liaisonProcess.stdout.on("data", evt => {
    // if message indicates liaison has started, resolve promise
    if (decoder.decode(evt) === `${liaisonConstants.START_MARKER}@${address}`) {
        liaisonStarted.resolve(evt)
    }
})
await liaisonStarted.promise
// create websoket to send messages over
let liaisonSocket = new WebSocket(`ws://${address}`);

Companion object

Each instance of Liaison creates an instance of Companion; this is an object with its own namespace, whose methods Liaison can call, giving access to Python through them. Objects in the Companion's namespace can be used as an argument to any given function by prepending them with $. Companion objects have the following methods:

get

Get the value from this Companion's namespace which a string points to.

Parameters

• target <string> A string of attribute/key references starting with a name in this Companion's namespace or an importable package.

Returns

• <any> The value of the given target

exists

Check whether a target exists, either as a name in this Companion's namespace or as part of an installed Python module.

Parameters

• target <string> A string of attribute/key references starting with a name in this Companion's namespace or an importable package.

Returns

• <boolean> true/false according to whether the target exists

init

Initialize an object and store it in this Companion's namespace

Parameters

• name <string> Name to store the created object by
• cls <string> Resolvable string pointing to the class to initialise (or a callable to use as a constructor)
• args <array> Positional arguments to supply to the constructor
• kwargs <object> Named arguments to supply to the constructor

Returns

• <string> The name the object was registered to

run

Call the given function

Parameters

• fcn <string> Resolvable path to the function
• args <array> Positional arguments to pass to the function
• kwargs <object> Named arguments to pass to the function

Returns

• <any> Output from the function

try

The same as run, but called within a try:except statement

Parameters

• fcn <string> Resolvable path to the function
• args <array> Positional arguments to pass to the function
• kwargs <object> Named arguments to pass to the function

Returns

• <object> Object with a key "success" indicating whether the method executed successfully, and a key "result" containing either the output of the function or the caught error

register

Register something resolvable (e.g. a module, class or method) under a particular name

Parameters

• name <string> Name to register as
• target <string> Resolvable string pointing to object to register

Returns

• <string> Name the object was registered as

store

Store an arbitrary value in this Companion's namespace

Parameters

• name <string> Name to register as
• value <string> Value to store

Returns

• <string> Name the value was registered as

ping

Returns the word "pong". Useful for testing whether a Liaison is still alive, or send routine messages to keep a connection open.

Sending messages

Once you have both a Liaison process and a websocket setup, you can send messages to Liaison which will be executed by its Companion object. Liason has access to any Python modules present in the python environment it was executed from. The syntax of these messages is as follows:

• command <object>
  • command <string> Companion method to execute, see above for options and inputs for each
  • args <array> Array of positional arguments to pass to the Companion method
  • kwargs <object> Object of key:value pairs indicating the keyword arguments to be passed to the Companion method
• id <string> An arbitrary ID; when the function returns, any output will be sent back as a websocket message with the same ID

Example: Performing a T-Test in scipy over Liaison

// define some data to do a T-Test on
let a = [0.5982758 , 0.67019733, 0.68617796, 0.28764011]
let b = [0.41138649, 1.67023998, 1.0420896 , 1.49671732]
// create the command to send
let cmd = {
    command: {
        command: 'run',
        args: [
            "scipy.stats:ttest_ind", a, b
        ],
        kwargs: {
            equal_var: false
        }
    },
    id: crypto.randomUUID()
}
// send the command as a JSON string
liaisonSocket.send(
    JSON.stringify(cmd)
)
// wait for a reply (optional)
let replied = Promise.withResolvers()
let lsnr = evt => {
    // parse message
    let data = JSON.parse(evt.data)
    // if message is a reply to our command...
    if (data.evt.id !== cmd.id) {
        // stop listening
        liaisonSocket.removeEventListener("message", lsnr)
        // resolve/reject promise
        if (data.response) {
            replied.resolve(data.response)
        } else {
            replied.reject(data)
        }
    }    
}
liaisonSocket.addEventListener("message", lsnr)
// get response
let resp = await replied.promise