Copyright	(c) Andrew Gibiansky, 2016
License	MIT
Maintainer	andrew.gibiansky@gmail.com
Stability	stable
Portability	POSIX
Safe Haskell	None
Language	Haskell2010

Jupyter.Messages

Contents

Client Requests (Shell channel)
Kernel Replies (Shell channel)
Kernel Outputs (IOPub channel)
Kernel Requests (Stdin channel)
Client Replies (Stdin channel)
Comm Messages (Shell or IOPub channel)

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.

Synopsis

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 `ExecuteReply`. 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 `InspectReply`. 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 `DisplayDataOutput` message, which should be a formatted representation of information about the context. In the notebook, this is used to show tooltips over function calls, etc.
HistoryRequest HistoryOptions	Replied to with a `HistoryReply`. 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 `CompleteReply`. 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 `IsCompleteReply`. 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. There are four possible replies (see the `CodeComplete` data type): complete: code is ready to be executed incomplete: code should prompt for another line invalid: code will typically be sent for execution, so that the user sees the error soonest. unknown: if the kernel is not able to determine this. 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 `ConnectReply`. 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 `CommInfoReply`. When a client needs the currently open `comm`s in the kernel, it can issue a `CommInfoRequest` for the currently open `comm`s. When the optional `TargetName` is specified, the `CommInfoReply` should only contain the currently open `comm`s for that target.
KernelInfoRequest	Replied to with a `KernelInfoReply`. If a client needs to know information about the kernel, it can make a `KernelInfoRequest`. This message can be used to fetch core information of the kernel, including language (e.g., Python), language version number and IPython version number, and the IPython message spec version number.
ShutdownRequest Restart	Replied to with a `ShutdownReply`. The clients can request the kernel to shut itself down; this is used in multiple cases: when the user chooses to close the client application via a menu or window control. when the user invokes a frontend-specific exit method (like the `quit` magic) when the user chooses a GUI method (like the Ctrl-C shortcut in the IPythonQt client) to force a kernel restart to get a clean kernel without losing client-side state like history or inlined figures. 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.

Instances

Eq ClientRequest Source
Ord ClientRequest Source
Show ClientRequest Source
ToJSON ClientRequest Source
IsMessage ClientRequest Source

newtype CodeBlock Source

A block of code, represented as text.

Constructors

CodeBlock Text

Instances

Eq CodeBlock Source
Ord CodeBlock Source
Show CodeBlock Source
IsString CodeBlock Source
ToJSON CodeBlock Source
FromJSON CodeBlock Source

newtype CodeOffset Source

A zero-indexed offset into a block of code.

Constructors

CodeOffset Int

Instances

Eq CodeOffset Source
Num CodeOffset Source
Ord CodeOffset Source
Show CodeOffset Source
ToJSON CodeOffset Source
FromJSON CodeOffset Source

data ExecuteOptions Source

Options for executing code in the kernel.

Constructors

ExecuteOptions

Fields

executeSilent :: Bool

Whether this code should be forced to be as silent as possible.

Kernels should avoid broadcasting on the iopub channel (sending KernelOutput messages) and the ExecuteReply message will not be sent when executeSilent is True. In addition, kernels should act as if executeStoreHistory is set to True whenever executeSilent is True.

executeStoreHistory :: Bool

A boolean flag which, if True, signals the kernel to populate its history. If executeSilent is True, kernels should ignore the value of this flag and treat it as False.

executeAllowStdin :: Bool

Some frontends do not support stdin requests.

If such a frontend makes a request, it should set executeAllowStdin to False, and any code that reads from stdin should crash (or, if the kernel so desires, get an empty string).

executeStopOnError :: Bool

A boolean flag, which, if True, does not abort the execution queue, if an exception or error is encountered. This allows the queued execution of multiple execute_requests, even if they generate exceptions.

Instances

Eq ExecuteOptions Source
Ord ExecuteOptions Source
Show ExecuteOptions Source

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, `DetailLow` is equivalent to typing `x?` at the prompt.
DetailHigh	Include a high level of detail. In IPython, `DetailHigh` is equivalent to typing `x??` at the prompt, and tries to include the source code.

Instances

Eq DetailLevel Source
Ord DetailLevel Source
Show DetailLevel Source
ToJSON DetailLevel Source

data HistoryOptions Source

What to search for in the kernel history.

Constructors

HistoryOptions
Fields historyShowOutput :: Bool If `True`, include text output in the resulting `HistoryItem`s. historyRaw :: Bool If `True`, return the raw input history, else the transformed input. historyAccessType :: HistoryAccessType Type of search to perform.

Instances

Eq HistoryOptions Source
Ord HistoryOptions Source
Show HistoryOptions Source

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

Instances

Eq TargetName Source
Ord TargetName Source
Show TargetName Source
IsString TargetName Source
ToJSON TargetName Source
FromJSON TargetName Source

data Restart Source

Whether the kernel should restart after shutting down, or remain stopped.

Constructors

Restart	Restart after shutting down.
NoRestart	Remain stopped after shutting down.

Instances

Eq Restart Source
Ord Restart Source
Show Restart Source
ToJSON Restart Source
FromJSON Restart Source

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.

Instances

Eq HistoryAccessType Source
Ord HistoryAccessType Source
Show HistoryAccessType Source

data HistoryRangeOptions Source

Options for retrieving a range of history cells.

Constructors

HistoryRangeOptions
Fields historyRangeSession :: Int Which cell to retrieve history for. If this is negative, then it counts backwards from the current session. historyRangeStart :: Int Which item to start with in the selected session. historyRangeStop :: Int Which item to end with in the selected session.

Instances

Eq HistoryRangeOptions Source
Ord HistoryRangeOptions Source
Show HistoryRangeOptions Source

data HistorySearchOptions Source

Options for retrieving history cells that match a pattern.

Constructors

HistorySearchOptions
Fields historySearchCells :: Int Get the last n cells that match the provided pattern. historySearchPattern :: Text Pattern to search for (treated literally but with `*` and `?` as wildcards). historySearchUnique :: Bool If `True`, do not include duplicated history items.

Instances

Eq HistorySearchOptions Source
Ord HistorySearchOptions Source
Show HistorySearchOptions Source

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 `KernelInfoRequest`. 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 `KernelInfoReply`. This message can be used to fetch core information of the kernel, including language (e.g., Python), language version number and IPython version number, and the IPython message spec version number.
ExecuteReply ExecutionCount ExecuteResult	Reply to an `ExecuteRequest` message. The kernel should have a single, monotonically increasing counter of all execution requests that are made with when `executeStoreHistory` is `True`. This counter is used to populate the `In[n]` and `Out[n]` prompts in the frontend. The value of this counter will be returned as the `ExecutionCount` field of all `ExecuteReply` and `ExecuteInput` messages. `ExecuteReply` does not include any output data, only a status, as the output data is sent via `DisplayDataOutput` messages on the iopub channel (in `KernelOutput` messages).
InspectReply InspectResult	Reply to an `InspectRequest`. 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 `DisplayDataOutput` message, which should be a formatted representation of information about the context. In the notebook, this is used to show tooltips over function calls, etc.
HistoryReply [HistoryItem]	Reply to a `HistoryRequest`. 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 `HistoryItem`s should include non-`Nothing` `historyItemOutput` values when `historyShowOutput` in the `HistoryRequest` is `True`.
CompleteReply CompleteResult	Reply to a `CompleteRequest`. 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 `IsCompleteRequest`. Clients can request the code completeness status with a `IsCompleteRequest`. 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.
ConnectReply ConnectInfo	Reply to a `ConnectReply`. When a client connects to the request/reply socket of the kernel, it can issue a `ConnectRequest` 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. The `ConnectReply` contains a `ConnectInfo` with information about the ZeroMQ sockets' ports used by the kernel.
CommInfoReply (Map UUID TargetName)	Reply to a `CommInfoRequest`. When a client needs the currently open comms in the kernel, it can issue a `CommInfoRequest` for the currently open comms. The `CommInfoReply` provides a list of currently open `comm`s with their respective target names to the frontend.
ShutdownReply Restart	Reply to a `ShutdownRequest`. 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 `ShutdownReply` allows for a safe shutdown, but, if no `ShutdownReply` is received (for example, if the kernel is deadlocked) 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.

Instances

Eq KernelReply Source
Show KernelReply Source
ToJSON KernelReply Source
IsMessage KernelReply Source

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

kernelProtocolVersion :: Text: Version of messaging protocol, usually two or three integers in the format X.Y or X.Y.Z. The first integer indicates major version. It is incremented when there is any backward incompatible change. The second integer indicates minor version. It is incremented when there is any backward compatible change.
kernelBanner :: Text: A banner of information about the kernel, which may be desplayed in console environments.
kernelImplementation :: Text: The kernel implementation name (e.g. ipython for the IPython kernel)
kernelImplementationVersion :: Text: Implementation version number. The version number of the kernel's implementation (e.g. IPython.version for the IPython kernel)
kernelLanguageInfo :: LanguageInfo: Information about the language of code for the kernel
kernelHelpLinks :: [HelpLink]: A list of help links. These will be displayed in the help menu in the notebook UI.

Instances

Eq KernelInfo Source
Show KernelInfo Source

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 CodeMirrorMode that corresponds to the JSON value {"name": "mode", "key": "value"} would be OptionsMode "mode" [("mode", String "value")].

Instances

Eq CodeMirrorMode Source
Show CodeMirrorMode Source
ToJSON CodeMirrorMode Source
FromJSON CodeMirrorMode Source

data LanguageInfo Source

Information about the language of code for a kernel.

Constructors

LanguageInfo

Fields

languageName :: Text: Name of the programming language that the kernel implements. Kernel included in IPython returns python.
languageVersion :: Text: Language version number. It is Python version number (e.g., 2.7.3) for the kernel included in IPython.
languageMimetype :: Text: mimetype for script files in this language.
languageFileExtension :: Text: Extension for script files including the dot, e.g. .py
languagePygmentsLexer :: Maybe Text: Pygments lexer, for highlighting (Only needed if it differs from the languageName field.)
languageCodeMirrorMode :: Maybe CodeMirrorMode: Codemirror mode, for for highlighting in the notebook. (Only needed if it differs from the languageName field.)
languageNbconvertExporter :: Maybe Text: Nbconvert exporter, if notebooks written with this kernel should be exported with something other than the general script exporter.

Instances

Eq LanguageInfo Source
Show LanguageInfo Source
ToJSON LanguageInfo Source
FromJSON LanguageInfo Source

data HelpLink Source

A link to some help text to include in the frontend's help menu.

Constructors

HelpLink
Fields helpLinkText :: Text Text to show for the link. helpLinkURL :: Text URL the link points to. This URL is not validated, and is used directly as the link destination.

Instances

Eq HelpLink Source
Ord HelpLink Source
Show HelpLink Source
ToJSON HelpLink Source
FromJSON HelpLink Source

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

Eq ExecuteResult Source
Ord ExecuteResult Source
Show ExecuteResult Source

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

Eq InspectResult Source
Ord InspectResult Source
Show InspectResult Source

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

Instances

Eq CompleteResult Source
Ord CompleteResult Source
Show CompleteResult Source

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

Instances

Eq CompletionMatch Source
Ord CompletionMatch Source
Show CompletionMatch Source
IsString CompletionMatch Source
ToJSON CompletionMatch Source
FromJSON CompletionMatch Source

data CursorRange Source

Range (of an input cell) to replace with a completion match.

Constructors

CursorRange
Fields cursorStart :: Int Beginning of the range (in characters). cursorEnd :: Int End of the range (in characters).

Instances

Eq CursorRange Source
Ord CursorRange Source
Show CursorRange Source

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 `f`.
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 historyItemSession :: Int The session of this input. historyItemLine :: Int The line number in the session. historyItemInput :: Text The input on this line. historyItemOutput :: Maybe Text Optionally, the output when this was run.

Instances

Eq HistoryItem Source
Ord HistoryItem Source
Show HistoryItem Source
ToJSON HistoryItem Source
FromJSON HistoryItem Source

newtype ExecutionCount Source

The execution count, represented as an integer (number of cells evaluated up to this point).

Constructors

ExecutionCount Int

Instances

Eq ExecutionCount Source
Num ExecutionCount Source
Ord ExecutionCount Source
Show ExecutionCount Source
ToJSON ExecutionCount Source
FromJSON ExecutionCount Source

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

Instances

Eq CodeComplete Source
Ord CodeComplete Source
Show CodeComplete Source
FromJSON CodeComplete Source

data ConnectInfo Source

Connection information about the ZeroMQ sockets the kernel communicates on.

Constructors

ConnectInfo
Fields connectShellPort :: Int The port the shell ROUTER socket is listening on. connectIopubPort :: Int The port the PUB socket is listening on. connectStdinPort :: Int The port the stdin ROUTER socket is listening on. connectHeartbeatPort :: Int The port the heartbeat REP socket is listening on. connectControlPort :: Int The port the control ROUTER socket is listening on.

Instances

Eq ConnectInfo Source
Ord ConnectInfo Source
Show ConnectInfo Source

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 `stdout` (`StreamStdout`) or `stderr` (`StreamStderr`).
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 `DisplayData` type. 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 `ExecuteRequest`, along with the `ExecutionCount`.
ExecuteResultOutput ExecutionCount DisplayData	Results of an execution are published as an `ExecuteResult`. These are identical to `DisplayDataOutput` messages, with the addition of an `ExecutionCount` key. Results can have multiple simultaneous formats depending on its configuration. A plain text representation should always be provided in the text/plain mime-type (`MimePlainText`). Frontends are free to display any or all of the provided representations according to their capabilities, and should ignore mime-types they do not understand.
ExecuteErrorOutput ErrorInfo	When an error occurs during code execution, a `ExecuteErrorOutput` should be published to inform all frontends of the error.
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: `KernelBusy` and `KernelIdle` messages should be sent before and after handling every message (not just code execution!).
ClearOutput WaitBeforeClear	This message type is used to clear the output that is visible on the frontend. The `WaitBeforeClear` parameter changes when the output will be cleared (immediately or delayed until next output).
ShutdownNotificationOutput Restart	Inform the frontends that the kernel is shutting down. This message should be broadcast whenever a `ShutdownRequest` is received, so that all frontends, not just the one that requested the shutdown, know the kernel is shutting down. The `Restart` field should match what was requested in the `ShutdownRequest`.

Instances

Eq KernelOutput Source
Ord KernelOutput Source
Show KernelOutput Source
ToJSON KernelOutput Source
IsMessage KernelOutput Source

data Stream Source

Output stream to write messages to.

Constructors

StreamStdout	Standard output
StreamStderr	Standard error

Instances

Eq Stream Source
Ord Stream Source
Show Stream Source
ToJSON Stream Source
FromJSON Stream Source

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)

Instances

Eq DisplayData Source
Ord DisplayData Source
Show DisplayData Source
Generic DisplayData Source
Monoid DisplayData Source
type Rep DisplayData Source

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 imageWidth :: Int Image width, in pixels. imageHeight :: Int Image height, in pixels.

Instances

Eq ImageDimensions Source
Ord ImageDimensions Source
Show ImageDimensions Source
ToJSON ImageDimensions Source

data MimeType Source

Mime types for the display data, with any associated metadata that the mime types may require.

Constructors

MimePlainText	A `text/plain` mimetype for text
MimeHtml	A `text/html` mimetype for HTML
MimePng ImageDimensions	A `image/png` mimetype for PNG images, with associated image width and height
MimeJpg ImageDimensions	A `image/jpg` mimetype for JPG images, with associated image width and height
MimeSvg	A `image/svg+xml` mimetype for SVG images
MimeLatex	A `text/latex` mimetype for LaTeX
MimeJavascript	A `application/javascript` mimetype for Javascript

Instances

Eq MimeType Source
Ord MimeType Source
Show MimeType Source
Generic MimeType Source
type Rep MimeType Source

data ErrorInfo Source

Error information, to be displayed to the user.

Constructors

ErrorInfo
Fields errorName :: Text Name of the error or exception. errorValue :: Text Any values associated with the error or exception. errorTraceback :: [Text] If possible, a traceback for the error or exception.

Instances

Eq ErrorInfo Source
Ord ErrorInfo Source
Show ErrorInfo Source
FromJSON ErrorInfo Source

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.

Instances

Eq WaitBeforeClear Source
Ord WaitBeforeClear Source
Show WaitBeforeClear Source
ToJSON WaitBeforeClear Source
FromJSON WaitBeforeClear Source

data KernelStatus Source

Status of the kernel.

Used with KernelStatusOutput messages to let the frontend know what the kernel is doing.

Constructors

KernelIdle	`idle`: The kernel is available for more processing tasks.
KernelBusy	`busy`: The kernel is currently processing and busy.
KernelStarting	`starting`: The kernel is loading and is not yet available for processing.

Instances

Eq KernelStatus Source
Ord KernelStatus Source
Show KernelStatus Source
ToJSON KernelStatus Source
FromJSON KernelStatus Source

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.

Instances

Eq KernelRequest Source
Ord KernelRequest Source
Show KernelRequest Source
ToJSON KernelRequest Source
IsMessage KernelRequest Source

data InputOptions Source

Metadata for requesting input from the user.

Constructors

InputOptions
Fields inputPrompt :: Text Prompt for the user. inputPassword :: Bool Is this prompt entering a password? On some frontends this will cause

Instances

Eq InputOptions Source
Ord InputOptions Source
Show InputOptions Source

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.

Instances

Eq ClientReply Source
Ord ClientReply Source
Show ClientReply Source
ToJSON ClientReply Source
IsMessage ClientReply Source

Comm Messages (Shell or IOPub channel)

data Comm Source

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 CommOpen message used to request that the receiving end create a comm with the provided UUID and target name.

The TargetName lets the receiving end what sort of comm to create; this can also be refined with an optional TargetModule, which can select the module responsible for creating this comm (for languages or environments in which the idea of a module is meaningful). Although such a distinction is not always meaningful, the TargetModule is often used to select a module (such as a Python module) and the TargetName is often used to select the constructor or function in that module that then creates the comm.

The auxiliary JSON data value can contain any information the client or kernel wishes to include for this comm message.

CommClose UUID Value

A CommClose message destroys a comm, selecting it by its UUID.

The auxiliary JSON data value can contain any information the client or kernel wishes to include for this comm message.

CommMessage UUID Value

A CommMessage message sends some JSON data to a comm, selecting it by its UUID.

Instances

Eq Comm Source
Show Comm Source
ToJSON Comm Source
IsMessage Comm Source

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

Instances

Eq TargetModule Source
Ord TargetModule Source
Show TargetModule Source
ToJSON TargetModule Source
FromJSON TargetModule Source