Internals

init(args, kernel)

Initialize a kernel. args may either be empty or have one element containing the path to an existing connection file. If args is empty a connection file will be generated.

IPython message struct.

msg_header(m::Msg, msg_type::String)

Create a header for a Msg.

send_ipython(socket, kernel, m::Msg)

Send a message m. This will lock socket.

recv_ipython(socket, kernel)

Wait for and get a message. This will lock socket.

Jupyter associates cells with message headers. Once a cell's execution state has been set as to idle, it will silently drop stream messages (i.e. output to stdout and stderr) - see https://github.com/jupyter/notebook/issues/518. When using Interact, and a widget's state changes, a new message header is sent to the IJulia kernel, and while Reactive is updating Signal graph state, it's execution state is busy, meaning Jupyter will not drop stream messages if Interact can set the header message under which the stream messages will be sent. Hence the need for this function.

send_status(state::AbstractString, kernel, parent_msg::Msg=execute_msg)

Publish a status message.

connect_request(socket, kernel, msg)

Handle a connect request.

execute_request(socket, kernel, msg)

Handle a execute request. This will execute Julia code, along with Pkg and shell commands.

shutdown_request(socket, kernel, msg)

Handle a shutdown request. After sending the reply this will exit the process.

interrupt_request(socket, kernel, msg)

Handle a interrupt request. This will throw an InterruptException to the currently executing request handler.

inspect_request(socket, kernel, msg)

Handle a introspection request.

history_request(socket, kernel, msg)

Handle a history request. This is currently only a dummy implementation that doesn't actually do anything.

complete_request(socket, kernel, msg)

Handle a completion request.

kernel_info_request(socket, kernel, msg)

Handle a kernel info request.

is_complete_request(socket, kernel, msg)

Handle a completeness request.

eventloop(socket, kernel)

Generic event loop for one of the kernel sockets.

waitloop(kernel)

Main loop of a kernel. Runs the event loops for the control and shell sockets (note: in IJulia the shell socket is called requests).

Wrapper type around redirected stdio streams, both for overloading things like flush and so that we can set properties like color.

watch_stream(rd::IO, name::AbstractString)

Continually read from (size limited) Libuv/OS buffer into an IObuffer to avoid problems when the Libuv/OS buffer gets full (https://github.com/JuliaLang/julia/issues/8789). Send data immediately when buffer contains more than max_bytes bytes. Otherwise, if data is available it will be sent every stream_interval seconds (see the Timer's set up in watch_stdio). Truncate the output to max_output_per_request bytes per execution request since excessive output can bring browsers to a grinding halt.

Struct to dispatch on for inline display.

InlineIOContext(io, KVs::Pair...)

Create an IOContext for inline display.

Supported MIME types for inline display in IPython, in descending order of preference (descending "richness").

A vector of MIME types (or vectors of MIME types) that IJulia will try to render. IJulia will try to render every MIME type specified in the first level of the vector. If a vector of MIME types is specified, IJulia will include only the first MIME type that is renderable (this allows for the expression of priority and exclusion of redundant data).

For example, since "text/plain" is specified as a first-child of the array, IJulia will always try to include a "text/plain" representation of anything that is displayed. Since markdown and html are specified within a sub-vector, IJulia will always try to render "text/markdown", and will only try to render "text/html" if markdown isn't possible.

MIME types that when rendered (via stringmime) return JSON data. See ijulia_mime_types for a description of how MIME types are selected.

This is necessary to embed the JSON as is in the displaydata bundle (rather than as stringify'd JSON).

limitstringmime(mime::MIME, x, forcetext=false)

Convert x to a string of type mime, making sure to use an IOContext that tells the underlying show function to limit output.

Need special handling for showing a string as a textmime type, since in that case the string is assumed to be raw data unless it is text/plain.

Generate a dictionary of mime_type => data pairs for all registered MIME types. This is the format that Jupyter expects in display_data and execute_result messages.

Generate the preferred json-MIME representation of x.

Returns a tuple with the selected MIME type and the representation of the data using that MIME type (as a JSONText).

Generate the preferred MIME representation of x.

Returns a tuple with the selected MIME type and the representation of the data using that MIME type.

register_mime(x::Union{MIME, Vector{MIME}})
register_mime(x::AbstractVector{<:MIME})

Register a new MIME type.

register_jsonmime(x::Union{MIME, Vector{MIME}})
register_jsonmime(x::AbstractVector{<:MIME})

Register a new JSON MIME type.

find_jupyter_subcommand(subcommand::AbstractString, port::Union{Nothing,Int}=nothing)

Return a Cmd for the program subcommand. If the program is jupyter or jupyterlab it may prompt the user to install it.

launch(cmd, dir, detached, verbose)

Run cmd in dir. If detached is false it will not wait for the command to finish. If verbose is true then the stdout/stderr from the cmd process will be echoed to stdout/stderr.

set_verbose(v=true)

This function enables (or disables, for set_verbose(false)) verbose output from the IJulia kernel, when called within a running notebook. This consists of log messages printed to the terminal window where jupyter was launched, displaying information about every message sent or received by the kernel. Used for debugging IJulia.

If d ends with an incomplete UTF8-encoded character, return the number of trailing incomplete bytes. Otherwise, return 0.

get_token(code, pos)

Given a string and a cursor position, find substring to request help on by:

1. Searching backwards for the closest token (may be invalid)
2. Keep searching backwards until we find an token before an unbalanced '(' a. If (1) is not valid, store the first valid token b. We assume a token before an unbalanced '(' is a function
3. If we find a possible function token, return this token.
4. Otherwise, return the last valid token

Important Note

Tokens are chosen following several empirical observations instead of rigorous rules. We assume that the first valid token before left-imbalanced (more '(' than ')') parentheses is the function "closest" to cursor. The following examples use '|' to denote cursor, showing observations on parentheses.

• f()| has balanced parentheses with nothing within, thus f is the desired token.
• f(|) has imbalanced parentheses, thus f is the desired token.
• f(x|, y) gives tokens x and f. x has balanced parentheses, while f is left-imbalanced. f is desired.
• f(x)| returns f
• f(x, y)| returns f.
• f((x|)) returns f, as expected
• f(x, (|y)) returns f. This is a hack, as I deduct crossed_parentheses whenever a separator is encountered, clamped to 0! Otherwise, x would be returned.
• f(x, (y|)), f(x, (y)|), and f(x, (y))| all behave as above. Arbitrary nesting of tuples should not cause misbehavior.
• expr1 ; expr2, cursor in expr2 never causes search in expr1

TODO: detect operators? More robust parsing using the Julia parser instead of string hacks?

get_previous_token(code, pos, crossed_parentheses)

Given a string and a cursor position, find substring corresponding to previous token. crossed_parentheses:Int keeps track of how many parentheses have been crossed. A pair of parentheses yields 0 crossing; a '(' add 1; a ')' subtracts 1.

Returns (startpos, endpos, crossed_parentheses, stop)

• startpos is the start position of the closest potential token before pos.
• endpos is end position if said token is can be valid identifier, or -1 otherwise
• crossed_parentheses is the new count for parentheses.
• stop is true if ';' is hit, denoting the beginning of a clause.