@nteract/messaging
Version:
Messaging mechanics for nteract apps (jupyter spec)
261 lines • 7.99 kB
JavaScript
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.inputReply = exports.shutdownRequest = exports.kernelInfoRequest = exports.executeInput = exports.clearOutput = exports.status = exports.executeReply = exports.stream = exports.error = exports.executeResult = exports.updateDisplayData = exports.displayData = exports.executeRequest = exports.message = void 0;
const uuid_1 = require("uuid");
/**
* Returns which channel, iopub or stdin or shell, to send a kernel message
* through.
*
* @param messageType The message type to fetch a channel for
*
* @returns The channel to send a kernel message through
*/
function whichChannel(messageType) {
switch (messageType) {
case "execute_request":
case "inspect_request":
case "kernel_info_request":
case "complete_request":
case "history_request":
case "is_complete_request":
case "comm_info_request":
case "shutdown_request":
return "shell";
case "display_data":
case "stream":
case "update_display_data":
case "execute_input":
case "execute_result":
case "error":
case "status":
case "clear_output":
return "iopub";
case "input_request":
case "input_reply":
return "stdin";
default:
// We fallthrough to handle the comm messages separately as well as
// unknown message types
break;
}
// NOTE: The Kernel listens for COMM messages on the Shell channel,
// and the Frontend listens for them on the IOPub channel.
// HACK: Since nteract is only frontends at the moment, no kernels implemented
// we simply assume this is destined for a frontend. Revisit as needed.
if (messageType === "comm_open" ||
messageType === "comm_msg" ||
messageType === "comm_close") {
return "shell";
}
// Likely safe to assume the message goes on shell
// the developer can override this otherwise
return "shell";
}
/**
* Returns a fully-formatted kernel message.
*
* @param header An object containing the message type and session information
* @param content The message type-specific contents to send in the kernel message
*
* @returns The fully-formatted kernel message
*/
function message(header, content = {}) {
const channel = whichChannel(header.msg_type);
return {
header: {
msg_id: uuid_1.v4(),
date: new Date().toISOString(),
version: "5.2",
// These fields _should_ get overridden by those provided in `header`
// We supply them as a fallback here
username: header.username || "nteract",
msg_type: header.msg_type,
session: header.session || uuid_1.v4()
},
metadata: {},
parent_header: {},
content,
channel,
buffers: []
};
}
exports.message = message;
/**
* Creates a header for a kernel message of a given type.
*
* @param msg_type The message type to create a header for
*
* @returns A complete header for the message
*/
function createHeader(msg_type) {
return {
msg_id: uuid_1.v4(),
date: new Date().toISOString(),
version: "5.2",
msg_type,
// These fields get overridden by enchannel implementations, we supply them
// as a fallback here
username: "nteract",
session: uuid_1.v4()
};
}
/**
* An execute request creator
*
* > executeRequest('print("hey")', { 'silent': true })
* { header:
* { msg_id: 'f344cc6b-4308-4405-a8e8-a166b0345579',
* date: 2017-10-23T22:33:39.970Z,
* version: '5.0',
* msg_type: 'execute_request',
* username: 'kyle',
* session: '123' },
* metadata: {},
* parent_header: {},
* content:
* { code: 'print("hey")',
* silent: false,
* store_history: true,
* user_expressions: {},
* allow_stdin: true,
* stop_on_error: false } }
*
* @param code The code to execute
* @param options The options for the execute request
*
* @returns A complete execute_request message
*/
function executeRequest(code = "", options = {}) {
const channel = whichChannel("execute_request");
return {
header: createHeader("execute_request"),
metadata: {},
parent_header: {},
content: Object.assign({ code, silent: false, store_history: true, user_expressions: {}, allow_stdin: true, stop_on_error: false }, options),
channel,
buffers: []
};
}
exports.executeRequest = executeRequest;
// The actual displayData function; generics should infer correctly, based on
// the overloads above.
function displayData(content, msg_type) {
if (msg_type === undefined) {
msg_type = "display_data";
}
return message({
msg_type
}, Object.assign({ data: {}, metadata: {}, transient: {} }, content));
}
exports.displayData = displayData;
/**
* Creates an update_display_data message.
*
* http://jupyter-client.readthedocs.io/en/stable/messaging.html#update-display-data
*/
function updateDisplayData(content) {
// TODO: Enforce the transient display_id here?
return displayData(content, "update_display_data");
}
exports.updateDisplayData = updateDisplayData;
/**
* Creates a message containing information about the result of an execution.
*
* http://jupyter-client.readthedocs.io/en/stable/messaging.html#id6
*/
function executeResult(content) {
// TODO: Enforce the transient display_id here?
const m = displayData(content, "execute_result");
m.content.execution_count = content.execution_count;
return m;
}
exports.executeResult = executeResult;
/**
* Creates an error message to indicate when an exception has occurred during
* code execution.
*
* http://jupyter-client.readthedocs.io/en/stable/messaging.html#execution-errors
*/
function error(content) {
return message({
msg_type: "error"
}, Object.assign({ ename: "", evalue: "", traceback: [] }, content));
}
exports.error = error;
/**
* Creates a stream message.
*
* http://jupyter-client.readthedocs.io/en/stable/messaging.html#streams-stdout-stderr-etc
*
* @param content The message type and its contents.
*/
function stream(content) {
return message({
msg_type: "stream"
}, content);
}
exports.stream = stream;
function executeReply(content) {
return message({
msg_type: "execute_reply"
}, content);
}
exports.executeReply = executeReply;
/**
* Creates a status message published by the kernel to indicate its state.
*
* @param execution_state The kernel's execution state
*/
function status(execution_state) {
return message({
msg_type: "status"
}, {
execution_state
});
}
exports.status = status;
/**
*
* @param content
*/
function clearOutput(content) {
return message({
msg_type: "clear_output"
}, content);
}
exports.clearOutput = clearOutput;
/**
*
* @param content
*/
function executeInput(content) {
return message({
msg_type: "execute_input"
}, content);
}
exports.executeInput = executeInput;
/**
* Creates a message to request information about a kernel.
*
* @returns A kernel_info_request message
*/
function kernelInfoRequest() {
return message({ msg_type: "kernel_info_request" });
}
exports.kernelInfoRequest = kernelInfoRequest;
/**
* Creates a message to request the shutdown of a kernel.
*
* @param content An options object containing whether or not to restart the kernel
*
* @returns A shutdown_request message
*/
function shutdownRequest(content = { restart: false }) {
return message({ msg_type: "shutdown_request" }, content);
}
exports.shutdownRequest = shutdownRequest;
function inputReply(content) {
return message({ msg_type: "input_reply" }, content);
}
exports.inputReply = inputReply;
//# sourceMappingURL=messages.js.map