@jupyterlab/services
- Version 7.3.5
- Published
- 1.22 MB
- 11 dependencies
- BSD-3-Clause license
Install
npm i @jupyterlab/services
yarn add @jupyterlab/services
pnpm add @jupyterlab/services
Overview
services
Index
Classes
KernelConnection
- anyMessage
- clientId
- clone()
- connectionStatus
- connectionStatusChanged
- createComm()
- dispose()
- disposed
- handleComms
- handleShutdown()
- hasComm()
- hasPendingInput
- id
- info
- interrupt()
- iopubMessage
- isDisposed
- model
- name
- pendingInput
- reconnect()
- registerCommTarget()
- registerMessageHook()
- removeCommTarget()
- removeInputGuard()
- removeMessageHook()
- requestCommInfo()
- requestComplete()
- requestDebug()
- requestExecute()
- requestHistory()
- requestInspect()
- requestIsComplete()
- requestKernelInfo()
- restart()
- sendControlMessage()
- sendInputReply()
- sendShellMessage()
- serverSettings
- shutdown()
- spec
- status
- statusChanged
- unhandledMessage
- username
Interfaces
Namespaces
KernelMessage
- Channel
- ControlMessageType
- createMessage()
- IClearOutputMsg
- ICommCloseMsg
- ICommInfoReply
- ICommInfoReplyMsg
- ICommInfoRequestMsg
- ICommMsgMsg
- ICommOpenMsg
- ICompleteReplyMsg
- ICompleteRequestMsg
- IControlMessage
- IDebugEventMsg
- IDebugReplyMsg
- IDebugRequestMsg
- IDisplayDataMsg
- IErrorMsg
- IExecuteCount
- IExecuteInputMsg
- IExecuteReply
- IExecuteReplyMsg
- IExecuteRequestMsg
- IExecuteResultMsg
- IHeader
- IHistoryReply
- IHistoryReplyMsg
- IHistoryRequestMsg
- IHistoryRequestRange
- IHistoryRequestSearch
- IHistoryRequestTail
- IInfoReply
- IInfoReplyMsg
- IInfoRequestMsg
- IInputReply
- IInputReplyMsg
- IInputRequestMsg
- IInspectReply
- IInspectReplyMsg
- IInspectRequestMsg
- IIOPubMessage
- IIsCompleteReplyIncomplete
- IIsCompleteReplyMsg
- IIsCompleteReplyOther
- IIsCompleteRequestMsg
- ILanguageInfo
- IMessage
- IOptions
- IOPubMessageType
- IReplyAbortContent
- IReplyErrorContent
- IReplyOkContent
- isClearOutputMsg()
- isCommCloseMsg()
- isCommMsgMsg()
- isCommOpenMsg()
- isDebugEventMsg()
- isDebugReplyMsg()
- isDebugRequestMsg()
- isDisplayDataMsg()
- isErrorMsg()
- isExecuteInputMsg()
- isExecuteReplyMsg()
- isExecuteResultMsg()
- IShellControlMessage
- IShellMessage
- isInfoRequestMsg()
- isInputReplyMsg()
- isInputRequestMsg()
- isStatusMsg()
- isStreamMsg()
- IStatusMsg
- IStdinMessage
- IStreamMsg
- isUpdateDisplayDataMsg()
- IUpdateDisplayDataMsg
- Message
- MessageType
- ShellMessageType
- Status
- StdinMessageType
- supportedKernelWebSocketProtocols
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 Server 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 Server 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 Server 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 Server 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 Server 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 Server 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 Server 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 Server 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 Server 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 Server 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 Server 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 Server 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 theexecute_reply
content when the shell reply is received and validated. The future will resolve when this message is received and theidle
iopub status is received. The future will also be disposed at this point unlessdisposeOnDone
is specified andfalse
, 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 Server 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 andtrue
, the future is disposed when both a control reply and an idle status message are received. IfexpectReply
is not given or isfalse
, the future is resolved when an idle status message is received. IfdisposeOnDone
is not given or istrue
, the Future is disposed at this point. IfdisposeOnDone
is given andfalse
, 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 andtrue
, the future is disposed when both a shell reply and an idle status message are received. IfexpectReply
is not given or isfalse
, the future is resolved when an idle status message is received. IfdisposeOnDone
is not given or istrue
, the Future is disposed at this point. IfdisposeOnDone
is given andfalse
, 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 Server 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 runningCount
readonly runningCount: number;
The number of running kernels.
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.
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.
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.
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 hash
hash?: boolean;
Whether to include a hash in the response.
The default is
false
.
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 hash
readonly hash?: string;
The hexdigest hash string of content, if requested (otherwise null). It cannot be null if hash_algorithm is defined.
property hash_algorithm
readonly hash_algorithm?: string;
The algorithm used to compute hash value. It cannot be null if hash is defined.
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
whencontent
is present andtype
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 aISharedDocument
.
interface ISharedFactoryOptions
interface ISharedFactoryOptions {}
The options used to instantiate a ISharedDocument
property collaborative
collaborative?: boolean;
Whether 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 fornotebook
anddirectory
types. Anything else is considered asfile
type.
type FileFormat
type FileFormat = 'json' | 'text' | 'base64' | null;
A contents file format. Always
json
fornotebook
anddirectory
types. It should be set to eithertext
orbase64
forfile
type. See the [jupyter server data model for filesystem entities](https://jupyter-server.readthedocs.io/en/latest/developers/contents.html#filesystem-entities) for more details.
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 Server 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.
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 theonClose
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 Server 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 theexecute_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 Server 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 andtrue
, 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. IfexpectReply
is not given or isfalse
, the future is done when an idle status message with the appropriate parent header is received, in which case the.done
promise resolves toundefined
.If
disposeOnDone
is given andfalse
, 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.
property runningCount
readonly runningCount: number;
The number of running kernels.
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 Server 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 eitherconnecting
ordisconnected
, the kernel status will beunknown
unless the kernel status wasdead
, in which case it staysdead
.
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 Server 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 Server 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 Server 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 Server 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 Server 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 Server 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 Server 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 Server 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.
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).
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: {