Jupyter JS Services
Javascript client for the Jupyter services REST APIs
API Docs
REST API Docs
Note: All functions and methods using the REST API allow an optional
ajaxOptions
parameter to configure the request.
Package Install
Prerequisites
npm install --save jupyter-js-services
Source Build
Prerequisites
git clone https://github.com/jupyter/jupyter-js-services.git
cd jupyter-js-services
npm install
npm run build
Rebuild
npm run clean
npm run build
Run Tests
Follow the source build instructions first.
npm test
Build Docs
Follow the source build instructions first.
npm run docs
Navigate to docs/index.html
.
Supported Runtimes
The runtime versions which are currently known to work are listed below.
Earlier versions may also work, but come with no guarantees.
- Node 0.12.7+
- IE 11+
- Firefox 32+
- Chrome 38+
Usage from Node.js
Follow the package install instructions first.
npm install --save xmlhttprequest ws
Override the global XMLHttpRequest
and WebSocket
:
import { XMLHttpRequest } from "xmlhttprequest";
import { default as WebSocket } from 'ws';
global.XMLHttpRequest = XMLHttpRequest;
global.WebSocket = WebSocket;
Usage Examples
Note: This module is fully compatible with Node/Babel/ES6/ES5. Simply
omit the type declarations when using a language other than TypeScript.
Kernel
import {
listRunningKernels, connectToKernel, startNewKernel, getKernelSpecs
} from 'jupyter-js-services';
listRunningKernels({ baseUrl: 'http://localhost:8000' }).then(kernelModels => {
var options = {
baseUrl: 'http://localhost:8000',
wsUrl: 'ws://localhost:8000',
name: kernelModels[0].name
}
connectToKernel(kernelModels[0].id, options).then((kernel) => {
console.log(kernel.name);
});
});
getKernelSpecs({ baseUrl: 'http://localhost:8888' }).then(kernelSpecs => {
console.log('Default spec:', kernelSpecs.default);
console.log('Available specs', Object.keys(kernelSpecs.kernelspecs));
var options = {
baseUrl: 'http://localhost:8888',
wsUrl: 'ws://localhost:8888',
name: kernelSpecs.default
}
startNewKernel(options).then((kernel) => {
var future = kernel.execute({ code: 'a = 1' } );
future.onDone = () => {
console.log('Future is fulfilled');
}
future.onIOPub = (msg) => {
console.log(msg.content);
}
kernel.restart().then(() => {
var request = { code: 'hello', cursor_pos: 4, detail_level: 0};
kernel.inspect(request).then((reply) => {
console.log(reply.data);
});
});
kernel.interrupt().then(() => {
kernel.complete({ code: 'impor', cursor_pos: 4 } ).then((reply) => {
console.log(reply.matches);
});
});
kernel.statusChanged.connect((status) => {
console.log('status', status);
});
kernel.shutdown().then(() => {
console.log('Kernel shut down');
});
});
});
NotebookSession
import {
listRunningSessions, connectToSession, startNewSession
} from 'jupyter-js-services';
listRunningSessions({ baseUrl: 'http://localhost:8000' }
).then(sessionModels => {
var options = {
baseUrl: 'http://localhost:8000',
wsUrl: 'ws://localhost:8000',
kernelName: sessionModels[0].kernel.name,
notebookPath: sessionModels[0].notebook.path
}
connectToSession(sessionModels[0].id, options).then((session) => {
console.log(session.kernel.name);
});
});
var options = {
baseUrl: 'http://localhost:8000',
wsUrl: 'ws://localhost:8000',
kernelName: 'python',
notebookPath: '/tmp/foo.ipynb'
}
startNewSession(options).then((session) => {
var future = session.kernel.execute({ code: 'a = 1' });
future.onDone = () => {
console.log('Future is fulfilled');
}
session.renameNotebook('/local/bar.ipynb').then(() => {
console.log('Notebook renamed to', session.notebookPath);
});
session.sessionDied.connect(() => {
console.log('session died');
});
session.shutdown().then(() => {
console.log('session closed');
});
});
Comm
import {
getKernelSpecs, startNewKernel
} from 'jupyter-js-services';
var BASEURL = 'http://localhost:8888';
var WSURL = 'ws://localhost:8888';
getKernelSpecs({ baseUrl: BASEURL }).then(kernelSpecs => {
return startNewKernel({
baseUrl: BASEURL,
wsUrl: WSURL,
name: kernelSpecs.default,
});
}).then(kernel => {
var comm = kernel.connectToComm('test');
comm.open('initial state');
comm.send('test');
comm.close('bye');
});
getKernelSpecs({ baseUrl: BASEURL }).then(kernelSpecs => {
return startNewKernel({
baseUrl: BASEURL,
wsUrl: WSURL,
name: kernelSpecs.default,
});
}).then(kernel => {
kernel.commOpened.connect((kernel, commMsg) => {
if (commMsg.target_name !== 'test2') {
return;
}
var comm = kernel.connectToComm('test2', commMsg.comm_id);
comm.onMsg = (msg) => {
console.log(msg);
}
comm.onClose = (msg) => {
console.log(msg);
}
});
var code = [
"from ipykernel.comm import Comm",
"comm = Comm(target_name='test2')",
"comm.send(data='hello')",
"comm.close(data='bye')"
].join('\n')
kernel.execute({ code: code });
});
Contents
import {
ContentsManager
} from 'jupyter-js-services';
var contents = new ContentsManager('http://localhost:8000');
contents.newUntitled("/foo", { type: "file", ext: "py" }).then(
(model) => {
console.log(model.path);
}
);
contents.get("/foo", { type: "directory", name: "bar" }).then(
(model) => {
var files = model.content;
}
)
contents.rename("/foo/bar.txt", "/foo/baz.txt");
contents.save("/foo", { type: "file", name: "test.py" });
contents.delete("/foo/bar.txt");
contents.copy("/foo/bar.txt", "/baz").then((model) => {
var newPath = model.path;
});
contents.createCheckpoint("/foo/bar.ipynb").then((model) => {
var checkpoint = model;
contents.restoreCheckpoint("/foo/bar.ipynb", checkpoint.id);
contents.deleteCheckpoint("/foo/bar.ipynb", checkpoint.id);
});
contents.listCheckpoints("/foo/bar.txt").then((models) => {
console.log(models[0].id);
});
Configuration
startNewKernel, getKernelSpecs, getConfigSection, ConfigWithDefaults
} from 'jupyter-js-services';
var BASEURL = 'http://localhost:8888';
var WSURL = 'ws://localhost:8888';
getKernelSpecs({ baseUrl: BASEURL }).then(kernelSpecs => {
return startNewKernel({
baseUrl: BASEURL,
wsUrl: WSURL,
name: kernelSpecs.default,
});
}).then(kernel => {
getConfigSection('notebook', BASEURL).then(section => {
var defaults = { default_cell_type: 'code' };
var config = new ConfigWithDefaults(section, defaults, 'Notebook');
console.log(config.get('default_cell_type'));
config.set('foo', 'bar').then(data => {
console.log(data.foo);
});
});
});