| Copyright | (c) Andrew Gibiansky, 2016 |
|---|---|
| License | MIT |
| Maintainer | andrew.gibiansky@gmail.com |
| Stability | stable |
| Portability | POSIX |
| Safe Haskell | None |
| Language | Haskell2010 |
Jupyter.Messages
Contents
Description
Jupyter kernels and clients communicate along a typed messaging protocol called the Jupyter messaging protocol. The protocol defines several ZeroMQ sockets that are used for communication between the clients and the kernels, as well as the format of the data that is sent on each of those sockets.
To summarize briefly, the messaging protocol defines four types of communication:
- Client to kernel requests (
ClientRequest) and replies (KernelReply) - Kernel output publication to all clients (
KernelOutput) - Kernel to client requests (
KernelRequest) and replies (ClientReply) - Free-form "comm" messages between kernels and clients (
Comm)
Client to kernel requests and replies are sent on two sockets called the shell and control sockets, but
when using the jupyter package these two sockets can be treated as a single communication channel,
with the caveat that two messages may be sent at once (and thus the handlers must be thread-safe). Clients will
send a ClientRequest which the kernel must respond to with a KernelReply.
During the response, kernels may want to publish results, intermediate data, or errors to the front-end(s).
This is done on the iopub socket, with every published value represented via a KernelOutput. Kernel
outputs are the primary mechanism for transmitting results of code evaluation to the front-ends.
In addition to publishing outputs, kernels may request input from the clients during code evaluation using KernelRequest messages, to which the clients reply with a ClientReply. At the moment, the
only use for KernelRequests is to request standard input from the clients, so all such messages go on the stdin socket.
Finally, kernels and frontends can create custom communication protocols using the free-form and unstructured Comm
messages. A comm in Jupyter parlance is a communication channel between a kernel and a client; either one
may request to create or close a comm, and then send arbitrary JSON data along that comm. Kernels listen
for Comm messages on the shell socket and can send their own Comm messages on the iopub socket. (Comm messages
are not used frequently, but have been used to implement, e.g. the Jupyter widgets in
ipywidgets; for most use cases, it is safe to ignore them
and provide empty Comm message handlers.)
For more information, please read the full Jupyter messaging specification.
- data ClientRequest
- newtype CodeBlock = CodeBlock Text
- newtype CodeOffset = CodeOffset Int
- data ExecuteOptions = ExecuteOptions {}
- defaultExecuteOptions :: ExecuteOptions
- data DetailLevel
- data HistoryOptions = HistoryOptions {}
- newtype TargetName = TargetName Text
- data Restart
- data HistoryAccessType
- data HistoryRangeOptions = HistoryRangeOptions {}
- data HistorySearchOptions = HistorySearchOptions {}
- data KernelReply
- data KernelInfo = KernelInfo {}
- data CodeMirrorMode
- data LanguageInfo = LanguageInfo {}
- data HelpLink = HelpLink {
- helpLinkText :: Text
- helpLinkURL :: Text
- newtype ExecuteResult = ExecuteResult (OperationResult ())
- pattern ExecuteOk :: ExecuteResult
- pattern ExecuteError :: ErrorInfo -> ExecuteResult
- pattern ExecuteAbort :: ExecuteResult
- newtype InspectResult = InspectResult (OperationResult (Maybe DisplayData))
- pattern InspectOk :: Maybe DisplayData -> InspectResult
- pattern InspectError :: ErrorInfo -> InspectResult
- pattern InspectAbort :: InspectResult
- newtype CompleteResult = CompleteResult (OperationResult ([CompletionMatch], CursorRange, Map Text Text))
- pattern CompleteOk :: [CompletionMatch] -> CursorRange -> Map Text Text -> CompleteResult
- pattern CompleteError :: ErrorInfo -> CompleteResult
- pattern CompleteAbort :: CompleteResult
- newtype CompletionMatch = CompletionMatch Text
- data CursorRange = CursorRange {
- cursorStart :: Int
- cursorEnd :: Int
- data OperationResult f
- data HistoryItem = HistoryItem {}
- newtype ExecutionCount = ExecutionCount Int
- data CodeComplete
- data ConnectInfo = ConnectInfo {}
- data KernelOutput
- data Stream
- newtype DisplayData = DisplayData (Map MimeType Text)
- displayPlain :: Text -> DisplayData
- displayLatex :: Text -> DisplayData
- displayHtml :: Text -> DisplayData
- displayJavascript :: Text -> DisplayData
- displaySvg :: Text -> DisplayData
- displayPng :: ImageDimensions -> Text -> DisplayData
- displayJpg :: ImageDimensions -> Text -> DisplayData
- data ImageDimensions = ImageDimensions {
- imageWidth :: Int
- imageHeight :: Int
- data MimeType
- data ErrorInfo = ErrorInfo {
- errorName :: Text
- errorValue :: Text
- errorTraceback :: [Text]
- data WaitBeforeClear
- data KernelStatus
- data KernelRequest = InputRequest InputOptions
- data InputOptions = InputOptions {
- inputPrompt :: Text
- inputPassword :: Bool
- data ClientReply = InputReply Text
- data Comm
- newtype TargetModule = TargetModule Text
Client Requests (Shell channel)
data ClientRequest Source
Most communication from a client to a kernel is initiated by the client on the shell socket.
The shell socket accepts multiple incoming connections from different frontends (clients), and receives requests for code execution, object information, prompts, etc. from all the connected frontends. The communication on this socket is a sequence of request/reply actions from each frontend and the kernel.
The clients will send ClientRequest messages to the kernel, to which the kernel must reply with
exactly one appropriate KernelReply and, optionally, publish as many KernelOutputs as the
kernel wishes. Each ClientRequest constructor corresponds to exactly one KernelReply
constructor which should be used in the reply.
For more information on each of these messages, view the appropriate section of the Jupyter messaging spec.
Constructors
| ExecuteRequest CodeBlock ExecuteOptions | Replied to with an This message type is used by frontends to ask the kernel to execute code on behalf of the user, in a namespace reserved to the user’s variables (and thus separate from the kernel’s own internal code and variables). |
| InspectRequest CodeBlock CodeOffset DetailLevel | Replied to with an Code can be inspected to show useful information to the user. It is up to the kernel to decide what information should be displayed, and its formatting. The reply is a mime-bundle, like a |
| HistoryRequest HistoryOptions | Replied to with a For clients to explicitly request history from a kernel. The kernel has all the actual execution history stored in a single location, so clients can request it from the kernel when needed. |
| CompleteRequest CodeBlock CodeOffset | Replied to with a A message type for the client to request autocompletions from the kernel. The lexing is left to the kernel, and the only information provided is the cell contents and the current cursor location in the cell. |
| IsCompleteRequest CodeBlock | Replied to with a When the user enters a line in a console style interface, the console must decide whether to immediately execute the current code, or whether to show a continuation prompt for further input. For instance, in Python There are four possible replies (see the
The frontend should also handle the kernel not replying promptly. It may default to sending the code for execution, or it may implement simple fallback heuristics for whether to execute the code (e.g. execute after a blank line). Frontends may have ways to override this, forcing the code to be sent for execution or forcing a continuation prompt. |
| ConnectRequest | Replied to with a When a client connects to the request/reply socket of the kernel, it can issue a connect request to get basic information about the kernel, such as the ports the other ZeroMQ sockets are listening on. This allows clients to only have to know about a single port (the shell channel) to connect to a kernel. Warning: Connect requests are deprecated in the Jupyter messaging spec. |
| CommInfoRequest (Maybe TargetName) | Replied to with a When a client needs the currently open |
| KernelInfoRequest | Replied to with a If a client needs to know information about the kernel, it can make a
|
| ShutdownRequest Restart | Replied to with a The clients can request the kernel to shut itself down; this is used in multiple cases:
The client sends a shutdown request to the kernel, and once it receives the reply message (which is otherwise empty), it can assume that the kernel has completed shutdown safely. The request can be sent on either the control or shell sockets. Upon their own shutdown, client applications will typically execute a last minute sanity check and forcefully terminate any kernel that is still alive, to avoid leaving stray processes in the user’s machine. Kernels that receive a shutdown request will automatically shut down after replying to it. |
A block of code, represented as text.
data ExecuteOptions Source
Options for executing code in the kernel.
Constructors
| ExecuteOptions | |
Fields
| |
defaultExecuteOptions :: ExecuteOptions Source
Default set of options for an ExecuteRequest.
By default, executeStopOnError and executeStoreHistory are True, while executeSilent and
executeAllowStdin are False.
data DetailLevel Source
How much detail to show for an InspectRequest.
Constructors
| DetailLow | Include a low level of detail. In IPython, |
| DetailHigh | Include a high level of detail. In IPython, |
data HistoryOptions Source
What to search for in the kernel history.
Constructors
| HistoryOptions | |
Fields
| |
newtype TargetName Source
The target name (target_name) for a Comm.
The target name is, roughly, the type of the comm to open. It tells the kernel or the frontend
(whichever receives the CommOpen message) what sort of comm to open and how that comm
should behave. (The TargetModule can also be optionally used in combination with a TargetName
for this purpose; see CommOpen for more info.)
Constructors
| TargetName Text |
Whether the kernel should restart after shutting down, or remain stopped.
data HistoryAccessType Source
What items should be accessed in this HistoryRequest.
Constructors
| HistoryRange HistoryRangeOptions | Get a range of history items. |
| HistoryTail Int | Get the last n cells in the history. |
| HistorySearch HistorySearchOptions | Search for something in the history. |
data HistoryRangeOptions Source
Options for retrieving a range of history cells.
Constructors
| HistoryRangeOptions | |
Fields
| |
data HistorySearchOptions Source
Options for retrieving history cells that match a pattern.
Constructors
| HistorySearchOptions | |
Fields
| |
Kernel Replies (Shell channel)
data KernelReply Source
Clients send requests (ClientRequest) to the kernel via the shell socket, and kernels
generate one KernelReply as a response to every ClientRequest. Each type of ClientRequest
corresponds to precisely one response type (for example, HistoryRequest must be responded to
with a HistoryReply).
Constructors
| KernelInfoReply KernelInfo | Reply for a If a client needs to know information about the kernel, it can make a request
of the kernel’s information, which must be responded to with a
|
| ExecuteReply ExecutionCount ExecuteResult | Reply to an The kernel should have a single, monotonically increasing counter of all
execution requests that are made with when
|
| InspectReply InspectResult | Reply to an Code can be inspected to show useful information to the user. It is up to the kernel to decide what information should be displayed, and its formatting. The reply is a mime-bundle, like a |
| HistoryReply [HistoryItem] | Reply to a Clients can explicitly request history from a kernel. The kernel has all the actual execution history stored in a single location, so clients can request it from the kernel when needed. The |
| CompleteReply CompleteResult | Reply to a Clients can request autocompletion results from the kernel, and the kernel responds with a list of matches and the selection to autocomplete. |
| IsCompleteReply CodeComplete | Reply to a Clients can request the code completeness status with a For example, when the user enters a line in a console style interface, the console must decide whether to immediately execute the current code, or whether to show a continuation prompt for further input. For instance, in Python |
| ConnectReply ConnectInfo | Reply to a When a client connects to the request/reply socket of the kernel, it can
issue a The |
| CommInfoReply (Map UUID TargetName) | Reply to a When a client needs the currently open comms in the kernel, it can issue a
The |
| ShutdownReply Restart | Reply to a The client sends a shutdown request to the kernel, and once it receives the reply message (which is otherwise empty), it can assume that the kernel has completed shutdown safely. The |
data KernelInfo Source
Reply content for a KernelInfoReply, containing core information about the kernel and the
kernel implementation. Pieces of this information are used throughout the frontend for display
purposes.
Refer to the lists of available Pygments lexers and Codemirror modes for those fields.
Constructors
| KernelInfo | |
Fields
| |
Instances
data CodeMirrorMode Source
Value set in a language info object for the CodeMirror mode.
Constructors
| NamedMode Text | Mode described just by its name |
| OptionsMode Text [(Text, Value)] | Mode with a name and a list of extra params. These parameters are interpreted by the CodeMirror library. For example, the |
data LanguageInfo Source
Information about the language of code for a kernel.
Constructors
| LanguageInfo | |
Fields
| |
A link to some help text to include in the frontend's help menu.
Constructors
| HelpLink | |
Fields
| |
newtype ExecuteResult Source
Result from an ExecuteRequest.
No data is included with the result, because all execution results are published via
KernelOutputs instead.
Constructors
| ExecuteResult (OperationResult ()) |
Instances
pattern ExecuteOk :: ExecuteResult Source
Shorthand pattern for a successful ExecuteResult.
pattern ExecuteError :: ErrorInfo -> ExecuteResult Source
Shorthand pattern for an errored ExecuteResult.
pattern ExecuteAbort :: ExecuteResult Source
Shorthand pattern for an aborted ExecuteResult.
newtype InspectResult Source
Result from an InspectRequest.
Result includes inspection results to show to the user (in rich DisplayData format), or
Nothing if no object was found.
Constructors
| InspectResult (OperationResult (Maybe DisplayData)) |
Instances
pattern InspectOk :: Maybe DisplayData -> InspectResult Source
Shorthand pattern for a successful ExecuteResult.
pattern InspectError :: ErrorInfo -> InspectResult Source
Shorthand pattern for an errored InspectResult.
pattern InspectAbort :: InspectResult Source
Shorthand pattern for an aborted InspectResult.
newtype CompleteResult Source
Result from a CompleteRequest.
Result includes a (possibly empty) list of matches, the range of characters to replace with the matches, and any associated metadata for the completions.
Constructors
| CompleteResult (OperationResult ([CompletionMatch], CursorRange, Map Text Text)) |
pattern CompleteOk :: [CompletionMatch] -> CursorRange -> Map Text Text -> CompleteResult Source
Shorthand pattern for a successful ExecuteResult.
pattern CompleteError :: ErrorInfo -> CompleteResult Source
Shorthand pattern for an errored CompleteResult.
pattern CompleteAbort :: CompleteResult Source
Shorthand pattern for an aborted CompleteResult.
newtype CompletionMatch Source
A completion match, including all the text (not just the text after the cursor).
Constructors
| CompletionMatch Text |
data CursorRange Source
Range (of an input cell) to replace with a completion match.
Constructors
| CursorRange | |
Fields
| |
Instances
data OperationResult f Source
Many operations share a similar result structure. They can:
- complete successfully and return a result (
OperationOk) - fail with an error (
OperationError) - be aborted by the user (
OperationAbort)
This data type captures this pattern, and is used in a variety of replies, such as
ExecuteResult and InspectResult.
Constructors
| OperationOk f | The operation completed successfully, returning some value |
| OperationError ErrorInfo | The operation failed, returning error information about the failure. |
| OperationAbort | The operation was aborted by the user. |
Instances
| Eq f => Eq (OperationResult f) Source | |
| Ord f => Ord (OperationResult f) Source | |
| Show f => Show (OperationResult f) Source |
data HistoryItem Source
One item from the kernel history, representing one single input to the kernel. An input corresponds to a cell in a notebook, not a single line in a cell.
Constructors
| HistoryItem | |
Fields
| |
newtype ExecutionCount Source
The execution count, represented as an integer (number of cells evaluated up to this point).
Constructors
| ExecutionCount Int |
data CodeComplete Source
Whether a string of code is complete (no more code needs to be entered), incomplete, or unknown in status.
For example, when the user enters a line in a console style interface, the console must decide whether to immediately execute the current code, or whether to show a continuation prompt for further input.
For instance, in Python a = 5 would be executed immediately, while for i in
range(5): would expect further input.
Constructors
| CodeComplete | The provided code is complete. Complete code is ready to be executed. |
| CodeIncomplete Text | The provided code is incomplete, and the next line should be "indented" with the provided text. Incomplete code should prompt for another line. |
| CodeInvalid | The provided code is invalid. Invalid code will typically be sent for execution, so that the user sees the error soonest. |
| CodeUnknown | Whether provided code is complete or not could not be determined. If the code completeness is unknown, or the kernel does not reply in time, the frontend may default to sending the code for execution, or use a simple heuristic (execute after a blank line) . |
data ConnectInfo Source
Connection information about the ZeroMQ sockets the kernel communicates on.
Constructors
| ConnectInfo | |
Fields
| |
Instances
Kernel Outputs (IOPub channel)
data KernelOutput Source
During processing and code execution, the kernel publishes side effects through messages sent
on its iopub socket. Side effects include kernel outputs and notifications, such as writing to
standard output or standard error, displaying rich outputs via DisplayDataOutput messages,
updating the frontend with kernel status, etc.
Multiple frontends may be subscribed to a single kernel, and KernelOutput messages are
published to all frontends simultaneously.
Constructors
| StreamOutput Stream Text | Write text to |
| DisplayDataOutput DisplayData | Send data that should be displayed (text, html, svg, etc.) to all frontends.
Each message can have multiple representations of the data; it is up to the
frontend to decide which to use and how. A single message should contain all
possible representations of the same information; these representations are
encapsulated in the For transmitting non-textual displays, such as images, data should be base64 encoded and represented as text. |
| ExecuteInputOutput ExecutionCount CodeBlock | Inform all frontends of the currently executing code. To let all frontends
know what code is being executed at any given time, these messages contain a
re-broadcast of the code portion of an |
| ExecuteResultOutput ExecutionCount DisplayData | Results of an execution are published as an Results can have multiple simultaneous formats depending on its configuration.
A plain text representation should always be provided in the text/plain
mime-type ( |
| ExecuteErrorOutput ErrorInfo | When an error occurs during code execution, a |
| KernelStatusOutput KernelStatus | Inform the frontends of the current kernel status. This lets frontends display usage stats and loading indicators to the user. This message type is used by frontends to monitor the status of the kernel. Note: |
| ClearOutput WaitBeforeClear | This message type is used to clear the output that is visible on the frontend. The |
| ShutdownNotificationOutput Restart | Inform the frontends that the kernel is shutting down. This message should be broadcast whenever a |
Output stream to write messages to.
Constructors
| StreamStdout | Standard output |
| StreamStderr | Standard error |
newtype DisplayData Source
A display data mimebundle, used to publish rich data to Jupyter frontends.
A mimebundle contains all possible representations of an object available to the kernel in a map
from MimeType keys to encoded data values. By sending all representations to the Jupyter
frontends, kernels allow the frontends to select the most appropriate representation; for
instance, the console frontend may prefer to use a text representation, while the notebook will
prefer to use an HTML or PNG representation.
All data must be encoded into Text values; for items such as images, the data must be
base64-encoded prior to transmission.
In order to create the DisplayData values, use the provided displayPlain, displayHtml,
displayJavascript, etc, utilities; the Monoid instance can be used to combine DisplayData
values to create values with multiple possible representations.
Constructors
| DisplayData (Map MimeType Text) |
displayPlain :: Text -> DisplayData Source
Create a text/plain DisplayData bundle out of a bit of Text.
displayLatex :: Text -> DisplayData Source
Create a text/latex DisplayData bundle out of a bit of Text.
displayHtml :: Text -> DisplayData Source
Create a text/html DisplayData bundle out of a bit of Text.
displayJavascript :: Text -> DisplayData Source
Create a application/javascript DisplayData bundle out of a bit of Text.
displaySvg :: Text -> DisplayData Source
Create a image/svg+xml DisplayData bundle out of a bit of Text.
displayPng :: ImageDimensions -> Text -> DisplayData Source
Create a image/png DisplayData bundle out of a bit of Text.
The text should be base-64 encoded data.
displayJpg :: ImageDimensions -> Text -> DisplayData Source
Create a image/jpg DisplayData bundle out of a bit of Text.
The text should be base-64 encoded data.
data ImageDimensions Source
Dimensions of an image, to be included with the DisplayData bundle in the MimeType.
Constructors
| ImageDimensions | |
Fields
| |
Mime types for the display data, with any associated metadata that the mime types may require.
Constructors
| MimePlainText | A |
| MimeHtml | A |
| MimePng ImageDimensions | A |
| MimeJpg ImageDimensions | A |
| MimeSvg | A |
| MimeLatex | A |
| MimeJavascript | A |
Error information, to be displayed to the user.
Constructors
| ErrorInfo | |
Fields
| |
data WaitBeforeClear Source
Whether a ClearOutput should clear the display immediately, or clear the display right before
the next display arrives.
If ClearImmediately is used, then the frontend may "blink", as there may be a moment after the
display is cleared but before a new display available, whereas ClearBeforeNextOutput is meant
to alleviate the blinking effect.
Used with the ClearOutput kernel output message.
Constructors
| ClearBeforeNextOutput | Clear the display area immediately. |
| ClearImmediately | Clear the display area right before the next display arrives. |
data KernelStatus Source
Status of the kernel.
Used with KernelStatusOutput messages to let the frontend know what the kernel is doing.
Constructors
| KernelIdle |
|
| KernelBusy |
|
| KernelStarting |
|
Kernel Requests (Stdin channel)
data KernelRequest Source
Although usually kernels respond to clients' requests, the request/reply can also go in the opposite direction: from the kernel to a single frontend. The purpose of these messages (sent on the stdin socket) is to allow code to request input from the user (in particular reading from standard input) and to have those requests fulfilled by the client. The request should be made to the frontend that made the execution request that prompted the need for user input.
Constructors
| InputRequest InputOptions | Request text input from standard input. |
data InputOptions Source
Metadata for requesting input from the user.
Constructors
| InputOptions | |
Fields
| |
Instances
Client Replies (Stdin channel)
data ClientReply Source
Replies from the client to the kernel, as a result of the kernel sending a KernelRequest to
the client.
Constructors
| InputReply Text | Returns the text input by the user to the frontend. |
Comm Messages (Shell or IOPub channel)
Comm messages provide developers with an unstructured communication channel between the
kernel and the frontend which exists on both sides and can communicate in any direction.
These messages are fully symmetrical - both the kernel and the frontend can send each message, and no messages expect a reply.
Every comm has an ID and a target name. The code handling the message on the receiving side
(which may be the client or the kernel) is responsible for creating a comm given the target
name of the comm being created.
Once a comm is open with a CommOpen message, the comm should exist immediately on both
sides, until the comm is closed with a CommClose message.
For more information on comm messages, read the
section in the Jupyter messaging spec.
Constructors
| CommOpen UUID Value TargetName (Maybe TargetModule) | A The The auxiliary JSON |
| CommClose UUID Value | A The auxiliary JSON |
| CommMessage UUID Value | A |
newtype TargetModule Source
Target module for a CommOpen message, optionally used in combination with a TargetName to
let the receiving side of the CommOpen message know how to create the comm.
Constructors
| TargetModule Text |