sidegears 0.1.0

Tools for browser-based desktop applications

SideGears desktop app runtime

https://gitlab.com/john.tourtellott/sidegears

SideGears is a set of lightweight tools for creating desktop applications that consist of an html/css/javascript UI with a python backend. The toolset has two parts

• Python kernel for backend processing and platform access. the python kernel is available from pypi ("pip install sidegears").
• Javascript client for browser-based user interface. The javascript client is available from npmjs ("npm install sidegears").

The two halves connect through a standard websocket connection and communicate via json-rpc messages. In the typical use case, the user interface, running in a browser, calls methods in the kernel via the sidegears interface. See examples in the npm package that use the python webruntime library to launch a browser instance from python.

SideGears supports 3 of the 4 RPC transport cases:

• RPC request from the javascript client to the python kernel.
• RPC notification from client to kernel.
• RPC notification from kernel to client.

SideGears does not support RPC requests from the kernel to the client. This can be added, but is not considered needed for the desktop applications that are envisioned.

Python Kernel

The sidegears kernel uses the standard websockets module that runs in the asyncio event loop. The kernel has two public objects:

from sidegears.kernel import RPCKernel, rpc_method

Kernel methods are:

• start(self, host='localhost', port='5678', close_on_disconnect=False) Start the kernel, listening for client connections on the specified host and port. When the close_on_disconnect flag is set, the kernel will run until the client connection closes. (This call is not blocking.)
• stop(self) Stop the kernel, terminating any o## Javascript API en connections.
• wait_until_closed(self) Returns a future that resolves when the kernel has stopped. This method is used when the close_on_connection flag is set when the kernel is started.
• send_notification(self, method, params=None) Send a notification message to the client.
• set_basic_logging(self, enabled) Enable logging of the RPC messages sent and received.
• set_debug(self, enabled) Enabled debug options in the json RPC server.
• set_trim_log_values(self, enabled) When basic logging is enabled, shorten the messages logged to the console.

RPC methods are designated by using the rpc_method decorattor, for example:

@rpc_method
async def multiply(x, y):
    print('Received multiply method')
    return x*y

Note that methods must be defined as async.

Source code for several examples applications that run the kernel and launch a browser/UI are included in the package distribution files. You can find these in the python site-packages/sidegears folder.

Javascript Client Packages

The javascript libraries are used in conjunction with the corresponding python sidegears package in pypi. When the python sidegears kernel is running, the sidegears js library can connect to the kernel and make functions calls (which are transported as json-rpc messages over websockets.)

There are four packages in the dist folder:

• sidegears.js : UMD format, for running in browser or bundled with common js applications. This is the default package entry point.
• sidegears.esm.js : ES6 package for bundling into large applications
• sidegears-plugin.js : UMD format for Vue applications in browser or commonjs
• sidegears-plugin.esm.js : ES6 format, for bunding into applications

Javascript UI/Client

For starndard html pages, use the sidegears.js or sidegears.esm.js, depending on your bundling format. The API is very small, and used in the examples/client/client.html file. The API methods are:

• sidegears.connect(url) opens the connection to the kernel. For now, the only url currently supported by the kernel is 'ws://localhost:5678'. The method returns a promise object, so wait for that to resolve before calling methods on the kernel.

• sidegears.disconnect() closes the connection to the kernel. For desktop apps, this can be called in response to the window beforeUnload event, although there is no guarantee it will be executed before the window closes.

• sidegears.requester returns a proxy object that can make RPC request calls directly. In brief, calling sidegears.requester.method(params) is equivalent to calling sidegears.sendRequest(method, params).

• sidegears.notifier returns a proxy object that can make RPC notification calls directly. In brief, calling sidegears.notifier.method(params) is equivalent to calling sidegears.sendNotification(method, params).

• sidegears.sendRequest(method, parameters) makes an rpc call to the kernel, returning a promise object that resolves to the reply or error. The "method" argument is a string, and the parameters are passed to the method when it is executed in the kernel. Only parameters that can be json serialized can be used. The call returns a promise object that resolves to the result or error.

• sidegears.sendNotification(method, parameters) makes an rpc call to the kernel, but unlike reqest calls, there is no return from rpc notification calls. The "method" argument is a string, and the "parameters" are passed to the method when it is executed in the kernel. Only parameters that can be json serialized can be used.

• sidegears.onNotify is used to set an application to be called when notification messages are received from the python kernel.

Vue API

For Vue.js applications, you can use the sidegears-plugin.js and sidegears-plugin.esm.js files, which implement a Vue.js plugin. When installed, the plugin injects a global Vue.$_sidegears object. The plugin object has the same basic methods as described above for the standard API. From Vue components:

• this.$\_sidegears.connect(host='localhost', port=5678)
• this.$\_sidegears.disconnect()
• this.$\_sidegears.sendRequest(method, params)
• this.$\_sidegears.sendNotification(method, params)

Other methods are:

• $_sidegears.isOpen() returns a boolean indication whether the client is connected to the kernel or not.

• $_sidegears.getRequestProxy() returns a proxy object that can make RPC request calls directly (same as the javascript requester).

• $_sidegears.getNotifyProxy() returns a proxy object that can make RPC notification calls directly (same as the javascript notifier).

• custom notification event is emitted when a notification message is received from the kernel. The event arguments are the accompanying method and parameters.

Background

In some ways, SideGears is analogous to application frameworks such as Electron and NW.js, which also provide an html/js/css user interface.

• The main difference is that SideGears uses a python backend, whereas Electron and NW.js use nodejs.
• Also, in Electron and NW.js, the UI and nodejs logic are tightly coupled through a single event loop; whereas the SideGears UI and backend can be run in separate processes. (Theoretically, SideGears frontend and backend can run on different machines, although this is not officially supported.)
• SideGears supports the option to use an existing browser for the UI, instead of embedding chromium.

If anyone is curious where the term SideGears comes from:

• "Side" refers to PySide, which is the original name of the Qt for Python [1] project. Our initial implementations use the PySide QWebEngine library for the UI rendering engine (although we have moved on to webruntime). SideGears is also a "side" project for the author.
• "Gears" refers to TurboGears [2], a well-established web framework that takes a "best of breed" approach, combining existing tools into a cohesive system. We like their approach and try to emulate it. We also like to think of this project as a smtall set of software tools, not a full-scale "platform" or "framework".

[1] Qt for Python is at https://www.qt.io/qt-for-python

[2] TurboGears is at http://www.turbogears.org/