A signal emitted when any kernel message is sent or received.
This signal is emitted before any message handling has happened. The message should be treated as read-only.
Readonly clientReadonly connectionThe current connection status of the kernel.
A signal emitted when the kernel connection status changes.
Readonly disposedA signal emitted when the object is disposed.
Whether the kernel connection handles comm messages.
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.
Whether the kernel connection has pending input.
This is a guard to avoid deadlock is the user asks input as second time before submitting his first input
Readonly idThe id of the server-side kernel.
Readonly infoA signal emitted after an iopub kernel message is handled.
Readonly isReadonly modelThe kernel model, for convenience.
Readonly nameThe name of the server-side kernel.
A signal emitted when a kernel has pending inputs from the user.
Readonly serverThe server settings for the kernel.
Readonly specGet the kernel spec.
A promise that resolves with the kernel spec for this kernel.
This may make a server request to retrieve the spec.
Readonly statusThe current status of the kernel.
A signal emitted when the kernel status changes.
A signal emitted for unhandled non-iopub kernel messages that claimed to be responses for messages we sent using this kernel object.
Readonly usernameThe client username.
Clone the current kernel with a new clientId.
Optional options: Pick<Kernel.IKernelConnection.IOptions, "username" | "clientId" | "handleComms">Dispose of the resources held by the object.
If the object's dispose method is called more than once, all
calls made after the first will be a no-op.
It is undefined behavior to use any functionality of the object after it has been disposed unless otherwise explicitly noted.
Interrupt a kernel.
A promise that resolves when the kernel has interrupted.
Uses the Jupyter Server API.
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.
Register a comm target handler.
The name of the comm target.
The callback invoked for a comm open message.
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.
Register an IOPub message hook.
The callback invoked for the message.
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]].
Remove a comm target handler.
The name of the comm target to remove.
Send a comm_info_request message.
The content of the request.
Optional target_The comm target name to filter returned comms
A promise that resolves with the response message.
See Messaging in Jupyter.
Fulfills with the comm_info_reply content when the shell reply is
received and validated.
Send a complete_request message.
The content of the request.
A promise that resolves with the response message.
See Messaging in Jupyter.
Fulfills with the complete_reply content when the shell reply is
received and validated.
Send an execute_request message.
The content of the request.
Optional allow_Whether to allow stdin requests.
The default is true.
The code to execute.
Optional silent?: booleanWhether to execute the code as quietly as possible.
The default is false.
Optional stop_Whether to the abort execution queue on an error.
The default is false.
Optional store_Whether to store history of the execution.
The default true if silent is False.
It is forced to false if silent is true.
Optional user_A mapping of names to expressions to be evaluated in the kernel's interactive namespace.
Optional disposeOnDone: booleanWhether to dispose of the future when done.
Optional metadata: JSONObjectA kernel future.
See Messaging in Jupyter.
This method returns a kernel future, rather than a promise, since execution may have many response messages (for example, many iopub display messages).
Future onReply is called with the execute_reply content when the
shell reply is received and validated.
See also: [[IExecuteReply]]
Send a history_request message.
The content of the request.
A promise that resolves with the response message.
See Messaging in Jupyter.
Fulfills with the history_reply content when the shell reply is
received and validated.
Send an inspect_request message.
The content of the request.
A promise that resolves with the response message.
See Messaging in Jupyter.
Fulfills with the inspect_reply content when the shell reply is
received and validated.
Send an is_complete_request message.
The content of the request.
A promise that resolves with the response message.
See Messaging in Jupyter.
Fulfills with the is_complete_response content when the shell reply is
received and validated.
Send a kernel_info_request message.
A promise that resolves with the response message.
See Messaging in Jupyter.
Fulfills with the kernel_info_response content when the shell reply is
received and validated.
Restart a kernel.
A promise that resolves when the kernel has restarted.
Uses the Jupyter Server API 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.
Optional expectReply: booleanOptional disposeOnDone: booleanSend an input_reply message.
Send a shell message to the kernel.
The fully-formed shell message to send.
Optional expectReply: booleanWhether to expect a shell reply message.
Optional disposeOnDone: booleanWhether to dispose of the future when done.
Send a message to the kernel's shell channel, yielding a future object for accepting replies.
If expectReply is given and true, the future is done when both a
shell reply and an idle status message are received with the appropriate
parent header, in which case the .done promise resolves to the reply.
If expectReply is not given or is false, the future is done when an
idle status message with the appropriate parent header is received, in
which case the .done promise resolves to undefined.
If disposeOnDone is given and false, the future will not be disposed
of when the future is done, instead relying on the caller to dispose of
it. This allows for the handling of out-of-order output from ill-behaved
kernels.
All replies are validated as valid kernel messages.
If the kernel status is 'dead', this will throw an error.
Shutdown a kernel.
A promise that resolves when the kernel has shut down.
Uses the Jupyter Notebook API.
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 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.