[WIP] enchannel-notebook-backend

📓 An enchannel backend that lets you connect to a Jupyter notebook server.

Installation

npm install enchannel-notebook-backend

Usage

Enchannel-notebook-backend provides an API for spawning, disconnecting, and shutting down remote kernels in addition to implementing the enchannel spec. A typical use would be to spawn a kernel, connect to the kernel and communicate using enchannel and Jupyter message specs, disconnect from the kernel, and optionally shut it down.

The act of connecting and disconnecting is deliberately separate to the act of spawning and shutting down a kernel. This allows one to spawn a kernel, start some compute on it, disconnect and reconnect at a later time, and shutdown the kernel when appropriate.

To use the enchannel-notebook-backend, you must have access to a running Jupyter notebook server. This library requires the Jupyter notebook server to be launched with an explicit origin. If you want to listen to all connections, launch the notebook server like so:

python -m notebook --NotebookApp.allow_origin="*"

connectionOptions

The connectionOptions object is used in almost every method described below. It's analogous to the endpoint used in enchannel-socketio-backend. A connectionOptions object looks like the following:

const connectionOptions = {
  baseUrl: 'http://localhost:8888',
  wsUrl: 'ws://localhost:8888',
};

Where baseUrl is the base URL of the notebook server
and wsUrl is the websocket URL of the notebook server.

spawn

Spawns a remote kernel by name. Takes two arguments:

• connectionOptions, object - connections object, see above
• kernelName, string - name of the kernel to spawn

Returns a promise with the kernel id, string.

spawn(connectionOptions, kernelName)

Usage example

const enchannelBackend = require('enchannel-notebook-backend');
enchannelBackend.spawn(connectionOptions, 'python3').then(id => {
  console.log('spawned', id);
}).catch(err => {
  console.error('Could not spawn the kernel', err);
});

connect

Connects to a remote kernel by id. Accepts two arguments:

• connectionOptions, object - connections object, see above
• kernelId, string - id of the kernel to connect to

Returns a promise for an enchannel spec channels object

connect(connectionOptions, kernelId)

Usage example

enchannelBackend.connect(connectionOptions, id).then(channels => {
  console.log('connected', channels);
}).catch(err => {
  console.error('Could not connect to the kernel', err);
});

For API usage of the enchannel channels object, refer to the enchannel spec README.

shutdown

Shuts down a remote kernel by id. Accepts two arguments:

• connectionOptions, object - connections object, see above
• kernelId, string - id of the kernel to shutdown

Returns a promise which resolves when the shutdown is complete.

shutdown(connectionOptions, kernelId)

Usage example

enchannelBackend.shutdown(connectionOptions, id).then(() => {
  console.log('shutdown');
}).catch(err => {
  console.error('Could not shutdown the kernel', err);
});

disconnect

Disconnects from a kernel by closing the channels. Accepts one argument, the enchannel channels object.

Returns promise which resolves on success.

disconnect(channels)

Usage example

enchannelBackend.disconnect(channels).then(() => {
  console.log('disconnected');
}).catch(err => {
  console.error('Could not close the channels', err);
});

Development

To develop against enchannel-notebook-backend, first clone the repo then from within the cloned folder run:

npm install
npm link

Before opening a pull request, please run the unit tests locally:

npm test

You can also verify that the code works by hand by opening the test.html file in your web browser and following the promps.