Message Header#

The messageheader contains information about the message,such as unique identifiers for the originating session and the actual message ID,the type of message, the version of the Jupyter protocol,and the date the message was created.In addition, there is a username field, e.g. for the process that generated themessage, if applicable.This can be useful in collaborative settings where multiple users may beinteracting with the same kernel simultaneously,so that frontends can label the various messages in a meaningful way.

{"msg_id":str,# typically UUID, must be unique per message"session":str,# typically UUID, should be unique per session"username":str,# ISO 8601 timestamp for when the message is created"date":str,# All recognized message type strings are listed below."msg_type":str,# the message protocol version"version":"5.0",# Optional subshell_id"subshell_id":str|None,}

Parent header#

When a message is the “result” of another message,such as a side-effect (output or status) or direct reply,theparent_header is a copy of theheader of the messagethat “caused” the current message._reply messages MUST have aparent_header,and side-effectstypically have a parent.If there is no parent, an empty dict should be used.This parent is used by clients to route message handling to the right place,such as outputs to a cell.

{# parent_header is a copy of the request's header'msg_id':'...',...}

Metadata#

Themetadata dict contains information about the message that is not part of the content.This is not often used, but can be an extra location to store information aboutrequests and replies,such as extensions adding information about request or execution context.

Content#

Thecontent dict is the body of the message.Its structure is dictated by themsg_type field in the header,described in detail for each message below.

Buffers#

Finally, a list of additional binary buffers can be associated with a message.While this is part of the protocol,no official messages make use of these buffers.They are used by extension messages, such as IPython Parallel’sapplyand some of ipywidgets’comm messages.

A full message#

Combining all of these together,a complete message can be represented as the following dictionary of dictionaries (and one list):

{"header":{"msg_id":"...","msg_type":"...",...},"parent_header":{},"metadata":{},"content":{},"buffers":[],}

Request-Reply#

In general, the ROUTER/DEALER sockets follow a request-reply pattern:

The client sends an<action>_request message (such asexecute_request)on its shell (DEALER) socket.The kernel receives that request and immediately publishes astatus:busy message on IOPub.The kernel then processes the request and sends the appropriate<action>_reply message, such asexecute_reply.After processing the request and publishing associated IOPub messages, if any,the kernel publishes astatus:idle message.This idle status message indicates that IOPub messages associated with a givenrequest have all been received.

All reply messages have a'status' field, which will have one of the following values:

• status='ok': The request was processed successfully, and the remainingcontent of the reply is specified in the appropriate section below.

• status='error': The request failed due to an error.

  When status is ‘error’, the usual content of a successful reply should be omitted,instead the following fields should be present:

  {'status':'error','ename':str,# Exception name, as a string'evalue':str,# Exception value, as a string'traceback':list(str),# traceback frames as strings}

• status='abort': This is the same asstatus='error'but with no information about the error.No fields should be present other thatstatus.

As a special case,execute_reply messages (seeExecution results)have anexecution_count field regardless of their status.

Execute#

This message type is used by frontends to ask the kernel to execute code onbehalf of the user, in a namespace reserved to the user’s variables (and thusseparate from the kernel’s own internal code and variables).

Message type:execute_request:

content={# Source code to be executed by the kernel, one or more lines.'code':str,# A boolean flag which, if True, signals the kernel to execute# this code as quietly as possible.# silent=True forces store_history to be False,# and will *not*:#   - broadcast output on the IOPUB channel#   - have an execute_result# The default is False.'silent':bool,# A boolean flag which, if True, signals the kernel to populate history# The default is True if silent is False.  If silent is True, store_history# is forced to be False.'store_history':bool,# A dict mapping names to expressions to be evaluated in the# user's dict. The rich display-data representation of each will be evaluated after execution.# See the display_data content for the structure of the representation data.'user_expressions':dict,# Some frontends do not support stdin requests.# If this is true, code running in the kernel can prompt the user for input# with an input_request message (see below). If it is false, the kernel# should not send these messages.'allow_stdin':True,# A boolean flag, which, if True, aborts the execution queue if an exception is encountered.# If False, queued execute_requests will execute even if this request generates an exception.'stop_on_error':True,}

Thecode field contains a single string (possibly multiline) to be executed.

Theuser_expressions field deserves a detailed explanation. In the past, IPython hadthe notion of a prompt string that allowed arbitrary code to be evaluated, andthis was put to good use by many in creating prompts that displayed systemstatus, path information, and even more esoteric uses like remote instrumentstatus acquired over the network. But now that IPython has a clean separationbetween the kernel and the clients, the kernel has no prompt knowledge; promptsare a frontend feature, and it should be even possible for differentfrontends to display different prompts while interacting with the same kernel.user_expressions can be used to retrieve this information.

Any error in evaluating any expression inuser_expressions will result inonly that key containing a standard error message, of the form:

{'status':'error','ename':'NameError','evalue':'foo','traceback':...}

Upon completion of the execution request, the kernelalways sends a reply,with a status code indicating what happened and additional data depending onthe outcome. Seebelow for the possible returncodes and associated data.

content={# One of: 'ok' OR 'error' OR 'aborted''status':str,# The global kernel counter that increases by one with each request that# stores history.  This will typically be used by clients to display# prompt numbers to the user.  If the request did not store history, this will# be the current value of the counter in the kernel.'execution_count':int,}

{# 'payload' will be a list of payload dicts, and is optional.# payloads are considered deprecated.# The only requirement of each payload dict is that it have a 'source' key,# which is a string classifying the payload (e.g. 'page').'payload':list(dict),# Results for the user_expressions.'user_expressions':dict,}

{"source":"page",# mime-bundle of data to display in the pager.# Must include text/plain."data":mimebundle,# line offset to start from"start":int,}

{"source":"set_next_input",# the text contents of the cell to create"text":"some cell content",# If true, replace the current cell in document UIs instead of inserting# a cell. Ignored in console UIs."replace":bool,}

{"source":"edit_magic","filename":"/path/to/file.py",# the file to edit"line_number":int,# the line number to start with}

{"source":"ask_exit",# whether the kernel should be left running, only closing the client"keepkernel":bool,}

Introspection#

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.

Message type:inspect_request:

content={# The code context in which introspection is requested# this may be up to an entire multiline cell.'code':str,# The cursor position within 'code' (in unicode characters) where inspection is requested'cursor_pos':int,# The level of detail desired.  In IPython, the default (0) is equivalent to typing# 'x?' at the prompt, 1 is equivalent to 'x??'.# The difference is up to kernels, but in IPython level 1 includes the source code# if available.'detail_level':0or1,}

The reply is a mime-bundle, like adisplay_data 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.

Message type:inspect_reply:

content={# 'ok' if the request succeeded or 'error', with error information as in all other replies.'status':'ok',# found should be true if an object was found, false otherwise'found':bool,# data can be empty if nothing is found'data':dict,'metadata':dict,}

Completion#

Message type:complete_request:

content={# The code context in which completion is requested# this may be up to an entire multiline cell, such as# 'foo = a.isal''code':str,# The cursor position within 'code' (in unicode characters) where completion is requested'cursor_pos':int,}

Message type:complete_reply:

content={# status should be 'ok' unless an exception was raised during the request,# in which case it should be 'error', along with the usual error message content# in other messages.'status':'ok'# The list of all matches to the completion request, such as# ['a.isalnum', 'a.isalpha'] for the above example.'matches':list,# The range of text that should be replaced by the above matches when a completion is accepted.# typically cursor_end is the same as cursor_pos in the request.'cursor_start':int,'cursor_end':int,# Information that frontend plugins might use for extra display information about completions.'metadata':dict,}

History#

For clients to explicitly request history from a kernel. The kernel has allthe actual execution history stored in a single location, so clients canrequest it from the kernel when needed.

Message type:history_request:

content={# If True, also return output history in the resulting dict.'output':bool,# If True, return the raw input history, else the transformed input.'raw':bool,# So far, this can be 'range', 'tail' or 'search'.'hist_access_type':str,# If hist_access_type is 'range', get a range of input cells. session# is a number counting up each time the kernel starts; you can give# a positive session number, or a negative number to count back from# the current session.'session':int,# start and stop are line (cell) numbers within that session.'start':int,'stop':int,# If hist_access_type is 'tail' or 'search', get the last n cells.'n':int,# If hist_access_type is 'search', get cells matching the specified glob# pattern (with * and ? as wildcards).'pattern':str,# If hist_access_type is 'search' and unique is true, do not# include duplicated history.  Default is false.'unique':bool,}

Message type:history_reply:

content={# 'ok' if the request succeeded or 'error', with error information as in all other replies.'status':'ok',# A list of 3 tuples, either:# (session, line_number, input) or# (session, line_number, (input, output)),# depending on whether output was False or True, respectively.'history':list,}

Code completeness#

When the user enters a line in a console style interface, the console mustdecide whether to immediately execute the current code, or whether to show acontinuation prompt for further input. For instance, in Pythona=5 wouldbe executed immediately, whileforiinrange(5): would expect further input.

There are four possible replies:

• 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 theerror soonest.

• unknown - if the kernel is not able to determine this. The frontend shouldalso handle the kernel not replying promptly. It may default to sending thecode for execution, or it may implement simple fallback heuristics for whetherto execute the code (e.g. execute after a blank line).

Frontends may have ways to override this, forcing the code to be sent forexecution or forcing a continuation prompt.

Message type:is_complete_request:

content={# The code entered so far as a multiline string'code':str,}

Message type:is_complete_reply:

content={# One of 'complete', 'incomplete', 'invalid', 'unknown''status':str,# If status is 'incomplete', indent should contain the characters to use# to indent the next line. This is only a hint: frontends may ignore it# and use their own autoindentation rules. For other statuses, this# field does not exist.'indent':str,}

Connect#

When a client connects to the request/reply socket of the kernel, it can issuea connect request to get basic information about the kernel, such as the portsthe other ZeroMQ sockets are listening on. This allows clients to only haveto know about a single port (the shell channel) to connect to a kernel.The ports for any additional channels the kernel is listening on should be included in the reply.If any ports are omitted from the reply, this indicates that the channels are not running.

Message type:connect_request:

content={}

For example, a kernel with all channels running:

Message type:connect_reply:

content={'shell_port':int,# The port the shell ROUTER socket is listening on.'iopub_port':int,# The port the PUB socket is listening on.'stdin_port':int,# The port the stdin ROUTER socket is listening on.'hb_port':int,# The port the heartbeat socket is listening on.'control_port':int,# The port the control ROUTER socket is listening on.}

Comm info#

When a client needs the currently open comms in the kernel, it can issue arequest for the currently open comms. When the optionaltarget_name isspecified, the reply only contains the currently open comms for the target.

Message type:comm_info_request:

content={# Optional, the target name'target_name':str,}

Message type:comm_info_reply:

content={# 'ok' if the request succeeded or 'error', with error information as in all other replies.'status':'ok',# A dictionary of the comms, indexed by UUIDs.'comms':{comm_id:{'target_name':str,},},}

Kernel info#

If a client needs to know information about the kernel, it canmake a request of the kernel’s information.This message can be used to fetch core information of thekernel, including language (e.g., Python), language version number andIPython version number, and the IPython message spec version number.

Message type:kernel_info_request:

content={}

Message type:kernel_info_reply:

content={# 'ok' if the request succeeded or 'error', with error information as in all other replies.'status':'ok',# Version of messaging protocol.# 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.'protocol_version':'X.Y.Z',# The kernel implementation name# (e.g. 'ipython' for the IPython kernel)'implementation':str,# Implementation version number.# The version number of the kernel's implementation# (e.g. IPython.__version__ for the IPython kernel)'implementation_version':'X.Y.Z',# Information about the language of code for the kernel'language_info':{# Name of the programming language that the kernel implements.# Kernel included in IPython returns 'python'.'name':str,# Language version number.# It is Python version number (e.g., '2.7.3') for the kernel# included in IPython.'version':'X.Y.Z',# mimetype for script files in this language'mimetype':str,# Extension including the dot, e.g. '.py''file_extension':str,# Pygments lexer, for highlighting# Only needed if it differs from the 'name' field.'pygments_lexer':str,# Codemirror mode, for highlighting in the notebook.# Only needed if it differs from the 'name' field.'codemirror_mode':strordict,# Nbconvert exporter, if notebooks written with this kernel should# be exported with something other than the general 'script'# exporter.'nbconvert_exporter':str,},# A banner of information about the kernel,# which may be displayed in console environments.'banner':str,# A boolean flag which tells if the kernel supports debugging in the notebook.# Default is False.# Deprecated as replaced by 'supported_features'=['debugger'] (see below).'debugger':bool,# Optional: A list of dictionaries, each with keys 'text' and 'url'.# These will be displayed in the help menu in the notebook UI.'help_links':[{'text':str,'url':str}],# Optional: A list of optional features such as 'debugger' and# 'kernel subshells'. Introduced by Jupyter Enhancement Proposal 92# https://github.com/jupyter/enhancement-proposals/pull/92'supported_features':[str]}

Refer to the lists of availablePygments lexersandcodemirror modes for those fields.

Kernel shutdown#

The clients can request the kernel to shut itself down; this is used inmultiple cases:

• when the user chooses to close the client application via a menu or windowcontrol.

• when the user types ‘exit’ or ‘quit’ (or their uppercase magic equivalents).

• when the user chooses a GUI method (like the ‘Ctrl-C’ shortcut in theIPythonQt client) to force a kernel restart to get a clean kernel withoutlosing client-side state like history or inlined figures.

Implementation recommendation for starting kernels: A restart should optimallypreserve as many resources outside the kernel as possible (e.g. only restart thekernel and its subprocesses and not any parent processes). That is, ideally arestart should be “in-place”. For local kernels, there is typically no parentprocess so a “hard” restart and an in-place restart are identical whereas forremote kernels this is not generally the same. As an example, if a remote kernelis run in a container, during an in-place restart the container may be keptrunning and a new kernel process within it would be started.

The client sends a shutdown request to the kernel, and once it receives thereply message (which is otherwise empty), it can assume that the kernel hascompleted shutdown safely. The request is sent on thecontrol channel.

Upon their own shutdown, client applications will typically execute a lastminute sanity check and forcefully terminate any kernel that is still alive, toavoid leaving stray processes in the user’s machine.

Message type:shutdown_request:

content={'restart':bool# False if final shutdown, or True if shutdown precedes a restart}

Message type:shutdown_reply:

content={# 'ok' if the request succeeded or 'error', with error information as in all other replies.'status':'ok','restart':bool# False if final shutdown, or True if shutdown precedes a restart}

Kernel interrupt#

In case a kernel can not catch operating system interrupt signals (e.g. the usedruntime handles signals and does not allow a user program to define a callback),a kernel can choose to be notified using a message instead. For this to work,the kernels kernelspec must setinterrupt_mode tomessage. An interruptionwill then result in the following message on thecontrol channel:

Message type:interrupt_request:

content={}

Message type:interrupt_reply:

content={# 'ok' if the request succeeded or 'error', with error information as in all other replies.'status':'ok'}

Debug request#

This message type is used with debugging kernels to request specific actionsto be performed by the debugger such as adding a breakpoint or stepping intoa code.

Message type:debug_request:

content={}

Message type:debug_reply:

content={}

Thecontent dicts of thedebug_request anddebug_reply messages respectively follow thespecification of theRequest andResponse messages from theDebug Adapter Protocol (DAP) as of version 1.39 or later.

Debug requests and replies are sent over thecontrol channel to preventqueuing behind execution requests.

Kernel subshells#

Kernel subshells are separate threads of execution within the same kernel process thatwere introduced byJupyter Enhancement Proposal 91.Kernels supporting subshells must include'kernelsubshells' in'supported_features'inkernel info reply messages.

content={}

content={# 'ok' if the request succeeded or 'error', with error information as in all other replies.'status':'ok',# The ID of the subshell, unique within the kernel.'subshell_id':str,}

content={# The ID of the subshell.'subshell_id':str}

content={# 'ok' if the request succeeded or 'error', with error information as in all other replies.'status':'ok',}

content={}

content={# 'ok' if the request succeeded or 'error', with error information as in all other replies.'status':'ok',# A list of subshell IDs.'subshell_id':[str]}

Streams (stdout, stderr, etc)#

Message type:stream:

content={# The name of the stream is one of 'stdout', 'stderr''name':str,# The text is an arbitrary string to be written to that stream'text':str,}

Display Data#

This type of message is used to bring back data that should be displayed (text,html, svg, etc.) in the frontends. This data is published to all frontends.Each message can have multiple representations of the data; it is up to thefrontend to decide which to use and how. A single message should contain allpossible representations of the same information. Each representation shouldbe a JSON’able data structure, and should be a valid MIME type.

Some questions remain about this design:

• Do we use this message type for execute_result/displayhook? Probably not, becausethe displayhook also has to handle the Out prompt display. On the other handwe could put that information into the metadata section.

Message type:display_data:

content={# Who create the data# Used in V4. Removed in V5.# 'source' : str,# The data dict contains key/value pairs, where the keys are MIME# types and the values are the raw data of the representation in that# format.'data':dict,# Any metadata that describes the data'metadata':dict,# Optional transient data introduced in 5.1. Information not to be# persisted to a notebook or other documents. Intended to live only# during a live kernel session.'transient':dict,}

Themetadata contains any metadata that describes the output.Global keys are assumed to apply to the output as a whole.Themetadata dict can also contain mime-type keys, which will be sub-dictionaries,which are interpreted as applying only to output of that type.Third parties should put any data they write into a single dictwith a reasonably unique name to avoid conflicts.

The only metadata keys currently defined in IPython are the width and heightof images:

metadata={'image/png':{'width':640,'height':480}}

and expanded for JSON data:

metadata={'application/json':{'expanded':True}}

Thetransient dict contains runtime metadata that should not be persisted todocument formats and is fully optional. The only transient key currently defined in Jupyter isdisplay_id:

transient={'display_id':'abcd'}

Update Display Data#

Displays can now be named with adisplay_id within thetransient field ofdisplay_data orexecute_result.

When adisplay_id is specified for a display, it can be updated laterwith anupdate_display_data message. This message has the same format asdisplay_datamessages and must contain atransient field with adisplay_id.

Message type:update_display_data:

content={# The data dict contains key/value pairs, where the keys are MIME# types and the values are the raw data of the representation in that# format.'data':dict,# Any metadata that describes the data'metadata':dict,# Any information not to be persisted to a notebook or other environment# Intended to live only during a kernel session'transient':dict,}

Frontends can choose how they update prior outputs (or if they regard this as aregulardisplay_data message). Within the jupyter andnteract notebooks,all displays that match thedisplay_id are updated (even if there are multiple).

Code inputs#

To let all frontends know what code is being executed at any given time, thesemessages contain a re-broadcast of thecode portion of anexecute_request, along with theexecution_count.

Message type:execute_input:

content={'code':str,# Source code to be executed, one or more lines# The counter for this execution is also provided so that clients can# display it, since IPython automatically creates variables called _iN# (for input prompt In[N]).'execution_count':int}

Execution results#

Results of an execution are published as anexecute_result.These are identical todisplay_data messages, with the addition of anexecution_count key.

Results can have multiple simultaneous formats depending on itsconfiguration. A plain text representation should always be providedin thetext/plain mime-type. Frontends are free to display any or all of theseaccording to its capabilities.Frontends should ignore mime-types they do not understand. The data itself isany JSON object and depends on the format. It is often, but not always a string.

Message type:execute_result:

content={# The counter for this execution is also provided so that clients can# display it, since IPython automatically creates variables called _N# (for prompt N).'execution_count':int,# data and metadata are identical to a display_data message.# the object being displayed is that passed to the display hook,# i.e. the *result* of the execution.'data':dict,'metadata':dict,}

Execution errors#

When an error occurs during code execution

Message type:error:

content={# Similar content to the execute_reply messages for the 'error' case,# except the 'status' and 'execution_count' fields are omitted.}

Kernel status#

This message type is used by frontends to monitor the status of the kernel.

Message type:status:

content={# When the kernel starts to handle a message, it will enter the 'busy'# state and when it finishes, it will enter the 'idle' state.# The kernel will publish state 'starting' exactly once at process startup.execution_state:('busy','idle','starting')}

When a kernel receives a request and begins processing it,the kernel shall immediately publish a status message withexecution_state:'busy'.When that kernel has completed processing the requestand has finished publishing associated IOPub messages, if any,it shall publish a status message withexecution_state:'idle'.Thus, the outputs associated with a given execution shall generally arrivebetween the busy and idle status messages associated with a given request.

Clear output#

This message type is used to clear the output that is visible on the frontend.

Message type:clear_output:

content={# Wait to clear the output until new output is available.  Clears the# existing output immediately before the new output is displayed.# Useful for creating simple animations with minimal flickering.'wait':bool,}

Debug event#

This message type is used by debugging kernels to send debugging events to thefrontend.

Message type:debug_event:

content={}

Thecontent dict follows the specification of theEvent message from theDebug Adapter Protocol (DAP).

Opening a Comm#

Opening a Comm produces acomm_open message, to be sent to the other side:

{'comm_id':'u-u-i-d','target_name':'my_comm','data':{}}

Every Comm has an ID and a target name.The code handling the message on the receiving side is responsible for maintaining a mappingof target_name keys to constructors.After acomm_open message has been sent,there should be a corresponding Comm instance on both sides.Thedata key is always a dict and can be any extra JSON information used ininitialization of the comm.

If thetarget_name key is not found on the receiving side,then it should immediately reply with acomm_close message to avoid an inconsistent state.

Comm Messages#

Comm messages are one-way communications to update comm state,used for synchronizing widget state, or simply requesting actions of a comm’s counterpart.

Essentially, each comm pair defines their own message specification implementedinside thedata dict.

There are no expected replies (of course, one side can send anothercomm_msg in reply).

Message type:comm_msg:

{'comm_id':'u-u-i-d','data':{}}

Tearing Down Comms#

Since comms live on both sides, when a comm is destroyed the other side must be notified.This is done with acomm_close message.

Message type:comm_close:

{'comm_id':'u-u-i-d','data':{}}

Output Side Effects#

Since comm messages can execute arbitrary user code,handlers should set the parent header and publish status busy / idle,just like an execute request.

5.5 (draft)#

• Addeddebug_request/reply messages

• Addeddebug_event message

• Addedsupported_features inkernel info reply messages.

• Deprecateddebugger inkernel info reply messages asreplaced withsupported_features.

• Addedcreate_subshell,delete_subshell andlist_subshell messages.

5.4#

• Sending ashutdown_request message on theshell channel is deprecated.It should be sent on the control channel.

5.3#

• Kernels can now opt to be interrupted by a message sent on the control channelinstead of a system signal. SeeKernel specs andKernel interrupt.

5.2#

• Resolve ambiguity ofcursor_pos field in the presenceof unicode surrogate pairs.In 5.2, cursor_posmust be the actual encoding-independent offset in unicode codepoints.

  See also

  cursor_pos and unicode offsets

5.1#

• date in the header was accidentally omitted from the spec prior to 5.1,but it has always been in the canonical implementation,so implementers are strongly encouraged to include it.It is mandatory in 5.1.

• status='abort' in replies has not proved useful, and is considered deprecated.Kernels should sendstatus='error' instead.

• comm_info_request/reply added

• connect_request/reply have not proved useful, and are considered deprecated.Kernels are not expected to implement handlers for this message.

• newtransient field indisplay_data

• newupdate_display_data message

5.0#

General changes:

• version key added to message headers

• busy and idle status messages should be sent before/after handling every request,not just execution

Message renames to remove Python-specific-ness:

• pyin message renamed toexecute_input

• pyerr renamed toerror

• object_info_request/reply messages renamed toinspect_request/reply

Kernel info:

• versions changed from lists of integers to strings

• ipython_version is removed

• language_info,implementation,implementation_version,banner

  andhelp_links keys are added.

• language_version is moved tolanguage_info.version

• language is moved tolanguage_info.name

Execution:

• user_variables is removed fromexecute_request/reply because it isredundant withuser_expressions

• password key added toinput_request

Output:

• data key in stream messages renamed totext for consistency with thenotebook format.

• application/json in mimebundles should be unpacked JSON data,not a double-serialized JSON string.

Inspection:

• name key ininspect_request replaced withcode andcursor_pos,moving the lexing responsibility to the kernel.

• object_info_reply is now a mimebundle,allowing formatting decisions to be made by the kernel.

Completion:

• complete_request:line,block, andtext keys are removed in

  favor of a singlecode for context.Lexing is up to the kernel.

• complete_reply:

  • matched_text is removed in favor ofcursor_start andcursor_end.

  • metadata is added for extended information.

• newis_complete_request andis_complete_reply messages

4.1#

• comm_open/close/msg messages added

• clear_output:stdout,stderr, anddisplay boolean keys forselective clearing are removed,andwait is added.The selective clearing keys are ignored in v4 and the default behavior remains the same,so v4clear_output messages will be safely handled by a v4.1 frontend.

cursor_pos and unicode offsets#

Many frontends, especially those implemented in javascript,reported cursor_pos as the interpreter’s string index,which is not the same as the unicode character offset if the interpreter usesUTF-16 (e.g. javascript or Python 2 on macOS),which stores “astral-plane” characters such as𝐚(U+1D41A) as surrogate pairs,taking up two indices instead of one, causing a unicode offsetdrift of one per astral-plane character.Not all frontends have this behavior, however,and after JSON serialization information about which encoding was usedwhen calculating the offset is lost,so assumingcursor_pos is calculated in UTF-16 could result in a similarly incorrect offsetfor frontends that did the right thing.

For this reason, in protocol versions prior to 5.2,cursor_posis officially ambiguous in the presence of astral plane unicode characters.Frontends claiming to implement protocol 5.2MUST identify cursor_pos asthe encoding-independent unicode character offset.Kernels may choose to expect the UTF-16 offset from requests implementingprotocol 5.1 and earlier, in order to behave correctly with the most popularfrontends.But they should know that doing sointroduces the inverse bug for thefrontends that do not have this bug.

As an example, use a python3 kernel and evaluate𨭎𨭎𨭎𨭎𨭎=10. Then type𨭎𨭎 followed by the tab key and see if it properly completes.

Known affected frontends (as of 2017-06):

• Jupyter Notebook < 5.1

• JupyterLab < 0.24

• nteract < 0.2.0

• Jupyter Console and QtConsole with Python 2 on macOS and Windows

Knownnot affected frontends:

• QtConsole, Jupyter Console with Python 3 or Python 2 on Linux, CoCalc