# sophon-notebook-services

> Client APIs for the Jupyter services REST APIs

Latest version **4.0.2** (published 2019-07-31) · BSD-3-Clause license · 0 weekly downloads

## Install

```sh
npm install sophon-notebook-services
pnpm add sophon-notebook-services
yarn add sophon-notebook-services
bun add sophon-notebook-services
```

## Health

**Score 40/100 (D)** — status: abandoned.

Positive: has types; no vulnerabilities; high maintenance score; popular repo.

Warnings: low downloads; no esm support.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 4.0.2 |
| Published | 2019-07-31 |
| First published | 2019-07-31 |
| Weekly downloads | 0 |
| License | BSD-3-Clause |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 8 |
| Unpacked size | 1.4 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 15385 |
| Author | Project Jupyter |
| Maintainers | lcconly |
| Keywords | jupyter, notebook, services |

## Links

- npm: https://www.npmjs.com/package/sophon-notebook-services
- Repository: https://github.com/jupyterlab/jupyterlab
- Issues: https://github.com/jupyterlab/jupyterlab/issues
- npm.io page: https://npm.io/package/sophon-notebook-services

## Dependencies (8)

- [ws](https://npm.io/package/ws.md) ^7.0.0
- [node-fetch](https://npm.io/package/node-fetch.md) ^2.6.0
- [@phosphor/algorithm](https://npm.io/package/@phosphor/algorithm.md) ^1.1.3
- [@phosphor/coreutils](https://npm.io/package/@phosphor/coreutils.md) ^1.3.1
- [@phosphor/signaling](https://npm.io/package/@phosphor/signaling.md) ^1.2.3
- [@phosphor/disposable](https://npm.io/package/@phosphor/disposable.md) ^1.2.0
- [sophon-notebook-coreutils](https://npm.io/package/sophon-notebook-coreutils.md) ^3.0.0
- [sophon-notebook-observables](https://npm.io/package/sophon-notebook-observables.md) ^2.2.0

## Recent versions

- 4.0.2 (latest) — 2019-07-31
- 4.0.1 — 2019-08-02

## README

# JupyterLab Services

Javascript client for the Jupyter services REST APIs

[API Docs](http://jupyterlab.github.io/jupyterlab/)

[REST API Docs](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml)

Note: All functions and classes using the REST API allow a `serverSettings`
parameter to configure requests.
Requests are made using the `fetch` API, which is available in modern browsers
or via `npm install fetch` for node users. The `whatwg-fetch` npm package
can be used to polyfill browsers that do not support the `fetch` API.

## Package Install

**Prerequisites**

- [node](http://nodejs.org/)
- [python](https://www.anaconda.com/distribution/)

```bash
npm install --save sophon-notebook-services
conda install notebook  # notebook 4.3+ required
```

## Source Build

**Prerequisites**

- [git](http://git-scm.com/)
- [node 0.12+](http://nodejs.org/)
- [python](https://www.anaconda.com/distribution/)

```bash
git clone https://github.com/jupyterlab/jupyterlab.git
cd packages/services
npm install
npm run build
conda install notebook  # notebook 4.3+ required
```

**Rebuild**

```bash
npm run clean
npm run build
```

## Run Tests

Follow the source build instructions first.

```bash
npm test
```

## Build Docs

Follow the source build instructions first.

```bash
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+

Note: "requirejs" may need be included in a global context for `Comm` targets
using the a `target_module` (in the classic Notebook).
This can be as a `<script>` tag in the browser or by using the `requirejs`
package in node (`npm install requirejs` and setting
`global.requirejs = require('requirejs');`).

## Starting the Notebook Server

Follow the package install instructions first.

The library requires a running Jupyter Notebook server, launched as:

```bash
jupyter notebook
```

## Bundling for the Browser

Follow the package install instructions first.

See `examples/browser` for an example of using Webpack to bundle the library.

Note: Some browsers (such as IE11), require a polyfill for Promises.
The example demonstrates the use of the polyfill. See also notes about
the `fetch` API polyfill above.

## Usage from Node.js

Follow the package install instructions first.

See `examples/node` for an example of using an ES5 node script.

## Usage Examples

**Note:** This module is fully compatible with Node/Babel/ES6/ES5. The
examples below are written in TypeScript using ES6 syntax. Simply
omit the type declarations when using a language other than TypeScript.
A translator such as Babel can be used to convert from ES6 -> ES5.

**Kernel**

```typescript
import { KernelMessage, Kernel } from 'sophon-notebook-services';

// Get a list of available kernels and connect to one.
Kernel.listRunning().then(kernelModels => {
  const kernel = Kernel.connectTo(kernelModels[0]);
  console.log(kernel.name);
});

// Get info about the available kernels and start a new one.
Kernel.getSpecs().then(kernelSpecs => {
  console.log('Default spec:', kernelSpecs.default);
  console.log('Available specs', Object.keys(kernelSpecs.kernelspecs));
  // use the default name
  let options: Kernel.IOptions = {
    name: kernelSpecs.default
  };
  Kernel.startNew(options).then(kernel => {
    // Execute and handle replies.
    let future = kernel.requestExecute({ code: 'a = 1' });
    future.done.then(() => {
      console.log('Future is fulfilled');
    });
    future.onIOPub = msg => {
      console.log(msg.content); // Print rich output data.
    };

    // Restart the kernel and then send an inspect message.
    kernel.restart().then(() => {
      let request: KernelMessage.IInspectRequest = {
        code: 'hello',
        cursor_pos: 4,
        detail_level: 0
      };
      kernel.requestInspect(request).then(reply => {
        console.log(reply.content.data);
      });
    });

    // Interrupt the kernel and then send a complete message.
    kernel.interrupt().then(() => {
      kernel.requestComplete({ code: 'impor', cursor_pos: 4 }).then(reply => {
        console.log(reply.content.matches);
      });
    });

    // Register a callback for when the kernel changes state.
    kernel.statusChanged.connect(status => {
      console.log('status', status);
    });

    // Kill the kernel.
    kernel.shutdown().then(() => {
      console.log('Kernel shut down');
    });
  });
});
```

**Session**

```typescript
import { Session } from 'sophon-notebook-services';

// Get a list of available sessions and connect to one.
Session.listRunning().then(sessionModels => {
  const session = Session.connectTo(sessionModels[0]);
  console.log(session.kernel.name);
});

// Start a new session.
let options = {
  kernelName: 'python',
  path: '/tmp/foo.ipynb'
};

Session.startNew(options).then(session => {
  // Execute and handle replies on the kernel.
  let future = session.kernel.requestExecute({ code: 'a = 1' });
  future.done.then(() => {
    console.log('Future is fulfilled');
  });

  // Rename the session.
  session.setPath('/local/bar.ipynb').then(() => {
    console.log('Session renamed to', session.path);
  });

  // Register a callback for when the session dies.
  session.terminated.connect(() => {
    console.log('session died');
  });

  // Kill the session.
  session.shutdown().then(() => {
    console.log('session closed');
  });
});
```

**Comm**

```typescript
import { Kernel } from 'sophon-notebook-services';

// Create a comm from the server side.
//
// Get info about the available kernels and connect to one.
Kernel.getSpecs()
  .then(kernelSpecs => {
    return Kernel.startNew({
      name: kernelSpecs.default
    });
  })
  .then(kernel => {
    let comm = kernel.connectToComm('test').then(comm => {
      comm.open('initial state');
      comm.send('test');
      comm.close('bye');
    });
  });

// Create a comm from the client side.
Kernel.getSpecs()
  .then(kernelSpecs => {
    return Kernel.startNew({
      name: kernelSpecs.default
    });
  })
  .then(kernel => {
    kernel.registerCommTarget('test2', (comm, commMsg) => {
      if (commMsg.content.target_name !== 'test2') {
        return;
      }
      comm.onMsg = msg => {
        console.log(msg); // 'hello'
      };
      comm.onClose = msg => {
        console.log(msg); // 'bye'
      };
    });

    let code = [
      'from ipykernel.comm import Comm',
      'comm = Comm(target_name="test2")',
      'comm.send(data="hello")',
      'comm.close(data="bye")'
    ].join('\n');
    kernel.requestExecute({ code: code });
  });
```

**Contents**

```typescript
import { ContentsManager } from 'sophon-notebook-services';

let contents = new ContentsManager();

// Create a new python file.
contents.newUntitled({ path: '/foo', type: 'file', ext: 'py' }).then(model => {
  console.log('new file:', model.path);
});

// Get the contents of a directory.
contents.get('/foo/bar').then(model => {
  console.log('files:', model.content);
});

// Rename a file.
contents.rename('/foo/bar.txt', '/foo/baz.txt');

// Save a file.
contents.save('/foo/test.ipynb');

// Delete a file.
contents.delete('/foo/bar.txt');

// Copy a file.
contents.copy('/foo/bar.txt', '/baz').then(model => {
  console.log('new path', model.path);
});

// Create a checkpoint.
contents.createCheckpoint('/foo/bar.ipynb').then(model => {
  let checkpoint = model;

  // Restore a checkpoint.
  contents.restoreCheckpoint('/foo/bar.ipynb', checkpoint.id);

  // Delete a checkpoint.
  contents.deleteCheckpoint('/foo/bar.ipynb', checkpoint.id);
});

// List checkpoints for a file.
contents.listCheckpoints('/foo/bar.txt').then(models => {
  console.log(models[0].id);
});
```

**Configuration**

```typescript
import { ConfigWithDefaults, ConfigSection } from 'sophon-notebook-services';

// The base url of the Jupyter server.

ConfigSection.create({ name: 'notebook' }).then(section => {
  let config = new ConfigWithDefaults({
    section,
    defaults: { default_cell_type: 'code' },
    className: 'Notebook'
  });
  console.log(config.get('default_cell_type')); // 'code'
  config.set('foo', 'bar').then(data => {
    console.log(data); // "{ 'foo': 'bar' }"
  });
});
```

**Terminals**

```typescript
import { TerminalSession } from 'sophon-notebook-services';

// Create a named terminal session and send some data.
TerminalSession.startNew().then(session => {
  session.send({ type: 'stdin', content: ['foo'] });
});
```

---
_Source: https://npm.io/package/sophon-notebook-services · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._