@jupyterlab/services

@jupyterlab/services

Version 7.0.9
Published 9 days ago
1.2 MB
11 dependencies
BSD-3-Clause license

Install

npm i @jupyterlab/services

yarn add @jupyterlab/services

pnpm add @jupyterlab/services

Overview

services

Index

Classes

class BaseManager

abstract class BaseManager implements IManager {}

constructor

constructor(options: BaseManager.IOptions);

property connectionFailure

abstract connectionFailure: ISignal<this, Error>;

A signal emitted when there is a connection failure.

property disposed

readonly disposed: ISignal<this, void>;

A signal emitted when the delegate is disposed.

property isActive

readonly isActive: boolean;

Whether the manager is active.

property isDisposed

readonly isDisposed: boolean;

Test whether the delegate has been disposed.

property isReady

abstract isReady: boolean;

Test whether the manager is ready.

property ready

abstract ready: Promise<void>;

A promise that fulfills when the manager is ready.

property serverSettings

readonly serverSettings: ServerConnection.ISettings;

The server settings of the manager.

method dispose

dispose: () => void;

Dispose of the delegate and invoke the callback function.

class ConfigWithDefaults

class ConfigWithDefaults {}

Configurable object with defaults.

constructor

constructor(options: ConfigWithDefaults.IOptions);

Create a new config with defaults.

method get

get: (key: string) => JSONValue;

Get data from the config section or fall back to defaults.

method set

set: (key: string, value: JSONValue) => Promise<JSONValue>;

Set a config value.
#### Notes Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/config).
The promise is fulfilled on a valid response and rejected otherwise.
Sends the update to the server, and changes our local copy of the data immediately.

class ContentsManager

class ContentsManager implements Contents.IManager {}

A contents manager that passes file operations to the server. Multiple servers implementing the IDrive interface can be attached to the contents manager, so that the same session can perform file operations on multiple backends.
This includes checkpointing with the normal file operations.

constructor

constructor(options?: ContentsManager.IOptions);

Construct a new contents manager object.
Parameter options
The options used to initialize the object.

property fileChanged

readonly fileChanged: ISignal<this, Contents.IChangedArgs>;

A signal emitted when a file operation takes place.

property isDisposed

readonly isDisposed: boolean;

Test whether the manager has been disposed.

property serverSettings

readonly serverSettings: ServerConnection.ISettings;

The server settings associated with the manager.

method addDrive

addDrive: (drive: Contents.IDrive) => void;

Add an IDrive to the manager.

method copy

copy: (fromFile: string, toDir: string) => Promise<Contents.IModel>;

Copy a file into a given directory.
Parameter path
The original file path.
Parameter toDir
The destination directory path.
Returns
A promise which resolves with the new contents model when the file is copied.
#### Notes The server will select the name of the copied file.

method createCheckpoint

createCheckpoint: (path: string) => Promise<Contents.ICheckpointModel>;

Create a checkpoint for a file.
Parameter path
The path of the file.
Returns
A promise which resolves with the new checkpoint model when the checkpoint is created.

method delete

delete: (path: string) => Promise<void>;

Delete a file.
Parameter path
The path to the file.
Returns
A promise which resolves when the file is deleted.

method deleteCheckpoint

deleteCheckpoint: (path: string, checkpointID: string) => Promise<void>;

Delete a checkpoint for a file.
Parameter path
The path of the file.
Parameter checkpointID
The id of the checkpoint to delete.
Returns
A promise which resolves when the checkpoint is deleted.

method dispose

dispose: () => void;

Dispose of the resources held by the manager.

method driveName

driveName: (path: string) => string;

Given a path of the form drive:local/portion/of/it.txt get the name of the drive. If the path is missing a drive portion, returns an empty string.
Parameter path
: the path.
Returns
The drive name for the path, or the empty string.

method get

get: (
    path: string,
    options?: Contents.IFetchOptions
) => Promise<Contents.IModel>;

Get a file or directory.
Parameter path
: The path to the file.
Parameter options
: The options used to fetch the file.
Returns
A promise which resolves with the file content.

method getDownloadUrl

getDownloadUrl: (path: string) => Promise<string>;

Get an encoded download url given a file path.
Parameter path
An absolute POSIX file path on the server.
#### Notes It is expected that the path contains no relative paths.
The returned URL may include a query parameter.

method getSharedModelFactory

getSharedModelFactory: (path: string) => Contents.ISharedFactory | null;

Given a path, get a shared model factory from the relevant backend. Returns null if the backend does not provide one.

method listCheckpoints

listCheckpoints: (path: string) => Promise<Contents.ICheckpointModel[]>;

List available checkpoints for a file.
Parameter path
The path of the file.
Returns
A promise which resolves with a list of checkpoint models for the file.

method localPath

localPath: (path: string) => string;

Given a path of the form drive:local/portion/of/it.txt get the local part of it.
Parameter path
: the path.
Returns
The local part of the path.

method newUntitled

newUntitled: (options?: Contents.ICreateOptions) => Promise<Contents.IModel>;

Create a new untitled file or directory in the specified directory path.
Parameter options
: The options used to create the file.
Returns
A promise which resolves with the created file content when the file is created.

method normalize

normalize: (path: string) => string;

Normalize a global path. Reduces '..' and '.' parts, and removes leading slashes from the local part of the path, while retaining the drive name if it exists.
Parameter path
: the path.
Returns
The normalized path.

method rename

rename: (path: string, newPath: string) => Promise<Contents.IModel>;

Rename a file or directory.
Parameter path
The original file path.
Parameter newPath
The new file path.
Returns
A promise which resolves with the new file contents model when the file is renamed.

method resolvePath

resolvePath: (root: string, path: string) => string;

Resolve a global path, starting from the root path. Behaves like posix-path.resolve, with 3 differences: - will never prepend cwd - if root has a drive name, the result is prefixed with ":" - before adding drive name, leading slashes are removed
Parameter path
: the path.
Returns
The normalized path.

method restoreCheckpoint

restoreCheckpoint: (path: string, checkpointID: string) => Promise<void>;

Restore a file to a known checkpoint state.
Parameter path
The path of the file.
Parameter checkpointID
The id of the checkpoint to restore.
Returns
A promise which resolves when the checkpoint is restored.

method save

save: (
    path: string,
    options?: Partial<Contents.IModel>
) => Promise<Contents.IModel>;

Save a file.
Parameter path
The desired file path.
Parameter options
Optional overrides to the model.
Returns
A promise which resolves with the file content model when the file is saved.
#### Notes Ensure that model.content is populated for the file.

class Drive

class Drive implements Contents.IDrive {}

A default implementation for an IDrive, talking to the server using the Jupyter REST API.

constructor

constructor(options?: Drive.IOptions);

Construct a new contents manager object.
Parameter options
The options used to initialize the object.

property fileChanged

readonly fileChanged: ISignal<this, Contents.IChangedArgs>;

A signal emitted when a file operation takes place.

property isDisposed

readonly isDisposed: boolean;

Test whether the manager has been disposed.

property name

readonly name: string;

The name of the drive, which is used at the leading component of file paths.

property serverSettings

readonly serverSettings: ServerConnection.ISettings;

The server settings of the drive.

method copy

copy: (fromFile: string, toDir: string) => Promise<Contents.IModel>;

Copy a file into a given directory.
Parameter localPath
The original file path.
Parameter toDir
The destination directory path.
Returns
A promise which resolves with the new contents model when the file is copied.
#### Notes The server will select the name of the copied file.
Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/contents) and validates the response model.

method createCheckpoint

createCheckpoint: (localPath: string) => Promise<Contents.ICheckpointModel>;

Create a checkpoint for a file.
Parameter localPath
The path of the file.
Returns
A promise which resolves with the new checkpoint model when the checkpoint is created.
#### Notes Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/contents) and validates the response model.

method delete

delete: (localPath: string) => Promise<void>;

Delete a file.
Parameter localPath
The path to the file.
Returns
A promise which resolves when the file is deleted.
#### Notes Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/contents).

method deleteCheckpoint

deleteCheckpoint: (localPath: string, checkpointID: string) => Promise<void>;

Delete a checkpoint for a file.
Parameter localPath
The path of the file.
Parameter checkpointID
The id of the checkpoint to delete.
Returns
A promise which resolves when the checkpoint is deleted.
#### Notes Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/contents).

method dispose

dispose: () => void;

Dispose of the resources held by the manager.

method get

get: (
    localPath: string,
    options?: Contents.IFetchOptions
) => Promise<Contents.IModel>;

Get a file or directory.
Parameter localPath
: The path to the file.
Parameter options
: The options used to fetch the file.
Returns
A promise which resolves with the file content.
Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/contents) and validates the response model.

method getDownloadUrl

getDownloadUrl: (localPath: string) => Promise<string>;

Get an encoded download url given a file path.
Parameter localPath
An absolute POSIX file path on the server.
#### Notes It is expected that the path contains no relative paths.
The returned URL may include a query parameter.

method listCheckpoints

listCheckpoints: (localPath: string) => Promise<Contents.ICheckpointModel[]>;

List available checkpoints for a file.
Parameter localPath
The path of the file.
Returns
A promise which resolves with a list of checkpoint models for the file.
#### Notes Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/contents) and validates the response model.

method newUntitled

newUntitled: (options?: Contents.ICreateOptions) => Promise<Contents.IModel>;

Create a new untitled file or directory in the specified directory path.
Parameter options
: The options used to create the file.
Returns
A promise which resolves with the created file content when the file is created.
#### Notes Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/contents) and validates the response model.

method rename

rename: (oldLocalPath: string, newLocalPath: string) => Promise<Contents.IModel>;

Rename a file or directory.
Parameter oldLocalPath
The original file path.
Parameter newLocalPath
The new file path.
Returns
A promise which resolves with the new file contents model when the file is renamed.
#### Notes Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/contents) and validates the response model.

method restoreCheckpoint

restoreCheckpoint: (localPath: string, checkpointID: string) => Promise<void>;

Restore a file to a known checkpoint state.
Parameter localPath
The path of the file.
Parameter checkpointID
The id of the checkpoint to restore.
Returns
A promise which resolves when the checkpoint is restored.
#### Notes Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/contents).

method save

save: (
    localPath: string,
    options?: Partial<Contents.IModel>
) => Promise<Contents.IModel>;

Save a file.
Parameter localPath
The desired file path.
Parameter options
Optional overrides to the model.
Returns
A promise which resolves with the file content model when the file is saved.
#### Notes Ensure that model.content is populated for the file.
Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/contents) and validates the response model.

class EventManager

class EventManager implements Event.IManager {}

The events API service manager.

constructor

constructor(options?: EventManager.IOptions);

Create a new event manager.

property isDisposed

readonly isDisposed: boolean;

Whether the event manager is disposed.

property serverSettings

readonly serverSettings: ServerConnection.ISettings;

The server settings used to make API requests.

property stream

readonly stream: IStream<Event.IManager, any>;

An event stream that emits and yields each new event.

method dispose

dispose: () => void;

Dispose the event manager.

method emit

emit: (event: Event.Request) => Promise<void>;

Post an event request to be emitted by the event bus.

class KernelConnection

class KernelConnection implements Kernel.IKernelConnection {}

Implementation of the Kernel object.
#### Notes Messages from the server are handled in the order they were received and asynchronously. Any message handler can return a promise, and message handling will pause until the promise is fulfilled.

constructor

constructor(options: Kernel.IKernelConnection.IOptions);

Construct a kernel object.

property anyMessage

readonly anyMessage: ISignal<this, Kernel.IAnyMessageArgs>;

A signal emitted for any kernel message.
#### Notes This signal is emitted when a message is received, before it is handled asynchronously.
This message is emitted when a message is queued for sending (either in the websocket buffer, or our own pending message buffer). The message may actually be sent across the wire at a later time.
The message emitted in this signal should not be modified in any way.

property clientId

readonly clientId: string;

The client unique id.

property connectionStatus

readonly connectionStatus: Kernel.ConnectionStatus;

The current connection status of the kernel connection.

property connectionStatusChanged

readonly connectionStatusChanged: ISignal<this, Kernel.ConnectionStatus>;

A signal emitted when the kernel status changes.

property disposed

readonly disposed: ISignal<this, void>;

property handleComms

readonly handleComms: boolean;

Handle comm messages
#### Notes The comm message protocol currently has implicit assumptions that only one kernel connection is handling comm messages. This option allows a kernel connection to opt out of handling comms.
See https://github.com/jupyter/jupyter_client/issues/263

property hasPendingInput

hasPendingInput: boolean;

property id

readonly id: string;

The id of the server-side kernel.

property info

readonly info: Promise<KernelMessage.IInfoReply>;

The cached kernel info.
Returns
A promise that resolves to the kernel info.

property iopubMessage

readonly iopubMessage: ISignal<
    this,
    KernelMessage.IIOPubMessage<KernelMessage.IOPubMessageType>
>;

A signal emitted for iopub kernel messages.
#### Notes This signal is emitted after the iopub message is handled asynchronously.

property isDisposed

readonly isDisposed: boolean;

Test whether the kernel has been disposed.

property model

readonly model: Kernel.IModel;

The kernel model

property name

readonly name: string;

The name of the server-side kernel.

property pendingInput

readonly pendingInput: ISignal<this, boolean>;

A signal emitted when a kernel has pending inputs from the user.

property serverSettings

readonly serverSettings: ServerConnection.ISettings;

The server settings for the kernel.

property spec

readonly spec: Promise<KernelSpec.ISpecModel>;

The kernel spec.
Returns
A promise that resolves to the kernel spec.

property status

readonly status: Kernel.Status;

The current status of the kernel.

property statusChanged

readonly statusChanged: ISignal<this, Kernel.Status>;

A signal emitted when the kernel status changes.

property unhandledMessage

readonly unhandledMessage: ISignal<
    this,
    KernelMessage.IMessage<KernelMessage.MessageType>
>;

A signal emitted for unhandled kernel message.
#### Notes This signal is emitted for a message that was not handled. It is emitted during the asynchronous message handling code.

property username

readonly username: string;

The client username.

method clone

clone: (
    options?: Pick<
        Kernel.IKernelConnection.IOptions,
        'clientId' | 'username' | 'handleComms'
    >
) => Kernel.IKernelConnection;

Clone the current kernel with a new clientId.

method createComm

createComm: (targetName: string, commId?: string) => Kernel.IComm;

Create a new comm.
#### Notes If a client-side comm already exists with the given commId, an error is thrown. If the kernel does not handle comms, an error is thrown.

method dispose

dispose: () => void;

Dispose of the resources held by the kernel.

method handleShutdown

handleShutdown: () => void;

Handles a kernel shutdown.
#### Notes This method should be called if we know from outside information that a kernel is dead (for example, we cannot find the kernel model on the server).

method hasComm

hasComm: (commId: string) => boolean;

Check if a comm exists.

method interrupt

interrupt: () => Promise<void>;

Interrupt a kernel.
#### Notes Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/kernels).
The promise is fulfilled on a valid response and rejected otherwise.
It is assumed that the API call does not mutate the kernel id or name.
The promise will be rejected if the kernel status is Dead or if the request fails or the response is invalid.

method reconnect

reconnect: () => Promise<void>;

Reconnect to a kernel.
#### Notes This may try multiple times to reconnect to a kernel, and will sever any existing connection.

method registerCommTarget

registerCommTarget: (
    targetName: string,
    callback: (
        comm: Kernel.IComm,
        msg: KernelMessage.ICommOpenMsg
    ) => void | PromiseLike<void>
) => void;

Register a comm target handler.
Parameter targetName
The name of the comm target.
Parameter callback
The callback invoked for a comm open message.
Returns
A disposable used to unregister the comm target.
#### Notes Only one comm target can be registered to a target name at a time, an existing callback for the same target name will be overridden. A registered comm target handler will take precedence over a comm which specifies a target_module.
If the callback returns a promise, kernel message processing will pause until the returned promise is fulfilled.

method registerMessageHook

registerMessageHook: (
    msgId: string,
    hook: (msg: KernelMessage.IIOPubMessage) => boolean | PromiseLike<boolean>
) => void;

Register an IOPub message hook.
Parameter msg_id
The parent_header message id the hook will intercept.
Parameter hook
The callback invoked for the message.
#### Notes The IOPub hook system allows you to preempt the handlers for IOPub messages that are responses to a given message id.
The most recently registered hook is run first. A hook can return a boolean or a promise to a boolean, in which case all kernel message processing pauses until the promise is fulfilled. If a hook return value resolves to false, any later hooks will not run and the function will return a promise resolving to false. If a hook throws an error, the error is logged to the console and the next hook is run. If a hook is registered during the hook processing, it will not run until the next message. If a hook is removed during the hook processing, it will be deactivated immediately.
See also [[IFuture.registerMessageHook]].

method removeCommTarget

removeCommTarget: (
    targetName: string,
    callback: (
        comm: Kernel.IComm,
        msg: KernelMessage.ICommOpenMsg
    ) => void | PromiseLike<void>
) => void;

Remove a comm target handler.
Parameter targetName
The name of the comm target to remove.
Parameter callback
The callback to remove.
#### Notes The comm target is only removed if the callback argument matches.

method removeInputGuard

removeInputGuard: () => void;

Remove the input guard, if any.

method removeMessageHook

removeMessageHook: (
    msgId: string,
    hook: (msg: KernelMessage.IIOPubMessage) => boolean | PromiseLike<boolean>
) => void;

Remove an IOPub message hook.
Parameter msg_id
The parent_header message id the hook intercepted.
Parameter hook
The callback invoked for the message.

method requestCommInfo

requestCommInfo: (
    content: KernelMessage.ICommInfoRequestMsg['content']
) => Promise<KernelMessage.ICommInfoReplyMsg>;

Send a comm_info_request message.
#### Notes Fulfills with the comm_info_reply content when the shell reply is received and validated.

method requestComplete

requestComplete: (
    content: KernelMessage.ICompleteRequestMsg['content']
) => Promise<KernelMessage.ICompleteReplyMsg>;

Send a complete_request message.
#### Notes See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#completion).
Fulfills with the complete_reply content when the shell reply is received and validated.

method requestDebug

requestDebug: (
    content: KernelMessage.IDebugRequestMsg['content'],
    disposeOnDone?: boolean
) => Kernel.IControlFuture<
    KernelMessage.IDebugRequestMsg,
    KernelMessage.IDebugReplyMsg
>;

Send an experimental debug_request message.
#### Notes Debug messages are experimental messages that are not in the official kernel message specification. As such, this function is *NOT* considered part of the public API, and may change without notice.

method requestExecute

requestExecute: (
    content: KernelMessage.IExecuteRequestMsg['content'],
    disposeOnDone?: boolean,
    metadata?: JSONObject
) => Kernel.IShellFuture<
    KernelMessage.IExecuteRequestMsg,
    KernelMessage.IExecuteReplyMsg
>;

Send an execute_request message.
#### Notes See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#execute).
Future onReply is called with the execute_reply content when the shell reply is received and validated. The future will resolve when this message is received and the idle iopub status is received. The future will also be disposed at this point unless disposeOnDone is specified and false, in which case it is up to the caller to dispose of the future.
**See also:** [[IExecuteReply]]

method requestHistory

requestHistory: (
    content: KernelMessage.IHistoryRequestMsg['content']
) => Promise<KernelMessage.IHistoryReplyMsg>;

Send a history_request message.
#### Notes See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#history).
Fulfills with the history_reply content when the shell reply is received and validated.

method requestInspect

requestInspect: (
    content: KernelMessage.IInspectRequestMsg['content']
) => Promise<KernelMessage.IInspectReplyMsg>;

Send an inspect_request message.
#### Notes See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#introspection).
Fulfills with the inspect_reply content when the shell reply is received and validated.

method requestIsComplete

requestIsComplete: (
    content: KernelMessage.IIsCompleteRequestMsg['content']
) => Promise<KernelMessage.IIsCompleteReplyMsg>;

Send an is_complete_request message.
#### Notes See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#code-completeness).
Fulfills with the is_complete_response content when the shell reply is received and validated.

method requestKernelInfo

requestKernelInfo: () => Promise<KernelMessage.IInfoReplyMsg | undefined>;

Send a kernel_info_request message.
#### Notes See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#kernel-info).
Fulfills with the kernel_info_response content when the shell reply is received and validated.

method restart

restart: () => Promise<void>;

Request a kernel restart.
#### Notes Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/kernels) and validates the response model.
Any existing Future or Comm objects are cleared once the kernel has actually be restarted.
The promise is fulfilled on a valid server response (after the kernel restarts) and rejected otherwise.
It is assumed that the API call does not mutate the kernel id or name.
The promise will be rejected if the request fails or the response is invalid.

method sendControlMessage

sendControlMessage: <T extends KernelMessage.ControlMessageType>(
    msg: KernelMessage.IControlMessage<T>,
    expectReply?: boolean,
    disposeOnDone?: boolean
) => Kernel.IControlFuture<KernelMessage.IControlMessage<T>>;

Send a control message to the kernel.
#### Notes Send a message to the kernel's control channel, yielding a future object for accepting replies.
If expectReply is given and true, the future is disposed when both a control reply and an idle status message are received. If expectReply is not given or is false, the future is resolved when an idle status message is received. If disposeOnDone is not given or is true, the Future is disposed at this point. If disposeOnDone is given and false, it is up to the caller to dispose of the Future.
All replies are validated as valid kernel messages.
If the kernel status is dead, this will throw an error.

method sendInputReply

sendInputReply: (
    content: KernelMessage.IInputReplyMsg['content'],
    parent_header: KernelMessage.IInputReplyMsg['parent_header']
) => void;

Send an input_reply message.
#### Notes See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#messages-on-the-stdin-router-dealer-sockets).

method sendShellMessage

sendShellMessage: <T extends KernelMessage.ShellMessageType>(
    msg: KernelMessage.IShellMessage<T>,
    expectReply?: boolean,
    disposeOnDone?: boolean
) => Kernel.IShellFuture<KernelMessage.IShellMessage<T>>;

Send a shell message to the kernel.
#### Notes Send a message to the kernel's shell channel, yielding a future object for accepting replies.
If expectReply is given and true, the future is disposed when both a shell reply and an idle status message are received. If expectReply is not given or is false, the future is resolved when an idle status message is received. If disposeOnDone is not given or is true, the Future is disposed at this point. If disposeOnDone is given and false, it is up to the caller to dispose of the Future.
All replies are validated as valid kernel messages.
If the kernel status is dead, this will throw an error.

method shutdown

shutdown: () => Promise<void>;

Shutdown a kernel.
#### Notes Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/kernels).
The promise is fulfilled on a valid response and rejected otherwise.
On a valid response, disposes this kernel connection.
If the kernel is already dead, disposes this kernel connection without a server request.

class KernelManager

class KernelManager extends BaseManager implements Kernel.IManager {}

An implementation of a kernel manager.

constructor

constructor(options?: KernelManager.IOptions);

Construct a new kernel manager.
Parameter options
The default options for kernel.

property connectionFailure

readonly connectionFailure: ISignal<this, Error>;

A signal emitted when there is a connection failure.

property isReady

readonly isReady: boolean;

Test whether the manager is ready.

property ready

readonly ready: Promise<void>;

A promise that fulfills when the manager is ready.

property runningChanged

readonly runningChanged: ISignal<this, Kernel.IModel[]>;

A signal emitted when the running kernels change.

property serverSettings

readonly serverSettings: ServerConnection.ISettings;

The server settings for the manager.

method connectTo

connectTo: (
    options: Omit<Kernel.IKernelConnection.IOptions, 'serverSettings'>
) => Kernel.IKernelConnection;

Connect to an existing kernel.
Returns
The new kernel connection.
#### Notes This will use the manager's server settings and ignore any server settings passed in the options.

method dispose

dispose: () => void;

Dispose of the resources used by the manager.

method findById

findById: (id: string) => Promise<Kernel.IModel | undefined>;

Find a kernel by id.
Parameter id
The id of the target kernel.
Returns
A promise that resolves with the kernel's model.

method refreshRunning

refreshRunning: () => Promise<void>;

Force a refresh of the running kernels.
Returns
A promise that resolves when the running list has been refreshed.
#### Notes This is not typically meant to be called by the user, since the manager maintains its own internal state.

method requestRunning

protected requestRunning: () => Promise<void>;

Execute a request to the server to poll running kernels and update state.

method running

running: () => IterableIterator<Kernel.IModel>;

Create an iterator over the most recent running kernels.
Returns
A new iterator over the running kernels.

method shutdown

shutdown: (id: string) => Promise<void>;

Shut down a kernel by id.
Parameter id
The id of the target kernel.
Returns
A promise that resolves when the operation is complete.

method shutdownAll

shutdownAll: () => Promise<void>;

Shut down all kernels.
Returns
A promise that resolves when all of the kernels are shut down.

method startNew

startNew: (
    createOptions?: IKernelOptions,
    connectOptions?: Omit<
        Kernel.IKernelConnection.IOptions,
        'model' | 'serverSettings'
    >
) => Promise<Kernel.IKernelConnection>;

Start a new kernel.
Parameter createOptions
The kernel creation options
Parameter connectOptions
The kernel connection options
Returns
A promise that resolves with the kernel connection.
#### Notes The manager serverSettings will be always be used.

class KernelSpecManager

class KernelSpecManager extends BaseManager implements KernelSpec.IManager {}

An implementation of a kernel spec manager.

constructor

constructor(options?: KernelSpecManager.IOptions);

Construct a new kernel spec manager.
Parameter options
The default options for kernel.

property connectionFailure

readonly connectionFailure: ISignal<this, Error>;

A signal emitted when there is a connection failure.

property isReady

readonly isReady: boolean;

Test whether the manager is ready.

property ready

readonly ready: Promise<void>;

A promise that fulfills when the manager is ready.

property serverSettings

readonly serverSettings: ServerConnection.ISettings;

The server settings for the manager.

property specs

readonly specs: KernelSpec.ISpecModels;

Get the most recently fetched kernel specs.

property specsChanged

readonly specsChanged: ISignal<this, KernelSpec.ISpecModels>;

A signal emitted when the specs change.

method dispose

dispose: () => void;

Dispose of the resources used by the manager.

method refreshSpecs

refreshSpecs: () => Promise<void>;

Force a refresh of the specs from the server.
Returns
A promise that resolves when the specs are fetched.
#### Notes This is intended to be called only in response to a user action, since the manager maintains its internal state.

method requestSpecs

protected requestSpecs: () => Promise<void>;

Execute a request to the server to poll specs and update state.

class NbConvertManager

class NbConvertManager {}

The nbconvert API service manager.

constructor

constructor(options?: NbConvertManager.IOptions);

Create a new nbconvert manager.

property serverSettings

readonly serverSettings: ServerConnection.ISettings;

The server settings used to make API requests.

method fetchExportFormats

protected fetchExportFormats: () => Promise<NbConvertManager.IExportFormats>;

Fetch and cache the export formats from the expensive nbconvert handler.

method getExportFormats

getExportFormats: (force?: boolean) => Promise<NbConvertManager.IExportFormats>;

Get the list of export formats, preferring pre-cached ones.

class ServiceManager

class ServiceManager implements ServiceManager.IManager {}

A Jupyter services manager.

constructor

constructor(options?: Partial<ServiceManager.IOptions>);

Construct a new services provider.

property builder

readonly builder: Builder.IManager;

The builder for the manager.

property connectionFailure

readonly connectionFailure: ISignal<this, Error>;

A signal emitted when there is a connection failure with the kernel.

property contents

readonly contents: Contents.IManager;

Get the contents manager instance.

property events

readonly events: Event.IManager;

The event manager instance.

property isDisposed

readonly isDisposed: boolean;

Test whether the service manager is disposed.

property isReady

readonly isReady: boolean;

Test whether the manager is ready.

property kernels

readonly kernels: Kernel.IManager;

Get the kernel manager instance.

property kernelspecs

readonly kernelspecs: KernelSpec.IManager;

Get the kernelspec manager instance.

property nbconvert

readonly nbconvert: NbConvert.IManager;

Get the nbconvert manager instance.

property ready

readonly ready: Promise<void>;

A promise that fulfills when the manager is ready.

property serverSettings

readonly serverSettings: ServerConnection.ISettings;

The server settings of the manager.

property sessions

readonly sessions: Session.IManager;

Get the session manager instance.

property settings

readonly settings: Setting.IManager;

Get the setting manager instance.

property terminals

readonly terminals: Terminal.IManager;

Get the terminal manager instance.

property user

readonly user: User.IManager;

Get the user manager instance.

property workspaces

readonly workspaces: Workspace.IManager;

Get the workspace manager instance.

method dispose

dispose: () => void;

Dispose of the resources used by the manager.

class SessionManager

class SessionManager extends BaseManager implements Session.IManager {}

An implementation of a session manager.

constructor

constructor(options: SessionManager.IOptions);

Construct a new session manager.
Parameter options
The default options for each session.

property connectionFailure

readonly connectionFailure: ISignal<this, Error>;

A signal emitted when there is a connection failure.

property isReady

readonly isReady: boolean;

Test whether the manager is ready.

property ready

readonly ready: Promise<void>;

A promise that fulfills when the manager is ready.

property runningChanged

readonly runningChanged: ISignal<this, Session.IModel[]>;

A signal emitted when the running sessions change.

property serverSettings

readonly serverSettings: ServerConnection.ISettings;

The server settings for the manager.

method connectTo

connectTo: (
    options: Omit<
        Session.ISessionConnection.IOptions,
        'connectToKernel' | 'serverSettings'
    >
) => Session.ISessionConnection;

method dispose

dispose: () => void;

Dispose of the resources used by the manager.

method findById

findById: (id: string) => Promise<Session.IModel | undefined>;

Find a session by id.

method findByPath

findByPath: (path: string) => Promise<Session.IModel | undefined>;

Find a session by path.

method refreshRunning

refreshRunning: () => Promise<void>;

Force a refresh of the running sessions.
Returns
A promise that with the list of running sessions.
#### Notes This is not typically meant to be called by the user, since the manager maintains its own internal state.

method requestRunning

protected requestRunning: () => Promise<void>;

Execute a request to the server to poll running kernels and update state.

method running

running: () => IterableIterator<Session.IModel>;

Create an iterator over the most recent running sessions.
Returns
A new iterator over the running sessions.

method shutdown

shutdown: (id: string) => Promise<void>;

Shut down a session by id.

method shutdownAll

shutdownAll: () => Promise<void>;

Shut down all sessions.
Returns
A promise that resolves when all of the kernels are shut down.

method startNew

startNew: (
    createOptions: Session.ISessionOptions,
    connectOptions?: Omit<
        Session.ISessionConnection.IOptions,
        'model' | 'connectToKernel' | 'serverSettings'
    >
) => Promise<Session.ISessionConnection>;

Start a new session. See also [[startNewSession]].
Parameter createOptions
Options for creating the session
Parameter connectOptions
Options for connecting to the session

method stopIfNeeded

stopIfNeeded: (path: string) => Promise<void>;

Find a session associated with a path and stop it if it is the only session using that kernel.
Parameter path
The path in question.
Returns
A promise that resolves when the relevant sessions are stopped.

class SettingManager

class SettingManager extends DataConnector<ISettingRegistry.IPlugin, string> {}

The settings API service manager.

constructor

constructor(options?: SettingManager.IOptions);

Create a new setting manager.

property serverSettings

readonly serverSettings: ServerConnection.ISettings;

The server settings used to make API requests.

method fetch

fetch: (id: string) => Promise<ISettingRegistry.IPlugin>;

Fetch a plugin's settings.
Parameter id
The plugin's ID.
Returns
A promise that resolves if successful.

method list

list: (
    query?: 'ids'
) => Promise<{ ids: string[]; values: ISettingRegistry.IPlugin[] }>;

Fetch the list of all plugin setting bundles.
Returns
A promise that resolves if successful.

method save

save: (id: string, raw: string) => Promise<void>;

Save a plugin's settings.
Parameter id
The plugin's ID.
Parameter raw
The user setting values as a raw string of JSON with comments.
Returns
A promise that resolves if successful.

class TerminalManager

class TerminalManager extends BaseManager implements Terminal.IManager {}

A terminal session manager.

constructor

constructor(options?: TerminalManager.IOptions);

Construct a new terminal manager.

property connectionFailure

readonly connectionFailure: ISignal<this, Error>;

A signal emitted when there is a connection failure.

property isReady

readonly isReady: boolean;

Test whether the manager is ready.

property ready

readonly ready: Promise<void>;

A promise that fulfills when the manager is ready.

property runningChanged

readonly runningChanged: ISignal<this, Terminal.IModel[]>;

A signal emitted when the running terminals change.

property serverSettings

readonly serverSettings: ServerConnection.ISettings;

The server settings of the manager.

method connectTo

connectTo: (
    options: Omit<Terminal.ITerminalConnection.IOptions, 'serverSettings'>
) => Terminal.ITerminalConnection;

method dispose

dispose: () => void;

Dispose of the resources used by the manager.

method isAvailable

isAvailable: () => boolean;

Whether the terminal service is available.

method refreshRunning

refreshRunning: () => Promise<void>;

Force a refresh of the running terminals.
Returns
A promise that with the list of running terminals.
#### Notes This is intended to be called only in response to a user action, since the manager maintains its internal state.

method requestRunning

protected requestRunning: () => Promise<void>;

Execute a request to the server to poll running terminals and update state.

method running

running: () => IterableIterator<Terminal.IModel>;

Create an iterator over the most recent running terminals.
Returns
A new iterator over the running terminals.

method shutdown

shutdown: (name: string) => Promise<void>;

Shut down a terminal session by name.

method shutdownAll

shutdownAll: () => Promise<void>;

Shut down all terminal sessions.
Returns
A promise that resolves when all of the sessions are shut down.

method startNew

startNew: (
    options?: Terminal.ITerminal.IOptions
) => Promise<Terminal.ITerminalConnection>;

Create a new terminal session.
Parameter options
The options used to create the terminal.
Returns
A promise that resolves with the terminal connection instance.
#### Notes The manager serverSettings will be used unless overridden in the options.

class UserManager

class UserManager extends BaseManager implements User.IManager {}

The user API service manager.

constructor

constructor(options?: UserManager.IOptions);

Create a new user manager.

property connectionFailure

readonly connectionFailure: ISignal<this, Error>;

A signal emitted when there is a connection failure.

property identity

readonly identity: User.IIdentity;

Get the most recently fetched identity.

property isReady

readonly isReady: boolean;

Test whether the manager is ready.

property permissions

readonly permissions: any;

Get the most recently fetched permissions.

property ready

readonly ready: Promise<void>;

A promise that fulfills when the manager is ready.

property serverSettings

readonly serverSettings: ServerConnection.ISettings;

The server settings for the manager.

property userChanged

readonly userChanged: ISignal<this, User.IUser>;

A signal emitted when the user changes.

method dispose

dispose: () => void;

Dispose of the resources used by the manager.

method refreshUser

refreshUser: () => Promise<void>;

Force a refresh of the specs from the server.
Returns
A promise that resolves when the specs are fetched.
#### Notes This is intended to be called only in response to a user action, since the manager maintains its internal state.

method requestUser

protected requestUser: () => Promise<void>;

Execute a request to the server to poll the user and update state.

class WorkspaceManager

class WorkspaceManager extends DataConnector<Workspace.IWorkspace> {}

The workspaces API service manager.

constructor

constructor(options?: WorkspaceManager.IOptions);

Create a new workspace manager.

property serverSettings

readonly serverSettings: ServerConnection.ISettings;

The server settings used to make API requests.

method fetch

fetch: (id: string) => Promise<Workspace.IWorkspace>;

Fetch a workspace.
Parameter id
The workspace's ID.
Returns
A promise that resolves if successful.

method list

list: () => Promise<{ ids: string[]; values: Workspace.IWorkspace[] }>;

Fetch the list of workspace IDs that exist on the server.
Returns
A promise that resolves if successful.

method remove

remove: (id: string) => Promise<void>;

Remove a workspace from the server.
Parameter id
The workspaces's ID.
Returns
A promise that resolves if successful.

method save

save: (id: string, workspace: Workspace.IWorkspace) => Promise<void>;

Save a workspace.
Parameter id
The workspace's ID.
Parameter workspace
The workspace being saved.
Returns
A promise that resolves if successful.

Interfaces

interface IConfigSection

interface IConfigSection {}

A Configurable data section.

property data

readonly data: JSONObject;

The data for this section.

property serverSettings

readonly serverSettings: ServerConnection.ISettings;

The server settings for the section.

method update

update: (newdata: JSONObject) => Promise<JSONObject>;

Modify the stored config values.
#### Notes Updates the local data immediately, sends the change to the server, and updates the local data with the response, and fulfils the promise with that data.

interface IManager

interface IManager extends IObservableDisposable {}

Object which manages kernel instances for a given base url.
#### Notes The manager is responsible for maintaining the state of kernel specs.

property connectionFailure

connectionFailure: ISignal<IManager, ServerConnection.NetworkError>;

A signal emitted when there is a connection failure.

property isActive

readonly isActive: boolean;

Whether the manager is active.

property isReady

readonly isReady: boolean;

Whether the manager is ready.

property ready

readonly ready: Promise<void>;

A promise that resolves when the manager is initially ready.

property serverSettings

readonly serverSettings: ServerConnection.ISettings;

The server settings for the manager.

Namespaces

namespace BaseManager

namespace BaseManager {}

The namespace for BaseManager class statics.

interface IOptions

interface IOptions {}

The options used to initialize a SessionManager.

property serverSettings

serverSettings?: ServerConnection.ISettings;

The server settings for the manager.

namespace Builder

namespace Builder {}

A namespace for builder API interfaces.

interface IManager

interface IManager extends BuildManager {}

The interface for the build manager.

namespace ConfigSection

namespace ConfigSection {}

The namespace for ConfigSection statics.

function create

create: (options: ConfigSection.IOptions) => Promise<IConfigSection>;

Create a config section.
Returns
A Promise that is fulfilled with the config section is loaded.

interface IOptions

interface IOptions {}

The options used to create a config section.

property name

name: string;

The section name.

property serverSettings

serverSettings?: ServerConnection.ISettings;

The optional server settings.

namespace ConfigWithDefaults

namespace ConfigWithDefaults {}

A namespace for ConfigWithDefaults statics.

interface IOptions

interface IOptions {}

The options used to initialize a ConfigWithDefaults object.

property className

className?: string;

The optional classname namespace.

property defaults

defaults?: JSONObject;

The default values.

property section

section: IConfigSection;

The configuration section.

namespace Contents

namespace Contents {}

A namespace for contents interfaces.

function validateCheckpointModel

validateCheckpointModel: (checkpoint: ICheckpointModel) => void;

Validates an ICheckpointModel, throwing an error if it does not pass.

function validateContentsModel

validateContentsModel: (contents: IModel) => void;

Validates an IModel, throwing an error if it does not pass.

interface IChangedArgs

interface IChangedArgs {}

The change args for a file change.

property newValue

newValue: Partial<IModel> | null;

The old contents.

property oldValue

oldValue: Partial<IModel> | null;

The new contents.

property type

type: 'new' | 'delete' | 'rename' | 'save';

The type of change.

interface ICheckpointModel

interface ICheckpointModel {}

Checkpoint model.

property id

readonly id: string;

The unique identifier for the checkpoint.

property last_modified

readonly last_modified: string;

Last modified timestamp.

interface ICreateOptions

interface ICreateOptions {}

The options used to create a file.

property ext

ext?: string;

The optional file extension for the new file (e.g. ".txt").
#### Notes This ignored if type is 'notebook'.

property path

path?: string;

The directory in which to create the file.

property type

type?: ContentType;

The file type.

interface IDrive

interface IDrive extends IDisposable {}

The interface for a network drive that can be mounted in the contents manager.

property fileChanged

fileChanged: ISignal<IDrive, IChangedArgs>;

A signal emitted when a file operation takes place.

property name

readonly name: string;

The name of the drive, which is used at the leading component of file paths.

property serverSettings

readonly serverSettings: ServerConnection.ISettings;

The server settings of the manager.

property sharedModelFactory

readonly sharedModelFactory?: ISharedFactory;

An optional shared model factory instance for the drive.

method copy

copy: (localPath: string, toLocalDir: string) => Promise<IModel>;

Copy a file into a given directory.
Parameter localPath
The original file path.
Parameter toLocalDir
The destination directory path.
Returns
A promise which resolves with the new content model when the file is copied.

method createCheckpoint

createCheckpoint: (localPath: string) => Promise<ICheckpointModel>;

Create a checkpoint for a file.
Parameter localPath
The path of the file.
Returns
A promise which resolves with the new checkpoint model when the checkpoint is created.

method delete

delete: (localPath: string) => Promise<void>;

Delete a file.
Parameter localPath
The path to the file.
Returns
A promise which resolves when the file is deleted.

method deleteCheckpoint

deleteCheckpoint: (localPath: string, checkpointID: string) => Promise<void>;

Delete a checkpoint for a file.
Parameter localPath
The path of the file.
Parameter checkpointID
The id of the checkpoint to delete.
Returns
A promise which resolves when the checkpoint is deleted.

method get

get: (localPath: string, options?: IFetchOptions) => Promise<IModel>;

Get a file or directory.
Parameter localPath
: The path to the file.
Parameter options
: The options used to fetch the file.
Returns
A promise which resolves with the file content.

method getDownloadUrl

getDownloadUrl: (localPath: string) => Promise<string>;

Get an encoded download url given a file path.
Returns
A promise which resolves with the absolute POSIX file path on the server.
#### Notes The returned URL may include a query parameter.

method listCheckpoints

listCheckpoints: (localPath: string) => Promise<ICheckpointModel[]>;

List available checkpoints for a file.
Parameter localPath
The path of the file.
Returns
A promise which resolves with a list of checkpoint models for the file.

method newUntitled

newUntitled: (options?: ICreateOptions) => Promise<IModel>;

Create a new untitled file or directory in the specified directory path.
Parameter options
: The options used to create the file.
Returns
A promise which resolves with the created file content when the file is created.

method rename

rename: (oldLocalPath: string, newLocalPath: string) => Promise<IModel>;

Rename a file or directory.
Parameter oldLocalPath
The original file path.
Parameter newLocalPath
The new file path.
Returns
A promise which resolves with the new file content model when the file is renamed.

method restoreCheckpoint

restoreCheckpoint: (localPath: string, checkpointID: string) => Promise<void>;

Restore a file to a known checkpoint state.
Parameter localPath
The path of the file.
Parameter checkpointID
The id of the checkpoint to restore.
Returns
A promise which resolves when the checkpoint is restored.

method save

save: (localPath: string, options?: Partial<IModel>) => Promise<IModel>;

Save a file.
Parameter localPath
The desired file path.
Parameter options
Optional overrides to the model.
Returns
A promise which resolves with the file content model when the file is saved.

interface IFetchOptions

interface IFetchOptions {}

The options used to fetch a file.

property content

content?: boolean;

Whether to include the file content.
The default is true.

property format

format?: FileFormat;

The override file format for the request.

property type

type?: ContentType;

The override file type for the request.

interface IManager

interface IManager extends IDisposable {}

The interface for a contents manager.

property fileChanged

readonly fileChanged: ISignal<IManager, IChangedArgs>;

A signal emitted when a file operation takes place.

property serverSettings

readonly serverSettings: ServerConnection.ISettings;

The server settings associated with the manager.

method addDrive

addDrive: (drive: IDrive) => void;

Add an IDrive to the manager.

method copy

copy: (path: string, toDir: string) => Promise<IModel>;

Copy a file into a given directory.
Parameter path
The original file path.
Parameter toDir
The destination directory path.
Returns
A promise which resolves with the new content model when the file is copied.

method createCheckpoint

createCheckpoint: (path: string) => Promise<ICheckpointModel>;

Create a checkpoint for a file.
Parameter path
The path of the file.
Returns
A promise which resolves with the new checkpoint model when the checkpoint is created.

method delete

delete: (path: string) => Promise<void>;

Delete a file.
Parameter path
The path to the file.
Returns
A promise which resolves when the file is deleted.

method deleteCheckpoint

deleteCheckpoint: (path: string, checkpointID: string) => Promise<void>;

Delete a checkpoint for a file.
Parameter path
The path of the file.
Parameter checkpointID
The id of the checkpoint to delete.
Returns
A promise which resolves when the checkpoint is deleted.

method driveName

driveName: (path: string) => string;

Given a path of the form drive:local/portion/of/it.txt get the name of the drive. If the path is missing a drive portion, returns an empty string.
Parameter path
: the path.
Returns
The drive name for the path, or the empty string.

method get

get: (path: string, options?: IFetchOptions) => Promise<IModel>;

Get a file or directory.
Parameter path
: The path to the file.
Parameter options
: The options used to fetch the file.
Returns
A promise which resolves with the file content.

method getDownloadUrl

getDownloadUrl: (path: string) => Promise<string>;

Get an encoded download url given a file path.
Parameter A
promise which resolves with the absolute POSIX file path on the server.
#### Notes The returned URL may include a query parameter.

method getSharedModelFactory

getSharedModelFactory: (path: string) => ISharedFactory | null;

Given a path, get a shared model IFactory from the relevant backend. Returns null if the backend does not provide one.

method listCheckpoints

listCheckpoints: (path: string) => Promise<ICheckpointModel[]>;

List available checkpoints for a file.
Parameter path
The path of the file.
Returns
A promise which resolves with a list of checkpoint models for the file.

method localPath

localPath: (path: string) => string;

Given a path of the form drive:local/portion/of/it.txt get the local part of it.
Parameter path
: the path.
Returns
The local part of the path.

method newUntitled

newUntitled: (options?: ICreateOptions) => Promise<IModel>;

Create a new untitled file or directory in the specified directory path.
Parameter options
: The options used to create the file.
Returns
A promise which resolves with the created file content when the file is created.

method normalize

normalize: (path: string) => string;

Normalize a global path. Reduces '..' and '.' parts, and removes leading slashes from the local part of the path, while retaining the drive name if it exists.
Parameter path
: the path.
Returns
The normalized path.

method rename

rename: (path: string, newPath: string) => Promise<IModel>;

Rename a file or directory.
Parameter path
The original file path.
Parameter newPath
The new file path.
Returns
A promise which resolves with the new file content model when the file is renamed.

method resolvePath

resolvePath: (root: string, path: string) => string;

Resolve a global path, starting from the root path. Behaves like posix-path.resolve, with 3 differences: - will never prepend cwd - if root has a drive name, the result is prefixed with ":" - before adding drive name, leading slashes are removed
Parameter path
: the path.
Returns
The normalized path.

method restoreCheckpoint

restoreCheckpoint: (path: string, checkpointID: string) => Promise<void>;

Restore a file to a known checkpoint state.
Parameter path
The path of the file.
Parameter checkpointID
The id of the checkpoint to restore.
Returns
A promise which resolves when the checkpoint is restored.

method save

save: (path: string, options?: Partial<IModel>) => Promise<IModel>;

Save a file.
Parameter path
The desired file path.
Parameter options
Optional overrides to the model.
Returns
A promise which resolves with the file content model when the file is saved.

interface IModel

interface IModel {}

A contents model.

property chunk

readonly chunk?: number;

The chunk of the file upload.

property content

readonly content: any;

The optional file content.

property created

readonly created: string;

File creation timestamp.

property format

readonly format: FileFormat;

The format of the file content.
#### Notes Only relevant for type: 'file'

property indices

indices?: ReadonlyArray<number> | null;

The indices of the matched characters in the name.

property last_modified

readonly last_modified: string;

Last modified timestamp.

property mimetype

readonly mimetype: string;

Specify the mime-type of file contents.
#### Notes Only non-null when content is present and type is "file".

property name

readonly name: string;

Name of the contents file.
#### Notes Equivalent to the last part of the path field.

property path

readonly path: string;

The full file path.
#### Notes It will *not* start with /, and it will be /-delimited.

property serverPath

readonly serverPath?: string;

The path as returned by the server contents API.
#### Notes Differently to path it does not include IDrive API prefix.

property size

readonly size?: number;

The size of then file in bytes.

property type

readonly type: ContentType;

The type of file.

property writable

readonly writable: boolean;

Whether the requester has permission to edit the file.

interface ISharedFactory

interface ISharedFactory {}

A factory interface for creating ISharedDocument objects.

property collaborative

readonly collaborative?: boolean;

Whether the IDrive supports real-time collaboration or not. Note: If it is not provided, it is false by default.

method createNew

createNew: (options: ISharedFactoryOptions) => ISharedDocument | undefined;

Create a new ISharedDocument instance.
It should return undefined if the factory is not able to create a ISharedDocument.

interface ISharedFactoryOptions

interface ISharedFactoryOptions {}

The options used to instantiate a ISharedDocument

property collaborative

collaborative?: boolean;

Wether the document is collaborative or not.
The default value is true.

property contentType

contentType: ContentType;

The content type of the document.

property format

format: FileFormat;

The format of the document. If null, the document won't be collaborative.

property path

path: string;

The path of the file.

type ContentType

type ContentType = string;

A contents file type. It can be anything but jupyter-server has special treatment for notebook and directory types. Anything else is considered as file type.

type FileFormat

type FileFormat = 'json' | 'text' | 'base64' | null;

A contents file format.

namespace ContentsManager

namespace ContentsManager {}

A namespace for ContentsManager statics.

interface IOptions

interface IOptions {}

The options used to initialize a contents manager.

property defaultDrive

defaultDrive?: Contents.IDrive;

The default drive backend for the contents manager.

property serverSettings

serverSettings?: ServerConnection.ISettings;

The server settings associated with the manager.

namespace Drive

namespace Drive {}

A namespace for Drive statics.

interface IOptions

interface IOptions {}

The options used to initialize a Drive.

property apiEndpoint

apiEndpoint?: string;

A REST endpoint for drive requests. If not given, defaults to the Jupyter REST API given by [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/contents).

property name

name?: string;

The name for the Drive, which is used in file paths to disambiguate it from other drives.

property serverSettings

serverSettings?: ServerConnection.ISettings;

The server settings for the server.

namespace Event

namespace Event {}

A namespace for event API interfaces.

interface IManager

interface IManager extends IDisposable {}

The interface for the event bus front-end.

property serverSettings

readonly serverSettings: ServerConnection.ISettings;

The server settings used to make API requests.

property stream

readonly stream: Event.Stream;

An event stream that emits and yields each new event.

method emit

emit: (event: Event.Request) => Promise<void>;

Post an event request to be emitted by the event bus.

type Emission

type Emission = ReadonlyJSONObject & {
    schema_id: string;
};

The event emission type.

type Request

type Request = {
    data: JSONObject;
    schema_id: string;
    version: string;
};

The event request type.

type Stream

type Stream = IStream<IManager, Emission>;

An event stream with the characteristics of a signal and an async iterator.

namespace EventManager

namespace EventManager {}

A namespace for EventManager statics.

interface IOptions

interface IOptions {}

The instantiation options for an event manager.

property serverSettings

serverSettings?: ServerConnection.ISettings;

The server settings used to make API requests.

namespace Kernel

module 'lib/kernel/kernel.d.ts' {}

Interface of a Kernel connection that is managed by a session.
#### Notes The Kernel object is tied to the lifetime of the Kernel id, which is a unique id for the Kernel session on the server. The Kernel object manages a websocket connection internally, and will auto-restart if the websocket temporarily loses connection. Restarting creates a new Kernel process on the server, but preserves the Kernel id.
The IKernelConnection is notably missing the full IKernel signals. This interface is for situations where a kernel may change, but we want a user to not have to worry about disconnecting and reconnecting signals when a kernel is swapped. The object that maintains an IKernel, but only provides a user with an IKernelConnection should proxy the appropriate IKernel signals for the user with its own signals. The advantage is that when the kernel is changed, the object itself can take care of disconnecting and reconnecting listeners.

interface IAnyMessageArgs

interface IAnyMessageArgs {}

Arguments interface for the anyMessage signal.

property direction

direction: 'send' | 'recv';

The direction of the message.

property msg

msg: Readonly<KernelMessage.IMessage>;

The message that is being signaled.

interface IComm

interface IComm extends IDisposable {}

A client side Comm interface.

property commId

readonly commId: string;

The unique id for the comm channel.

property onClose

onClose: (msg: KernelMessage.ICommCloseMsg) => void | PromiseLike<void>;

Callback for a comm close event.
#### Notes This is called when the comm is closed from either the server or client. If this is called in response to a kernel message and the handler returns a promise, all kernel message processing pauses until the promise is resolved.

property onMsg

onMsg: (msg: KernelMessage.ICommMsgMsg) => void | PromiseLike<void>;

Callback for a comm message received event.
#### Notes If the handler returns a promise, all kernel message processing pauses until the promise is resolved.

property targetName

readonly targetName: string;

The target name for the comm channel.

method close

close: (
    data?: JSONValue,
    metadata?: JSONObject,
    buffers?: (ArrayBuffer | ArrayBufferView)[]
) => IShellFuture;

Close the comm.
Parameter data
The data to send to the server on opening.
Parameter metadata
Additional metadata for the message.
Returns
A future for the generated message.
#### Notes This will send a comm_close message to the kernel, and call the onClose callback if set.
This is a no-op if the comm is already closed.

method open

open: (
    data?: JSONValue,
    metadata?: JSONObject,
    buffers?: (ArrayBuffer | ArrayBufferView)[]
) => IShellFuture;

Open a comm with optional data and metadata.
Parameter data
The data to send to the server on opening.
Parameter metadata
Additional metadata for the message.
Returns
A future for the generated message.
#### Notes This sends a comm_open message to the server.

method send

send: (
    data: JSONValue,
    metadata?: JSONObject,
    buffers?: (ArrayBuffer | ArrayBufferView)[],
    disposeOnDone?: boolean
) => IShellFuture;

Send a comm_msg message to the kernel.
Parameter data
The data to send to the server on opening.
Parameter metadata
Additional metadata for the message.
Parameter buffers
Optional buffer data.
Parameter disposeOnDone
Whether to dispose of the future when done.
Returns
A future for the generated message.
#### Notes This is a no-op if the comm has been closed.

interface IControlFuture

interface IControlFuture<
    REQUEST extends KernelMessage.IControlMessage = KernelMessage.IControlMessage,
    REPLY extends KernelMessage.IControlMessage = KernelMessage.IControlMessage
> extends IFuture<REQUEST, REPLY> {}

interface IFuture

interface IFuture<
    REQUEST extends KernelMessage.IShellControlMessage,
    REPLY extends KernelMessage.IShellControlMessage
> extends IDisposable {}

A Future interface for responses from the kernel.
When a message is sent to a kernel, a Future is created to handle any responses that may come from the kernel.

property done

readonly done: Promise<REPLY>;

A promise that resolves when the future is done.
#### Notes The future is done when there are no more responses expected from the kernel.
The done promise resolves to the reply message.

property msg

readonly msg: REQUEST;

The original outgoing message.

property onIOPub

onIOPub: (msg: KernelMessage.IIOPubMessage) => void | PromiseLike<void>;

The iopub handler for the kernel future.
#### Notes If the handler returns a promise, all kernel message processing pauses until the promise is resolved.

property onReply

onReply: (msg: REPLY) => void | PromiseLike<void>;

The reply handler for the kernel future.
#### Notes If the handler returns a promise, all kernel message processing pauses until the promise is resolved. If there is a reply message, the future done promise also resolves to the reply message after this handler has been called.

property onStdin

onStdin: (msg: KernelMessage.IStdinMessage) => void | PromiseLike<void>;

The stdin handler for the kernel future.
#### Notes If the handler returns a promise, all kernel message processing pauses until the promise is resolved.

method registerMessageHook

registerMessageHook: (
    hook: (msg: KernelMessage.IIOPubMessage) => boolean | PromiseLike<boolean>
) => void;

Register hook for IOPub messages.
Parameter hook
The callback invoked for an IOPub message.
#### Notes The IOPub hook system allows you to preempt the handlers for IOPub messages handled by the future.
The most recently registered hook is run first. A hook can return a boolean or a promise to a boolean, in which case all kernel message processing pauses until the promise is fulfilled. If a hook return value resolves to false, any later hooks will not run and the function will return a promise resolving to false. If a hook throws an error, the error is logged to the console and the next hook is run. If a hook is registered during the hook processing, it will not run until the next message. If a hook is removed during the hook processing, it will be deactivated immediately.

method removeMessageHook

removeMessageHook: (
    hook: (msg: KernelMessage.IIOPubMessage) => boolean | PromiseLike<boolean>
) => void;

Remove a hook for IOPub messages.
Parameter hook
The hook to remove.
#### Notes If a hook is removed during the hook processing, it will be deactivated immediately.

method sendInputReply

sendInputReply: (
    content: KernelMessage.IInputReplyMsg['content'],
    parent_header: KernelMessage.IInputReplyMsg['parent_header']
) => void;

Send an input_reply message.

interface IKernelConnection

interface IKernelConnection extends IObservableDisposable {}

Interface of a Kernel connection that is managed by a session.
#### Notes The Kernel object is tied to the lifetime of the Kernel id, which is a unique id for the Kernel session on the server. The Kernel object manages a websocket connection internally, and will auto-restart if the websocket temporarily loses connection. Restarting creates a new Kernel process on the server, but preserves the Kernel id.
The IKernelConnection is notably missing the full IKernel signals. This interface is for situations where a kernel may change, but we want a user to not have to worry about disconnecting and reconnecting signals when a kernel is swapped. The object that maintains an IKernel, but only provides a user with an IKernelConnection should proxy the appropriate IKernel signals for the user with its own signals. The advantage is that when the kernel is changed, the object itself can take care of disconnecting and reconnecting listeners.

property anyMessage

anyMessage: ISignal<this, IAnyMessageArgs>;

A signal emitted when any kernel message is sent or received.
#### Notes This signal is emitted before any message handling has happened. The message should be treated as read-only.

property clientId

readonly clientId: string;

The client unique id.
#### Notes This should be unique for a particular kernel connection object.

property connectionStatus

readonly connectionStatus: ConnectionStatus;

The current connection status of the kernel.

property connectionStatusChanged

connectionStatusChanged: ISignal<this, ConnectionStatus>;

A signal emitted when the kernel connection status changes.

property handleComms

handleComms: boolean;

Whether the kernel connection handles comm messages.
#### Notes The comm message protocol currently has implicit assumptions that only one kernel connection is handling comm messages. This option allows a kernel connection to opt out of handling comms.
See https://github.com/jupyter/jupyter_client/issues/263

property hasPendingInput

hasPendingInput: boolean;

Whether the kernel connection has pending input.
#### Notes This is a guard to avoid deadlock is the user asks input as second time before submitting his first input

property id

readonly id: string;

The id of the server-side kernel.

property info

readonly info: Promise<KernelMessage.IInfoReply>;

The kernel info
#### Notes This promise only resolves at startup, and is not refreshed on every restart.

property iopubMessage

iopubMessage: ISignal<this, KernelMessage.IIOPubMessage>;

A signal emitted after an iopub kernel message is handled.

property model

readonly model: IModel;

The kernel model, for convenience.

property name

readonly name: string;

The name of the server-side kernel.

property pendingInput

pendingInput: ISignal<this, boolean>;

A signal emitted when a kernel has pending inputs from the user.

property serverSettings

readonly serverSettings: ServerConnection.ISettings;

The server settings for the kernel.

property spec

readonly spec: Promise<KernelSpec.ISpecModel | undefined>;

Get the kernel spec.
Returns
A promise that resolves with the kernel spec for this kernel.
#### Notes This may make a server request to retrieve the spec.

property status

readonly status: KernelMessage.Status;

The current status of the kernel.

property statusChanged

statusChanged: ISignal<this, KernelMessage.Status>;

A signal emitted when the kernel status changes.

property unhandledMessage

unhandledMessage: ISignal<this, KernelMessage.IMessage>;

A signal emitted for unhandled non-iopub kernel messages that claimed to be responses for messages we sent using this kernel object.

property username

readonly username: string;

The client username.

method clone

clone: (
    options?: Pick<
        IKernelConnection.IOptions,
        'clientId' | 'username' | 'handleComms'
    >
) => IKernelConnection;

Clone the current kernel with a new clientId.

method createComm

createComm: (targetName: string, commId?: string) => IComm;

Create a new comm.
Parameter targetName
The name of the comm target.
Parameter id
The comm id.
Returns
A comm instance.

method hasComm

hasComm: (commId: string) => boolean;

Check if a comm exists.

method interrupt

interrupt: () => Promise<void>;

Interrupt a kernel.
Returns
A promise that resolves when the kernel has interrupted.
#### Notes Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/kernels).
The promise is fulfilled on a valid response and rejected otherwise.
It is assumed that the API call does not mutate the kernel id or name.
The promise will be rejected if the kernel status is 'dead' or if the request fails or the response is invalid.

method reconnect

reconnect: () => Promise<void>;

Reconnect to a disconnected kernel.
Returns
A promise that resolves when the kernel has reconnected.
#### Notes This just refreshes the connection to an existing kernel, and does not perform an HTTP request to the server or restart the kernel.

method registerCommTarget

registerCommTarget: (
    targetName: string,
    callback: (
        comm: IComm,
        msg: KernelMessage.ICommOpenMsg
    ) => void | PromiseLike<void>
) => void;

Register a comm target handler.
Parameter targetName
The name of the comm target.
Parameter callback
The callback invoked for a comm open message.
#### Notes Only one comm target can be registered to a target name at a time, an existing callback for the same target name will be overridden. A registered comm target handler will take precedence over a comm which specifies a target_module.
If the callback returns a promise, kernel message processing will pause until the returned promise is fulfilled.

method registerMessageHook

registerMessageHook: (
    msgId: string,
    hook: (msg: KernelMessage.IIOPubMessage) => boolean | PromiseLike<boolean>
) => void;

Register an IOPub message hook.
Parameter msg_id
The parent_header message id in messages the hook should intercept.
Parameter hook
The callback invoked for the message.
#### Notes The IOPub hook system allows you to preempt the handlers for IOPub messages with a given parent_header message id. The most recently registered hook is run first. If a hook return value resolves to false, any later hooks and the future's onIOPub handler will not run. If a hook throws an error, the error is logged to the console and the next hook is run. If a hook is registered during the hook processing, it will not run until the next message. If a hook is disposed during the hook processing, it will be deactivated immediately.
See also [[IFuture.registerMessageHook]].

method removeCommTarget

removeCommTarget: (
    targetName: string,
    callback: (
        comm: IComm,
        msg: KernelMessage.ICommOpenMsg
    ) => void | PromiseLike<void>
) => void;

Remove a comm target handler.
Parameter targetName
The name of the comm target to remove.
Parameter callback
The callback to remove.
#### Notes The comm target is only removed if it matches the callback argument.

method removeInputGuard

removeInputGuard: () => void;

Remove the input guard, if any.

method removeMessageHook

removeMessageHook: (
    msgId: string,
    hook: (msg: KernelMessage.IIOPubMessage) => boolean | PromiseLike<boolean>
) => void;

Remove an IOPub message hook.
Parameter msg_id
The parent_header message id the hook intercepted.
Parameter hook
The callback invoked for the message.

method requestCommInfo

requestCommInfo: (
    content: KernelMessage.ICommInfoRequestMsg['content']
) => Promise<KernelMessage.ICommInfoReplyMsg>;

Send a comm_info_request message.
Parameter content
The content of the request.
Returns
A promise that resolves with the response message.
#### Notes See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#comm_info).
Fulfills with the comm_info_reply content when the shell reply is received and validated.

method requestComplete

requestComplete: (
    content: KernelMessage.ICompleteRequestMsg['content']
) => Promise<KernelMessage.ICompleteReplyMsg>;

Send a complete_request message.
Parameter content
The content of the request.
Returns
A promise that resolves with the response message.
#### Notes See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#completion).
Fulfills with the complete_reply content when the shell reply is received and validated.

method requestDebug

requestDebug: (
    content: KernelMessage.IDebugRequestMsg['content'],
    disposeOnDone?: boolean
) => IControlFuture<
    KernelMessage.IDebugRequestMsg,
    KernelMessage.IDebugReplyMsg
>;

Send an experimental debug_request message.
Parameter content
The content of the request.
Parameter disposeOnDone
Whether to dispose of the future when done.
Returns
A kernel future.
#### Notes Debug messages are experimental messages that are not in the official kernel message specification. As such, this function is *NOT* considered part of the public API, and may change without notice.

method requestExecute

requestExecute: (
    content: KernelMessage.IExecuteRequestMsg['content'],
    disposeOnDone?: boolean,
    metadata?: JSONObject
) => IShellFuture<
    KernelMessage.IExecuteRequestMsg,
    KernelMessage.IExecuteReplyMsg
>;

Send an execute_request message.
Parameter content
The content of the request.
Parameter disposeOnDone
Whether to dispose of the future when done.
Returns
A kernel future.
#### Notes See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#execute).
This method returns a kernel future, rather than a promise, since execution may have many response messages (for example, many iopub display messages).
Future onReply is called with the execute_reply content when the shell reply is received and validated.
**See also:** [[IExecuteReply]]

method requestHistory

requestHistory: (
    content: KernelMessage.IHistoryRequestMsg['content']
) => Promise<KernelMessage.IHistoryReplyMsg>;

Send a history_request message.
Parameter content
The content of the request.
Returns
A promise that resolves with the response message.
#### Notes See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#history).
Fulfills with the history_reply content when the shell reply is received and validated.

method requestInspect

requestInspect: (
    content: KernelMessage.IInspectRequestMsg['content']
) => Promise<KernelMessage.IInspectReplyMsg>;

Send an inspect_request message.
Parameter content
The content of the request.
Returns
A promise that resolves with the response message.
#### Notes See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#introspection).
Fulfills with the inspect_reply content when the shell reply is received and validated.

method requestIsComplete

requestIsComplete: (
    content: KernelMessage.IIsCompleteRequestMsg['content']
) => Promise<KernelMessage.IIsCompleteReplyMsg>;

Send an is_complete_request message.
Parameter content
The content of the request.
Returns
A promise that resolves with the response message.
#### Notes See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#code-completeness).
Fulfills with the is_complete_response content when the shell reply is received and validated.

method requestKernelInfo

requestKernelInfo: () => Promise<KernelMessage.IInfoReplyMsg | undefined>;

Send a kernel_info_request message.
Parameter content
The content of the request.
Returns
A promise that resolves with the response message.
#### Notes See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#kernel-info).
Fulfills with the kernel_info_response content when the shell reply is received and validated.

method restart

restart: () => Promise<void>;

Restart a kernel.
Returns
A promise that resolves when the kernel has restarted.
#### Notes Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/kernels) and validates the response model.
Any existing Future or Comm objects are cleared.
It is assumed that the API call does not mutate the kernel id or name.
The promise will be rejected if the kernel status is 'dead' or if the request fails or the response is invalid.

method sendControlMessage

sendControlMessage: <T extends KernelMessage.ControlMessageType>(
    msg: KernelMessage.IControlMessage<T>,
    expectReply?: boolean,
    disposeOnDone?: boolean
) => IControlFuture<KernelMessage.IControlMessage<T>>;

method sendInputReply

sendInputReply: (
    content: KernelMessage.IInputReplyMsg['content'],
    parent_header: KernelMessage.IInputReplyMsg['parent_header']
) => void;

Send an input_reply message.
Parameter content
The content of the reply.
#### Notes See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#messages-on-the-stdin-router-dealer-sockets).

method sendShellMessage

sendShellMessage: <T extends KernelMessage.ShellMessageType>(
    msg: KernelMessage.IShellMessage<T>,
    expectReply?: boolean,
    disposeOnDone?: boolean
) => IShellFuture<KernelMessage.IShellMessage<T>>;

Send a shell message to the kernel.
Parameter msg
The fully-formed shell message to send.
Parameter expectReply
Whether to expect a shell reply message.
Parameter disposeOnDone
Whether to dispose of the future when done.
#### Notes Send a message to the kernel's shell channel, yielding a future object for accepting replies.
If expectReply is given and true, the future is done when both a shell reply and an idle status message are received with the appropriate parent header, in which case the .done promise resolves to the reply. If expectReply is not given or is false, the future is done when an idle status message with the appropriate parent header is received, in which case the .done promise resolves to undefined.
If disposeOnDone is given and false, the future will not be disposed of when the future is done, instead relying on the caller to dispose of it. This allows for the handling of out-of-order output from ill-behaved kernels.
All replies are validated as valid kernel messages.
If the kernel status is 'dead', this will throw an error.

method shutdown

shutdown: () => Promise<void>;

Shutdown a kernel.
Returns
A promise that resolves when the kernel has shut down.
#### Notes Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/kernels).
On a valid response, closes the websocket, disposes of the kernel object, and fulfills the promise.
The promise will be rejected if the kernel status is 'dead', the request fails, or the response is invalid.

interface IManager

interface IManager extends IBaseManager {}

Object which manages kernel instances for a given base url.
#### Notes The manager is responsible for maintaining the state of running kernels through polling the server. Use a manager if you want to be notified of changes to kernels.

property connectionFailure

connectionFailure: ISignal<IManager, ServerConnection.NetworkError>;

A signal emitted when there is a server API connection failure.

property isReady

readonly isReady: boolean;

Whether the manager is ready.

property ready

readonly ready: Promise<void>;

A promise that resolves when the manager is initially ready.

property runningChanged

runningChanged: ISignal<IManager, IModel[]>;

A signal emitted when the running kernels change.

method connectTo

connectTo: (options: IKernelConnection.IOptions) => IKernelConnection;

Connect to an existing kernel.
Parameter model
The model of the target kernel.
Returns
A promise that resolves with the new kernel instance.

method findById

findById: (id: string) => Promise<IModel | undefined>;

Find a kernel by id.
Parameter id
The id of the target kernel.
Returns
A promise that resolves with the kernel's model, or undefined if not found.

method refreshRunning

refreshRunning: () => Promise<void>;

Force a refresh of the running kernels.
Returns
A promise that resolves when the models are refreshed.
#### Notes This is intended to be called only in response to a user action, since the manager maintains its internal state.

method running

running: () => IterableIterator<IModel>;

Create an iterator over the known running kernels.
Returns
A new iterator over the running kernels.

method shutdown

shutdown: (id: string) => Promise<void>;

Shut down a kernel by id.
Parameter id
The id of the target kernel.
Returns
A promise that resolves when the operation is complete.

method shutdownAll

shutdownAll: () => Promise<void>;

Shut down all kernels.
Returns
A promise that resolves when all of the kernels are shut down.

method startNew

startNew: (
    createOptions?: IKernelOptions,
    connectOptions?: Omit<IKernelConnection.IOptions, 'model' | 'serverSettings'>
) => Promise<IKernelConnection>;

Start a new kernel.
Parameter createOptions
The kernel creation options
Parameter connectOptions
The kernel connection options
Returns
A promise that resolves with the kernel connection.
#### Notes The manager serverSettings will be always be used.

interface IModel

interface IModel {}

The kernel model provided by the server.
#### Notes See the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/kernels).

property connections

readonly connections?: number;

The number of active connections to the kernel.

property execution_state

readonly execution_state?: string;

The kernel execution state.

property id

readonly id: string;

Unique identifier of the kernel on the server.

property last_activity

readonly last_activity?: string;

The timestamp of the last activity on the kernel.

property name

readonly name: string;

The name of the kernel.

property reason

readonly reason?: string;

The reason the kernel died, if applicable.

property traceback

readonly traceback?: string;

The traceback for a dead kernel, if applicable.

interface IShellFuture

interface IShellFuture<
    REQUEST extends KernelMessage.IShellMessage = KernelMessage.IShellMessage,
    REPLY extends KernelMessage.IShellMessage = KernelMessage.IShellMessage
> extends IFuture<REQUEST, REPLY> {}

type ConnectionStatus

type ConnectionStatus = 'connected' | 'connecting' | 'disconnected';

The valid kernel connection states.
#### Notes The status states are: * connected: The kernel connection is live. * connecting: The kernel connection is not live, but we are attempting to reconnect to the kernel. * disconnected: The kernel connection is permanently down, we will not try to reconnect.
When a kernel connection is connected, the kernel status should be valid. When a kernel connection is either connecting or disconnected, the kernel status will be unknown unless the kernel status was dead, in which case it stays dead.

type IKernelOptions

type IKernelOptions = Partial<Pick<IModel, 'name'>>;

The options object used to initialize a kernel.

type Status

type Status =
    | 'unknown'
    | 'starting'
    | 'idle'
    | 'busy'
    | 'terminating'
    | 'restarting'
    | 'autorestarting'
    | 'dead';

The valid Kernel status states.
#### Notes The status states are: * unknown: The kernel status is unknown, often because the connection is disconnected or connecting. This state is determined by the kernel connection status. * autorestarting: The kernel is restarting, initiated by the server. This state is set by the services library, not explicitly sent from the kernel. * starting: The kernel is starting * idle: The kernel has finished processing messages. * busy: The kernel is currently processing messages. * restarting: The kernel is restarting. This state is sent by the Jupyter server. * dead: The kernel is dead and will not be restarted. This state is set by the Jupyter server and is a final state.

namespace Kernel.IKernelConnection

namespace Kernel.IKernelConnection {}

The namespace for IKernelConnection statics.

interface IOptions

interface IOptions {}

The options object used to initialize a kernel.

property clientId

clientId?: string;

The unique identifier for the kernel client.

property handleComms

handleComms?: boolean;

Whether the kernel connection should handle comm messages
#### Notes The comm message protocol currently has implicit assumptions that only one kernel connection is handling comm messages. This option allows a kernel connection to opt out of handling comms.
See https://github.com/jupyter/jupyter_client/issues/263

property model

model: IModel;

The kernel model.

property serverSettings

serverSettings?: ServerConnection.ISettings;

The server settings for the kernel.

property username

username?: string;

The username of the kernel client.

namespace KernelAPI

module 'lib/kernel/restapi.d.ts' {}

The kernel model provided by the server.
#### Notes See the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/kernels).

variable KERNEL_SERVICE_URL

const KERNEL_SERVICE_URL: string;

The url for the kernel service.

function getKernelModel

getKernelModel: (
    id: string,
    settings?: ServerConnection.ISettings
) => Promise<IModel | undefined>;

Get a full kernel model from the server by kernel id string.
#### Notes Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/kernels) and validates the response model.
The promise is fulfilled on a valid response and rejected otherwise.

function interruptKernel

interruptKernel: (
    id: string,
    settings?: ServerConnection.ISettings
) => Promise<void>;

Interrupt a kernel.
#### Notes Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/kernels) and validates the response model.
The promise is fulfilled on a valid response and rejected otherwise.

function listRunning

listRunning: (settings?: ServerConnection.ISettings) => Promise<IModel[]>;

Fetch the running kernels.
Parameter settings
The optional server settings.
Returns
A promise that resolves with the list of running kernels.
#### Notes Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/kernels) and validates the response model.
The promise is fulfilled on a valid response and rejected otherwise.

function restartKernel

restartKernel: (
    id: string,
    settings?: ServerConnection.ISettings
) => Promise<void>;

Restart a kernel.
#### Notes Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/kernels) and validates the response model.
The promise is fulfilled on a valid response (and thus after a restart) and rejected otherwise.

function shutdownKernel

shutdownKernel: (
    id: string,
    settings?: ServerConnection.ISettings
) => Promise<void>;

Shut down a kernel.
Parameter id
The id of the running kernel.
Parameter settings
The server settings for the request.
Returns
A promise that resolves when the kernel is shut down.
#### Notes Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/kernels) and validates the response model.
The promise is fulfilled on a valid response and rejected otherwise.

function startNew

startNew: (
    options?: IKernelOptions,
    settings?: ServerConnection.ISettings
) => Promise<IModel>;

Start a new kernel.
Parameter options
The options used to create the kernel.
Returns
A promise that resolves with a kernel connection object.
#### Notes Uses the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/kernels) and validates the response model.
The promise is fulfilled on a valid response and rejected otherwise.

interface IModel

interface IModel {}

The kernel model provided by the server.
#### Notes See the [Jupyter Notebook API](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter-server/jupyter_server/main/jupyter_server/services/api/api.yaml#!/kernels).

property connections

readonly connections?: number;

The number of active connections to the kernel.

property execution_state

readonly execution_state?: string;

The kernel execution state.

property id

readonly id: string;

Unique identifier of the kernel on the server.

property last_activity

readonly last_activity?: string;

The timestamp of the last activity on the kernel.

property name

readonly name: string;

The name of the kernel.

property reason

readonly reason?: string;

The reason the kernel died, if applicable.

property traceback

readonly traceback?: string;

The traceback for a dead kernel, if applicable.

type IKernelOptions

type IKernelOptions = Partial<Pick<IModel, 'name'>>;

The options object used to initialize a kernel.

namespace KernelManager

namespace KernelManager {}

The namespace for KernelManager class statics.

class NoopManager

class NoopManager extends KernelManager {}

A no-op kernel manager to be used when starting kernels.

property isActive

readonly isActive: boolean;

Whether the manager is active.

property parentReady

readonly parentReady: Promise<void>;

Used for testing.

property ready

readonly ready: Promise<void>;

A promise that fulfills when the manager is ready (never).

method connectTo

connectTo: (
    options: Omit<Kernel.IKernelConnection.IOptions, 'serverSettings'>
) => Kernel.IKernelConnection;

Connect to an existing kernel - throws an error since it is not supported.

method requestRunning

protected requestRunning: () => Promise<void>;

Execute a request to the server to poll running kernels and update state.

method shutdown

shutdown: (id: string) => Promise<void>;

Shut down a kernel by id - throws an error since it is not supported.

method startNew

startNew: (
    createOptions?: IKernelOptions,
    connectOptions?: Omit<
        Kernel.IKernelConnection.IOptions,
        'model' | 'serverSettings'
    >
) => Promise<Kernel.IKernelConnection>;

Start a new kernel - throws an error since it is not supported.

interface IOptions

interface IOptions extends BaseManager.IOptions {}

The options used to initialize a KernelManager.

property standby

standby?: Poll.Standby | (() => boolean | Poll.Standby);

When the manager stops polling the API. Defaults to when-hidden.

namespace KernelMessage

module 'lib/kernel/messages.d.ts' {}

#### Notes Debug messages are experimental messages that are not in the official kernel message specification. As such, this function is *NOT* considered part of the public API, and may change without notice.

function createMessage

createMessage: {
    <T extends IClearOutputMsg>(options: IOptions<T>): T;
    <T extends ICommCloseMsg<'iopub'>>(options: IOptions<T>): T;
    <T extends ICommCloseMsg<'shell'>>(options: IOptions<T>): T;
    <T extends ICommInfoReplyMsg>(options: IOptions<T>): T;
    <T extends ICommInfoRequestMsg>(options: IOptions<T>): T;
    <T extends ICommMsgMsg<'iopub'>>(options: IOptions<T>): T;
    <T extends ICommMsgMsg<'shell'>>(options: IOptions<T>): T;
    <T extends ICommOpenMsg<'iopub'>>(options: IOptions<T>): T;
    <T extends ICommOpenMsg<'shell'>>(options: IOptions<T>): T;
    <T extends ICompleteReplyMsg>(options: IOptions<T>): T;
    <T extends ICompleteRequestMsg>(options: IOptions<T>): T;
    <T extends IDisplayDataMsg>(options: IOptions<T>): T;
    <T extends IErrorMsg>(options: IOptions<T>): T;
    <T extends IExecuteInputMsg>(options: IOptions<T>): T;
    <T extends IExecuteReplyMsg>(options: IOptions<T>): T;
    <T extends IExecuteRequestMsg>(options: IOptions<T>): T;
    <T extends IExecuteResultMsg>(options: IOptions<T>): T;
    <T extends IHistoryReplyMsg>(options: IOptions<T>): T;
    <T extends IHistoryRequestMsg>(options: IOptions<T>): T;
    <T extends IInfoReplyMsg>(options: IOptions<T>): T;
    <T extends IInfoRequestMsg>(options: IOptions<T>): T;
    <T extends IInputReplyMsg>(options: IOptions<T>): T;
    <T extends IInputRequestMsg>(options: IOptions<T>): T;
    <T extends IInspectReplyMsg>(options: IOptions<T>): T;
    <T extends IInspectRequestMsg>(options: IOptions<T>): T;
    <T extends IIsCompleteReplyMsg>(options: IOptions<T>): T;
    <T extends IIsCompleteRequestMsg>(options: IOptions<T>): T;
    <T extends IStatusMsg>(options: IOptions<T>): T;
    <T extends IStreamMsg>(options: IOptions<T>): T;
    <T extends IUpdateDisplayDataMsg>(options: IOptions<T>): T;
    <T extends IDebugRequestMsg>(options: IOptions<T>): T;
    <T extends IDebugReplyMsg>(options: IOptions<T>): T;
    <T extends IDebugEventMsg>(options: IOptions<T>): T;
};

#### Notes Debug messages are experimental messages that are not in the official kernel message specification. As such, this function is *NOT* considered part of the public API, and may change without notice.

function isClearOutputMsg

isClearOutputMsg: (msg: IMessage) => msg is IClearOutputMsg;

Test whether a kernel message is a 'clear_output' message.

function isCommCloseMsg

isCommCloseMsg: (msg: IMessage) => msg is ICommCloseMsg<'iopub' | 'shell'>;

Test whether a kernel message is a 'comm_close' message.

function isCommMsgMsg

isCommMsgMsg: (msg: IMessage) => msg is ICommMsgMsg<'iopub' | 'shell'>;

Test whether a kernel message is a 'comm_msg' message.

function isCommOpenMsg

isCommOpenMsg: (msg: IMessage) => msg is ICommOpenMsg<'iopub' | 'shell'>;

Test whether a kernel message is a 'comm_open' message.

function isDebugEventMsg

isDebugEventMsg: (msg: IMessage) => msg is IDebugEventMsg;

Test whether a kernel message is an experimental 'debug_event' message.
#### Notes Debug messages are experimental messages that are not in the official kernel message specification. As such, this is *NOT* considered part of the public API, and may change without notice.

function isDebugReplyMsg

isDebugReplyMsg: (msg: IMessage) => msg is IDebugReplyMsg;

Test whether a kernel message is an experimental 'debug_reply' message.
#### Notes Debug messages are experimental messages that are not in the official kernel message specification. As such, this is *NOT* considered part of the public API, and may change without notice.

function isDebugRequestMsg

isDebugRequestMsg: (msg: IMessage) => msg is IDebugRequestMsg;

Test whether a kernel message is an experimental 'debug_request' message.
#### Notes Debug messages are experimental messages that are not in the official kernel message specification. As such, this is *NOT* considered part of the public API, and may change without notice.

function isDisplayDataMsg

isDisplayDataMsg: (msg: IMessage) => msg is IDisplayDataMsg;

Test whether a kernel message is an 'display_data' message.

function isErrorMsg

isErrorMsg: (msg: IMessage) => msg is IErrorMsg;

Test whether a kernel message is an 'error' message.

function isExecuteInputMsg

isExecuteInputMsg: (msg: IMessage) => msg is IExecuteInputMsg;

Test whether a kernel message is an 'execute_input' message.

function isExecuteReplyMsg

isExecuteReplyMsg: (msg: IMessage) => msg is IExecuteReplyMsg;

Test whether a kernel message is an 'execute_reply' message.

function isExecuteResultMsg

isExecuteResultMsg: (msg: IMessage) => msg is IExecuteResultMsg;

Test whether a kernel message is an 'execute_result' message.

function isInfoRequestMsg

isInfoRequestMsg: (msg: IMessage) => msg is IInfoRequestMsg;

Test whether a kernel message is a 'kernel_info_request' message.

function isInputReplyMsg

isInputReplyMsg: (msg: IMessage) => msg is IInputReplyMsg;

Test whether a kernel message is an 'input_reply' message.

function isInputRequestMsg

isInputRequestMsg: (msg: IMessage) => msg is IInputRequestMsg;

Test whether a kernel message is an 'input_request' message.

function isStatusMsg

isStatusMsg: (msg: IMessage) => msg is IStatusMsg;

Test whether a kernel message is a 'status' message.

function isStreamMsg

isStreamMsg: (msg: IMessage) => msg is IStreamMsg;

Test whether a kernel message is a 'stream' message.

function isUpdateDisplayDataMsg

isUpdateDisplayDataMsg: (msg: IMessage) => msg is IUpdateDisplayDataMsg;

Test whether a kernel message is an 'update_display_data' message.

interface IClearOutputMsg

interface IClearOutputMsg extends IIOPubMessage<'clear_output'> {}

A 'clear_output' message on the 'iopub' channel.
See [Clear output](https://jupyter-client.readthedocs.io/en/latest/messaging.html#clear-output).

property content

content: {
    wait: boolean;
};

interface ICommCloseMsg

interface ICommCloseMsg<T extends 'iopub' | 'shell' = 'iopub' | 'shell'>
    extends IMessage<'comm_close'> {}

A 'comm_close' message on the 'iopub' channel.
See [Comm close](https://jupyter-client.readthedocs.io/en/latest/messaging.html#opening-a-comm).

property channel

channel: T;

property content

content: {
    comm_id: string;
    data: JSONObject;
};

interface ICommInfoReply

interface ICommInfoReply extends IReplyOkContent {}

A 'comm_info_reply' message content.
See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#comm-info).
**See also:** [[ICommInfoRequest]], [[IKernel.commInfo]]

property comms

comms: {
    [commId: string]: {
        target_name: string;
    };
};

Mapping of comm ids to target names.

interface ICommInfoReplyMsg

interface ICommInfoReplyMsg extends IShellMessage<'comm_info_reply'> {}

A 'comm_info_reply' message on the 'shell' channel.
See [Messaging in Jupyter](https://jupyter-client.readthedocs.io/en/latest/messaging.html#comm-info).
**See also:** [[ICommInfoRequestMsg]], [[IKernel.commInfo]]

property content

content: ReplyContent<ICommInfoReply>;

property parent_header

parent_header: IHeader<'comm_info_request'>;

interface ICommInfoRequestMsg

interface ICommInfoRequestMsg extends IShellMessage<'comm_info_request'> {}

A 'comm_info_re

@jupyterlab/services

Install

Overview

Index

Classes

Interfaces

Namespaces

Classes

class BaseManager

constructor

property connectionFailure

property disposed

property isActive

property isDisposed

property isReady

property ready

property serverSettings

method dispose

class ConfigWithDefaults

constructor

method get

method set

class ContentsManager

constructor

Parameter options

property fileChanged

property isDisposed

property serverSettings

method addDrive

method copy

Parameter path

Parameter toDir

Returns

method createCheckpoint

Parameter path

Returns

method delete

Parameter path

Returns

method deleteCheckpoint

Parameter path

Parameter checkpointID

Returns

method dispose

method driveName

Parameter path

Returns

method get

Parameter path

Parameter options

Returns

method getDownloadUrl

Parameter path

method getSharedModelFactory

method listCheckpoints

Parameter path

Returns

method localPath

Parameter path

Returns

method newUntitled

Parameter options

Returns

method normalize

Parameter path

Returns

method rename

Parameter path

Parameter newPath

Returns

method resolvePath

Parameter path

Returns

method restoreCheckpoint

Parameter path

Parameter checkpointID

Returns

method save

Parameter path

Parameter options