Class KernelConnection

constructor

• new KernelConnection(
      options: Kernel.IKernelConnection.IOptions,
  ): KernelConnection

• Construct a kernel object.

  Parameters

  • options: Kernel.IKernelConnection.IOptions

  Returns KernelConnection

ReadonlyhandleComms

ReadonlyserverSettings

anyMessage

• get anyMessage(): ISignal<this, 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.

  Returns ISignal<this, IAnyMessageArgs>

clientId

• get clientId(): string

• The client unique id.

  Returns string

connectionStatus

• get connectionStatus(): Kernel.ConnectionStatus

• The current connection status of the kernel connection.

  Returns Kernel.ConnectionStatus

connectionStatusChanged

• get connectionStatusChanged(): ISignal<this, Kernel.ConnectionStatus>

• A signal emitted when the kernel status changes.

  Returns ISignal<this, Kernel.ConnectionStatus>

disposed

• get disposed(): ISignal<this, void>

• A signal emitted when the object is disposed.

  Returns ISignal<this, void>

hasPendingInput

• get 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

  Returns boolean
• set hasPendingInput(value: boolean): void

• 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

  Parameters

  • value: boolean

  Returns void

id

• get id(): string

• The id of the server-side kernel.

  Returns string

info

• get info(): Promise<KernelMessage.IInfoReply>

• The cached kernel info.

  Returns Promise<KernelMessage.IInfoReply>

  A promise that resolves to the kernel info.

iopubMessage

• get iopubMessage(): ISignal<this, IIOPubMessage<IOPubMessageType>>

• A signal emitted for iopub kernel messages.

  Notes

  This signal is emitted after the iopub message is handled asynchronously.

  Returns ISignal<this, IIOPubMessage<IOPubMessageType>>

isDisposed

• get isDisposed(): boolean

• Test whether the kernel has been disposed.

  Returns boolean

model

• get model(): Kernel.IModel

• The kernel model

  Returns Kernel.IModel

name

• get name(): string

• The name of the server-side kernel.

  Returns string

pendingInput

• get pendingInput(): ISignal<this, boolean>

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

  Returns ISignal<this, boolean>

spec

• get spec(): Promise<undefined | KernelSpec.ISpecModel>

• The kernel spec.

  Returns Promise<undefined | KernelSpec.ISpecModel>

  A promise that resolves to the kernel spec.

status

• get status(): Kernel.Status

• The current status of the kernel.

  Returns Kernel.Status

statusChanged

• get statusChanged(): ISignal<this, Kernel.Status>

• A signal emitted when the kernel status changes.

  Returns ISignal<this, Kernel.Status>

subshellId

• get subshellId(): null | string

• The subshell ID.

  Returns null | string
• set subshellId(value: null | string): void

• Set the subshell ID.

  Parameters

  • value: null | string

  Returns void

supportsSubshells

• get supportsSubshells(): boolean

• Check if this kernel supports JEP 91 kernel subshells.

  Returns boolean

unhandledMessage

• get 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.

  Returns ISignal<this, KernelMessage.IMessage<KernelMessage.MessageType>>

username

• get username(): string

• The client username.

  Returns string

clone

• clone(
      options?: Pick<
          Kernel.IKernelConnection.IOptions,
          "username"
          | "clientId"
          | "handleComms",
      >,
  ): Kernel.IKernelConnection

• Clone the current kernel with a new clientId.

  Parameters

  • options: Pick<Kernel.IKernelConnection.IOptions, "username" | "clientId" | "handleComms"> = {}

  Returns Kernel.IKernelConnection

createComm

• createComm(targetName: string, commId?: string): 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.

  Parameters

  • targetName: string
  • commId: string = ...

  Returns IComm

dispose

• dispose(): void

• Dispose of the resources held by the kernel.

  Returns void

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).

  Returns void

hasComm

• hasComm(commId: string): boolean

• Check if a comm exists.

  Parameters

  • commId: string

  Returns boolean

interrupt

• interrupt(): Promise<void>

• Interrupt a kernel.

  Notes

  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.

  Returns Promise<void>

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.

  Returns Promise<void>

registerCommTarget

• registerCommTarget(
      targetName: string,
      callback: (
          comm: IComm,
          msg: ICommOpenMsg<"iopub" | "shell">,
      ) => void | PromiseLike<void>,
  ): void

• Register a comm target handler.

  Parameters

  • targetName: string

    The name of the comm target.
  • callback: (comm: IComm, msg: ICommOpenMsg<"iopub" | "shell">) => void | PromiseLike<void>

    The callback invoked for a comm open message.

  Returns void

  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.

registerMessageHook

• registerMessageHook(
      msgId: string,
      hook: (
          msg: IIOPubMessage<IOPubMessageType>,
      ) => boolean | PromiseLike<boolean>,
  ): void

• Register an IOPub message hook.

  Parameters

  • msgId: string
  • hook: (msg: IIOPubMessage<IOPubMessageType>) => boolean | PromiseLike<boolean>

    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]].

  Returns void

removeCommTarget

• removeCommTarget(
      targetName: string,
      callback: (
          comm: IComm,
          msg: ICommOpenMsg<"iopub" | "shell">,
      ) => void | PromiseLike<void>,
  ): void

• Remove a comm target handler.

  Parameters

  • targetName: string

    The name of the comm target to remove.
  • callback: (comm: IComm, msg: ICommOpenMsg<"iopub" | "shell">) => void | PromiseLike<void>

    The callback to remove.

    Notes

    The comm target is only removed if the callback argument matches.

  Returns void

removeInputGuard

• removeInputGuard(): void

• Remove the input guard, if any.

  Returns void

removeMessageHook

• removeMessageHook(
      msgId: string,
      hook: (
          msg: IIOPubMessage<IOPubMessageType>,
      ) => boolean | PromiseLike<boolean>,
  ): void

• Remove an IOPub message hook.

  Parameters

  • msgId: string
  • hook: (msg: IIOPubMessage<IOPubMessageType>) => boolean | PromiseLike<boolean>

    The callback invoked for the message.

  Returns void

requestCommInfo

• requestCommInfo(content: { target_name?: string }): Promise<ICommInfoReplyMsg>

• Send a comm_info_request message.

  Notes

  Fulfills with the comm_info_reply content when the shell reply is received and validated.

  Parameters

  • content: { target_name?: string }

    • Optionaltarget_name?: string

      The comm target name to filter returned comms

  Returns Promise<ICommInfoReplyMsg>

requestComplete

• requestComplete(
      content: { code: string; cursor_pos: number },
  ): Promise<ICompleteReplyMsg>

• Send a complete_request message.

  Notes

  See Messaging in Jupyter.

  Fulfills with the complete_reply content when the shell reply is received and validated.

  Parameters

  • content: { code: string; cursor_pos: number }

  Returns Promise<ICompleteReplyMsg>

requestCreateSubshell

• requestCreateSubshell(
      content: Record<string, unknown>,
      disposeOnDone?: boolean,
  ): IControlFuture<ICreateSubshellRequestMsg, ICreateSubshellReplyMsg>

• Send a create_subshell_request message.

  https://github.com/jupyter/enhancement-proposals/pull/91

  Parameters

  • content: Record<string, unknown>
  • disposeOnDone: boolean = true

  Returns IControlFuture<ICreateSubshellRequestMsg, ICreateSubshellReplyMsg>

requestDeleteSubshell

• requestDeleteSubshell(
      content: { subshell_id: string },
      disposeOnDone?: boolean,
  ): IControlFuture<IDeleteSubshellRequestMsg, IDeleteSubshellReplyMsg>

• Send a delete_subshell_request message.

  https://github.com/jupyter/enhancement-proposals/pull/91

  Parameters

  • content: { subshell_id: string }
  • disposeOnDone: boolean = true

  Returns IControlFuture<IDeleteSubshellRequestMsg, IDeleteSubshellReplyMsg>

requestExecute

• requestExecute(
      content: {
          allow_stdin?: boolean;
          code: string;
          silent?: boolean;
          stop_on_error?: boolean;
          store_history?: boolean;
          user_expressions?: JSONObject;
      },
      disposeOnDone?: boolean,
      metadata?: JSONObject,
  ): IShellFuture<IExecuteRequestMsg, IExecuteReplyMsg>

• Send an execute_request message.

  Notes

  See Messaging in Jupyter.

  Future onReply is called with the execute_reply content when the shell reply is received and validated. The future will resolve when this message is received and the idle iopub status is received. The future will also be disposed at this point unless disposeOnDone is specified and false, in which case it is up to the caller to dispose of the future.

  See also: [[IExecuteReply]]

  Parameters

  • content: {
        allow_stdin?: boolean;
        code: string;
        silent?: boolean;
        stop_on_error?: boolean;
        store_history?: boolean;
        user_expressions?: JSONObject;
    }

    • Optionalallow_stdin?: boolean

      Whether to allow stdin requests. The default is true.

    • code: string

      The code to execute.

    • Optionalsilent?: boolean

      Whether to execute the code as quietly as possible. The default is false.

    • Optionalstop_on_error?: boolean

      Whether to the abort execution queue on an error. The default is false.

    • Optionalstore_history?: boolean

      Whether to store history of the execution. The default true if silent is False. It is forced to false if silent is true.

    • Optionaluser_expressions?: JSONObject

      A mapping of names to expressions to be evaluated in the kernel's interactive namespace.
  • disposeOnDone: boolean = true
  • Optionalmetadata: JSONObject

  Returns IShellFuture<IExecuteRequestMsg, IExecuteReplyMsg>

requestHistory

• requestHistory(
      content:
          | IHistoryRequestRange
          | IHistoryRequestSearch
          | IHistoryRequestTail,
  ): Promise<IHistoryReplyMsg>

• Send a history_request message.

  Notes

  See Messaging in Jupyter.

  Fulfills with the history_reply content when the shell reply is received and validated.

  Parameters

  • content: IHistoryRequestRange | IHistoryRequestSearch | IHistoryRequestTail

  Returns Promise<IHistoryReplyMsg>

requestInspect

• requestInspect(
      content: { code: string; cursor_pos: number; detail_level: 0 | 1 },
  ): Promise<IInspectReplyMsg>

• Send an inspect_request message.

  Notes

  See Messaging in Jupyter.

  Fulfills with the inspect_reply content when the shell reply is received and validated.

  Parameters

  • content: { code: string; cursor_pos: number; detail_level: 0 | 1 }

  Returns Promise<IInspectReplyMsg>

requestIsComplete

• requestIsComplete(content: { code: string }): Promise<IIsCompleteReplyMsg>

• Send an is_complete_request message.

  Notes

  See Messaging in Jupyter.

  Fulfills with the is_complete_response content when the shell reply is received and validated.

  Parameters

  • content: { code: string }

  Returns Promise<IIsCompleteReplyMsg>

requestKernelInfo

• requestKernelInfo(): Promise<undefined | IInfoReplyMsg>

• Send a kernel_info_request message.

  Notes

  See Messaging in Jupyter.

  Fulfills with the kernel_info_response content when the shell reply is received and validated.

  Returns Promise<undefined | IInfoReplyMsg>

requestListSubshell

• requestListSubshell(
      content: Record<string, unknown>,
      disposeOnDone?: boolean,
  ): IControlFuture<IListSubshellRequestMsg, IListSubshellReplyMsg>

• Send a list_subshell_request message.

  https://github.com/jupyter/enhancement-proposals/pull/91

  Parameters

  • content: Record<string, unknown>
  • disposeOnDone: boolean = true

  Returns IControlFuture<IListSubshellRequestMsg, IListSubshellReplyMsg>

restart

• restart(): Promise<void>

• Request a kernel restart.

  Notes

  Uses the Jupyter Server API 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.

  Returns Promise<void>

sendControlMessage

• sendControlMessage<T extends ControlMessageType>(
      msg: IControlMessage<T>,
      expectReply?: boolean,
      disposeOnDone?: boolean,
  ): IControlFuture<IControlMessage<T>, IControlMessage<ControlMessageType>>

• Send a control message to the kernel.

  Notes

  Send a message to the kernel's control channel, yielding a future object for accepting replies.

  If expectReply is given and true, the future is disposed when both a control reply and an idle status message are received. If expectReply is not given or is false, the future is resolved when an idle status message is received. If disposeOnDone is not given or is true, the Future is disposed at this point. If disposeOnDone is given and false, it is up to the caller to dispose of the Future.

  All replies are validated as valid kernel messages.

  If the kernel status is dead, this will throw an error.

  Type Parameters

  • T extends ControlMessageType

  Parameters

  • msg: IControlMessage<T>
  • expectReply: boolean = false
  • disposeOnDone: boolean = true

  Returns IControlFuture<IControlMessage<T>, IControlMessage<ControlMessageType>>

sendInputReply

• sendInputReply(
      content: ReplyContent<IInputReply>,
      parent_header: IHeader<"input_request">,
  ): void

• Send an input_reply message.

  Notes

  See Messaging in Jupyter.

  Parameters

  • content: ReplyContent<IInputReply>
  • parent_header: IHeader<"input_request">

  Returns void

sendShellMessage

• sendShellMessage<T extends ShellMessageType>(
      msg: IShellMessage<T>,
      expectReply?: boolean,
      disposeOnDone?: boolean,
  ): IShellFuture<IShellMessage<T>, IShellMessage<ShellMessageType>>

• Send a shell message to the kernel.

  Notes

  Send a message to the kernel's shell channel, yielding a future object for accepting replies.

  If expectReply is given and true, the future is disposed when both a shell reply and an idle status message are received. If expectReply is not given or is false, the future is resolved when an idle status message is received. If disposeOnDone is not given or is true, the Future is disposed at this point. If disposeOnDone is given and false, it is up to the caller to dispose of the Future.

  All replies are validated as valid kernel messages.

  If the kernel status is dead, this will throw an error.

  Type Parameters

  • T extends ShellMessageType

  Parameters

  • msg: IShellMessage<T>
  • expectReply: boolean = false
  • disposeOnDone: boolean = true

  Returns IShellFuture<IShellMessage<T>, IShellMessage<ShellMessageType>>

shutdown

• shutdown(): Promise<void>

• Shutdown a kernel.

  Notes

  Uses the Jupyter Server API.

  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.

  Returns Promise<void>