Jupyter.Messages.Internal

This module contains type and class definitions pertaining to handling Jupyter messages internally. The types defined here are generally useful for the jupyter library but will not be useful for users of the library.

Message Metadata

data MessageHeader

A message header with some metadata.

The metadata has a variety of important information that pertains to the session maintained between the client and the frontend. In addition to metadata, the message headers are used to establish relationships between the messages: in particular, the message parent is used to determine which request a reply corresponds to.

In addition, the message type is sent as a string with the message header.

For more information about the message headers, read the section of the Jupyter messaging protocol about the wire protocol.

Constructors

MessageHeader

Fields

messageIdentifiers :: [ByteString]

The identifiers sent with the message. These identifiers come at the front of the message, and are ZeroMQ routing prefix, which can be zero or more socket identities. These are used, for instance, to know where to send stdin requests (see the messaging spec).

messageParent :: Maybe MessageHeader

The parent header, if present. The parent header is used to establish relationships between request and reply messages and outputs published in response to requests.

messageMetadata :: Object

A free-form dict of metadata.

messageId :: UUID

A unique message UUID.

messageSession :: UUID

A unique session UUID.

messageUsername :: Username

The user who sent this message.

messageType :: MessageType

The type of this message. This is stored as a string, and determines how to parse the content and what to do with the message once it is parsed.

Instances

Eq MessageHeader

Show MessageHeader

newtype Username

A username represented as Text, part of the MessageHeader.

Constructors

Username Text

Instances

Eq Username

Ord Username

Show Username

IsString Username

ToJSON Username

FromJSON Username

newtype MessageType

The type of a message, internally stored as a string.

Examples include execute_request, comm_open, and display_data.

Constructors

MessageType

Fields

messageTypeText :: Text

Instances

Eq MessageType

Ord MessageType

Show MessageType

IsString MessageType

ToJSON MessageType

FromJSON MessageType

class ToJSON v => IsMessage v where

Jupyter messages are represented as a variety of datatypes, depending on where in the messaging protocol the message is used (for instance, ClientRequest or Comm).

Given any message, however, you need to be able to get a MessageType for it, so that when encoding the message onto the wire you can include the message type in the header. The IsMessage typeclass provides a single method, getMessageType, which gets the message type of any Jupyter message.

Methods

getMessageType :: v -> MessageType

Get the message type for a Jupyter message.

parseMessageContent :: MessageType -> Maybe (Object -> Parser v)

Get a parser for this message type.

If this message type does not correspond to one of the constructors for the data type v, then return Nothing. Otherwise, return a parser that parses the message body into the given datatype.

This is a slightly unusual but necessary interface, because the message type and the message body come in separate bytestrings, as they are separate blobs sent on the communication sockets. Thus, we must look first at the message type, and choose the JSON parser based on the message type.

Instances

IsMessage Comm

IsMessage KernelOutput

IsMessage ClientReply

IsMessage KernelRequest

IsMessage KernelReply

IsMessage ClientRequest

(IsMessage v1, IsMessage v2) => IsMessage (Either v1 v2)

Provide an IsMessage instance for the sum of two types which have IsMessage instances.

This is particularly useful for dealing with the shell and iopub socket, where kernels and clients can receive different types of messages on one socket (kernels can receive Comm and ClientRequest messages on the shell socket, while clients can receive KernelOutput and Comm messages on the iopub socket).