<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Messaging in IPython — IPython 2.3.0 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '2.3.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="top" title="IPython 2.3.0 documentation" href="../index.html" />
<link rel="up" title="IPython developer’s guide" href="index.html" />
<link rel="next" title="Messaging for Parallel Computing" href="parallel_messages.html" />
<link rel="prev" title="IPython developer’s guide" href="index.html" />
</head>
<body>
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<a href="http://ipython.org/"><img src="../_static/logo.png" border="0" alt="IPython Documentation"/></a>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="parallel_messages.html" title="Messaging for Parallel Computing"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="IPython developer’s guide"
accesskey="P">previous</a> |</li>
<li><a href="http://ipython.org">home</a>| </li>
<li><a href="../search.html">search</a>| </li>
<li><a href="../index.html">documentation </a> »</li>
<li><a href="index.html" accesskey="U">IPython developer’s guide</a> »</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Messaging in IPython</a><ul>
<li><a class="reference internal" href="#versioning">Versioning</a></li>
<li><a class="reference internal" href="#introduction">Introduction</a></li>
<li><a class="reference internal" href="#general-message-format">General Message Format</a></li>
<li><a class="reference internal" href="#the-wire-protocol">The Wire Protocol</a></li>
<li><a class="reference internal" href="#python-functional-api">Python functional API</a></li>
<li><a class="reference internal" href="#messages-on-the-shell-router-dealer-sockets">Messages on the shell ROUTER/DEALER sockets</a><ul>
<li><a class="reference internal" href="#execute">Execute</a><ul>
<li><a class="reference internal" href="#execution-semantics">Execution semantics</a></li>
<li><a class="reference internal" href="#execution-counter-old-prompt-number">Execution counter (old prompt number)</a></li>
<li><a class="reference internal" href="#execution-results">Execution results</a></li>
</ul>
</li>
<li><a class="reference internal" href="#object-information">Object information</a></li>
<li><a class="reference internal" href="#complete">Complete</a></li>
<li><a class="reference internal" href="#history">History</a></li>
<li><a class="reference internal" href="#connect">Connect</a></li>
<li><a class="reference internal" href="#kernel-info">Kernel info</a></li>
<li><a class="reference internal" href="#kernel-shutdown">Kernel shutdown</a></li>
</ul>
</li>
<li><a class="reference internal" href="#messages-on-the-pub-sub-socket">Messages on the PUB/SUB socket</a><ul>
<li><a class="reference internal" href="#streams-stdout-stderr-etc">Streams (stdout, stderr, etc)</a></li>
<li><a class="reference internal" href="#display-data">Display Data</a></li>
<li><a class="reference internal" href="#raw-data-publication">Raw Data Publication</a></li>
<li><a class="reference internal" href="#python-inputs">Python inputs</a></li>
<li><a class="reference internal" href="#python-outputs">Python outputs</a></li>
<li><a class="reference internal" href="#python-errors">Python errors</a></li>
<li><a class="reference internal" href="#kernel-status">Kernel status</a></li>
<li><a class="reference internal" href="#clear-output">Clear output</a></li>
</ul>
</li>
<li><a class="reference internal" href="#messages-on-the-stdin-router-dealer-sockets">Messages on the stdin ROUTER/DEALER sockets</a></li>
<li><a class="reference internal" href="#heartbeat-for-kernels">Heartbeat for kernels</a></li>
<li><a class="reference internal" href="#custom-messages">Custom Messages</a><ul>
<li><a class="reference internal" href="#opening-a-comm">Opening a Comm</a></li>
<li><a class="reference internal" href="#comm-messages">Comm Messages</a></li>
<li><a class="reference internal" href="#tearing-down-comms">Tearing Down Comms</a></li>
<li><a class="reference internal" href="#output-side-effects">Output Side Effects</a></li>
</ul>
</li>
<li><a class="reference internal" href="#todo">ToDo</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">IPython developer’s guide</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="parallel_messages.html"
title="next chapter">Messaging for Parallel Computing</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/development/messaging.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="messaging-in-ipython">
<span id="messaging"></span><h1>Messaging in IPython<a class="headerlink" href="#messaging-in-ipython" title="Permalink to this headline">¶</a></h1>
<div class="section" id="versioning">
<h2>Versioning<a class="headerlink" href="#versioning" title="Permalink to this headline">¶</a></h2>
<p>The IPython message specification is versioned independently of IPython.
The current version of the specification is 4.1.</p>
</div>
<div class="section" id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>This document explains the basic communications design and messaging
specification for how the various IPython objects interact over a network
transport. The current implementation uses the <a class="reference external" href="http://zeromq.org">ZeroMQ</a> library for messaging
within and between hosts.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This document should be considered the authoritative description of the
IPython messaging protocol, and all developers are strongly encouraged to
keep it updated as the implementation evolves, so that we have a single
common reference for all protocol details.</p>
</div>
<p>The basic design is explained in the following diagram:</p>
<a class="reference external image-reference" href="../_images/frontend-kernel.png"><img alt="IPython kernel/frontend messaging architecture." class="align-center" src="../_images/frontend-kernel.png" style="width: 450px;" /></a>
<p>A single kernel can be simultaneously connected to one or more frontends. The
kernel has three sockets that serve the following functions:</p>
<ol class="arabic">
<li><p class="first">stdin: this ROUTER socket is connected to all frontends, and it allows
the kernel to request input from the active frontend when <a class="reference external" href="http://docs.python.org/2/library/functions.html#raw_input" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">raw_input()</span></tt></a> is called.
The frontend that executed the code has a DEALER socket that acts as a ‘virtual keyboard’
for the kernel while this communication is happening (illustrated in the
figure by the black outline around the central keyboard). In practice,
frontends may display such kernel requests using a special input widget or
otherwise indicating that the user is to type input for the kernel instead
of normal commands in the frontend.</p>
</li>
<li><p class="first">Shell: this single ROUTER socket allows multiple incoming connections from
frontends, and this is the socket where requests for code execution, object
information, prompts, etc. are made to the kernel by any frontend. The
communication on this socket is a sequence of request/reply actions from
each frontend and the kernel.</p>
</li>
<li><p class="first">IOPub: this socket is the ‘broadcast channel’ where the kernel publishes all
side effects (stdout, stderr, etc.) as well as the requests coming from any
client over the shell socket and its own requests on the stdin socket. There
are a number of actions in Python which generate side effects: <a class="reference external" href="http://docs.python.org/2/library/functions.html#print" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">print()</span></tt></a>
writes to <tt class="docutils literal"><span class="pre">sys.stdout</span></tt>, errors generate tracebacks, etc. Additionally, in
a multi-client scenario, we want all frontends to be able to know what each
other has sent to the kernel (this can be useful in collaborative scenarios,
for example). This socket allows both side effects and the information
about communications taking place with one client over the shell channel
to be made available to all clients in a uniform manner.</p>
<p>All messages are tagged with enough information (details below) for clients
to know which messages come from their own interaction with the kernel and
which ones are from other clients, so they can display each type
appropriately.</p>
</li>
</ol>
<p>The actual format of the messages allowed on each of these channels is
specified below. Messages are dicts of dicts with string keys and values that
are reasonably representable in JSON. Our current implementation uses JSON
explicitly as its message format, but this shouldn’t be considered a permanent
feature. As we’ve discovered that JSON has non-trivial performance issues due
to excessive copying, we may in the future move to a pure pickle-based raw
message format. However, it should be possible to easily convert from the raw
objects to JSON, since we may have non-python clients (e.g. a web frontend).
As long as it’s easy to make a JSON version of the objects that is a faithful
representation of all the data, we can communicate with such clients.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Not all of these have yet been fully fleshed out, but the key ones are, see
kernel and frontend files for actual implementation details.</p>
</div>
</div>
<div class="section" id="general-message-format">
<h2>General Message Format<a class="headerlink" href="#general-message-format" title="Permalink to this headline">¶</a></h2>
<p>A message is defined by the following four-dictionary structure:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
<span class="c"># The message header contains a pair of unique identifiers for the</span>
<span class="c"># originating session and the actual message id, in addition to the</span>
<span class="c"># username for the process that generated the message. This is useful in</span>
<span class="c"># collaborative settings where multiple users may be interacting with the</span>
<span class="c"># same kernel simultaneously, so that frontends can label the various</span>
<span class="c"># messages in a meaningful way.</span>
<span class="s">'header'</span> <span class="p">:</span> <span class="p">{</span>
<span class="s">'msg_id'</span> <span class="p">:</span> <span class="n">uuid</span><span class="p">,</span>
<span class="s">'username'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="s">'session'</span> <span class="p">:</span> <span class="n">uuid</span><span class="p">,</span>
<span class="c"># All recognized message type strings are listed below.</span>
<span class="s">'msg_type'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="p">},</span>
<span class="c"># In a chain of messages, the header from the parent is copied so that</span>
<span class="c"># clients can track where messages come from.</span>
<span class="s">'parent_header'</span> <span class="p">:</span> <span class="nb">dict</span><span class="p">,</span>
<span class="c"># Any metadata associated with the message.</span>
<span class="s">'metadata'</span> <span class="p">:</span> <span class="nb">dict</span><span class="p">,</span>
<span class="c"># The actual content of the message must be a dict, whose structure</span>
<span class="c"># depends on the message type.</span>
<span class="s">'content'</span> <span class="p">:</span> <span class="nb">dict</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="the-wire-protocol">
<h2>The Wire Protocol<a class="headerlink" href="#the-wire-protocol" title="Permalink to this headline">¶</a></h2>
<p>This message format exists at a high level,
but does not describe the actual <em>implementation</em> at the wire level in zeromq.
The canonical implementation of the message spec is our <a class="reference internal" href="../api/generated/IPython.kernel.zmq.session.html#IPython.kernel.zmq.session.Session" title="IPython.kernel.zmq.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a> class.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This section should only be relevant to non-Python consumers of the protocol.
Python consumers should simply import and use IPython’s own implementation of the wire protocol
in the <a class="reference internal" href="../api/generated/IPython.kernel.zmq.session.html#IPython.kernel.zmq.session.Session" title="IPython.kernel.zmq.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">IPython.kernel.zmq.session.Session</span></tt></a> object.</p>
</div>
<p>Every message is serialized to a sequence of at least six blobs of bytes:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">[</span>
<span class="n">b</span><span class="s">'u-u-i-d'</span><span class="p">,</span> <span class="c"># zmq identity(ies)</span>
<span class="n">b</span><span class="s">'<IDS|MSG>'</span><span class="p">,</span> <span class="c"># delimiter</span>
<span class="n">b</span><span class="s">'baddad42'</span><span class="p">,</span> <span class="c"># HMAC signature</span>
<span class="n">b</span><span class="s">'{header}'</span><span class="p">,</span> <span class="c"># serialized header dict</span>
<span class="n">b</span><span class="s">'{parent_header}'</span><span class="p">,</span> <span class="c"># serialized parent header dict</span>
<span class="n">b</span><span class="s">'{metadata}'</span><span class="p">,</span> <span class="c"># serialized metadata dict</span>
<span class="n">b</span><span class="s">'{content}, # serialized content dict</span>
<span class="n">b</span><span class="s">'blob'</span><span class="p">,</span> <span class="c"># extra raw data buffer(s)</span>
<span class="o">...</span>
<span class="p">]</span>
</pre></div>
</div>
<p>The front of the message is the ZeroMQ routing prefix,
which can be zero or more socket identities.
This is every piece of the message prior to the delimiter key <tt class="docutils literal"><span class="pre"><IDS|MSG></span></tt>.
In the case of IOPub, there should be just one prefix component,
which is the topic for IOPub subscribers, e.g. <tt class="docutils literal"><span class="pre">pyout</span></tt>, <tt class="docutils literal"><span class="pre">display_data</span></tt>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">In most cases, the IOPub topics are irrelevant and completely ignored,
because frontends just subscribe to all topics.
The convention used in the IPython kernel is to use the msg_type as the topic,
and possibly extra information about the message, e.g. <tt class="docutils literal"><span class="pre">pyout</span></tt> or <tt class="docutils literal"><span class="pre">stream.stdout</span></tt></p>
</div>
<p>After the delimiter is the <a class="reference external" href="http://en.wikipedia.org/wiki/HMAC">HMAC</a> signature of the message, used for authentication.
If authentication is disabled, this should be an empty string.
By default, the hashing function used for computing these signatures is sha256.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">To disable authentication and signature checking,
set the <cite>key</cite> field of a connection file to an empty string.</p>
</div>
<p>The signature is the HMAC hex digest of the concatenation of:</p>
<ul class="simple">
<li>A shared key (typically the <tt class="docutils literal"><span class="pre">key</span></tt> field of a connection file)</li>
<li>The serialized header dict</li>
<li>The serialized parent header dict</li>
<li>The serialized metadata dict</li>
<li>The serialized content dict</li>
</ul>
<p>In Python, this is implemented via:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># once:</span>
<span class="n">digester</span> <span class="o">=</span> <span class="n">HMAC</span><span class="p">(</span><span class="n">key</span><span class="p">,</span> <span class="n">digestmod</span><span class="o">=</span><span class="n">hashlib</span><span class="o">.</span><span class="n">sha256</span><span class="p">)</span>
<span class="c"># for each message</span>
<span class="n">d</span> <span class="o">=</span> <span class="n">digester</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span>
<span class="k">for</span> <span class="n">serialized_dict</span> <span class="ow">in</span> <span class="p">(</span><span class="n">header</span><span class="p">,</span> <span class="n">parent</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span> <span class="n">content</span><span class="p">):</span>
<span class="n">d</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">serialized_dict</span><span class="p">)</span>
<span class="n">signature</span> <span class="o">=</span> <span class="n">d</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span>
</pre></div>
</div>
<p>After the signature is the actual message, always in four frames of bytes.
The four dictionaries that compose a message are serialized separately,
in the order of header, parent header, metadata, and content.
These can be serialized by any function that turns a dict into bytes.
The default and most common serialization is JSON, but msgpack and pickle
are common alternatives.</p>
<p>After the serialized dicts are zero to many raw data buffers,
which can be used by message types that support binary data (mainly apply and data_pub).</p>
</div>
<div class="section" id="python-functional-api">
<h2>Python functional API<a class="headerlink" href="#python-functional-api" title="Permalink to this headline">¶</a></h2>
<p>As messages are dicts, they map naturally to a <tt class="docutils literal"><span class="pre">func(**kw)</span></tt> call form. We
should develop, at a few key points, functional forms of all the requests that
take arguments in this manner and automatically construct the necessary dict
for sending.</p>
<p>In addition, the Python implementation of the message specification extends
messages upon deserialization to the following form for convenience:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
<span class="s">'header'</span> <span class="p">:</span> <span class="nb">dict</span><span class="p">,</span>
<span class="c"># The msg's unique identifier and type are always stored in the header,</span>
<span class="c"># but the Python implementation copies them to the top level.</span>
<span class="s">'msg_id'</span> <span class="p">:</span> <span class="n">uuid</span><span class="p">,</span>
<span class="s">'msg_type'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="s">'parent_header'</span> <span class="p">:</span> <span class="nb">dict</span><span class="p">,</span>
<span class="s">'content'</span> <span class="p">:</span> <span class="nb">dict</span><span class="p">,</span>
<span class="s">'metadata'</span> <span class="p">:</span> <span class="nb">dict</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
<p>All messages sent to or received by any IPython process should have this
extended structure.</p>
</div>
<div class="section" id="messages-on-the-shell-router-dealer-sockets">
<h2>Messages on the shell ROUTER/DEALER sockets<a class="headerlink" href="#messages-on-the-shell-router-dealer-sockets" title="Permalink to this headline">¶</a></h2>
<div class="section" id="execute">
<span id="id1"></span><h3>Execute<a class="headerlink" href="#execute" title="Permalink to this headline">¶</a></h3>
<p>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).</p>
<p>Message type: <tt class="docutils literal"><span class="pre">execute_request</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="c"># Source code to be executed by the kernel, one or more lines.</span>
<span class="s">'code'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># A boolean flag which, if True, signals the kernel to execute</span>
<span class="c"># this code as quietly as possible. This means that the kernel</span>
<span class="c"># will compile the code with 'exec' instead of 'single' (so</span>
<span class="c"># sys.displayhook will not fire), forces store_history to be False,</span>
<span class="c"># and will *not*:</span>
<span class="c"># - broadcast exceptions on the PUB socket</span>
<span class="c"># - do any logging</span>
<span class="c">#</span>
<span class="c"># The default is False.</span>
<span class="s">'silent'</span> <span class="p">:</span> <span class="nb">bool</span><span class="p">,</span>
<span class="c"># A boolean flag which, if True, signals the kernel to populate history</span>
<span class="c"># The default is True if silent is False. If silent is True, store_history</span>
<span class="c"># is forced to be False.</span>
<span class="s">'store_history'</span> <span class="p">:</span> <span class="nb">bool</span><span class="p">,</span>
<span class="c"># A list of variable names from the user's namespace to be retrieved.</span>
<span class="c"># What returns is a rich representation of each variable (dict keyed by name).</span>
<span class="c"># See the display_data content for the structure of the representation data.</span>
<span class="s">'user_variables'</span> <span class="p">:</span> <span class="nb">list</span><span class="p">,</span>
<span class="c"># Similarly, a dict mapping names to expressions to be evaluated in the</span>
<span class="c"># user's dict.</span>
<span class="s">'user_expressions'</span> <span class="p">:</span> <span class="nb">dict</span><span class="p">,</span>
<span class="c"># Some frontends (e.g. the Notebook) do not support stdin requests. If</span>
<span class="c"># raw_input is called from code executed from such a frontend, a</span>
<span class="c"># StdinNotImplementedError will be raised.</span>
<span class="s">'allow_stdin'</span> <span class="p">:</span> <span class="bp">True</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">code</span></tt> field contains a single string (possibly multiline). The kernel
is responsible for splitting this into one or more independent execution blocks
and deciding whether to compile these in ‘single’ or ‘exec’ mode (see below for
detailed execution semantics).</p>
<p>The <tt class="docutils literal"><span class="pre">user_</span></tt> fields deserve a detailed explanation. In the past, IPython had
the notion of a prompt string that allowed arbitrary code to be evaluated, and
this was put to good use by many in creating prompts that displayed system
status, path information, and even more esoteric uses like remote instrument
status acquired over the network. But now that IPython has a clean separation
between the kernel and the clients, the kernel has no prompt knowledge; prompts
are a frontend-side feature, and it should be even possible for different
frontends to display different prompts while interacting with the same kernel.</p>
<p>The kernel now provides the ability to retrieve data from the user’s namespace
after the execution of the main <tt class="docutils literal"><span class="pre">code</span></tt>, thanks to two fields in the
<tt class="docutils literal"><span class="pre">execute_request</span></tt> message:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">user_variables</span></tt>: If only variables from the user’s namespace are needed, a
list of variable names can be passed and a dict with these names as keys and
their <a class="reference external" href="http://docs.python.org/2/library/functions.html#repr" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">repr()</span></tt></a> as values will be returned.</li>
<li><tt class="docutils literal"><span class="pre">user_expressions</span></tt>: For more complex expressions that require function
evaluations, a dict can be provided with string keys and arbitrary python
expressions as values. The return message will contain also a dict with the
same keys and the <a class="reference external" href="http://docs.python.org/2/library/functions.html#repr" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">repr()</span></tt></a> of the evaluated expressions as value.</li>
</ul>
<p>With this information, frontends can display any status information they wish
in the form that best suits each frontend (a status line, a popup, inline for a
terminal, etc).</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">In order to obtain the current execution counter for the purposes of
displaying input prompts, frontends simply make an execution request with an
empty code string and <tt class="docutils literal"><span class="pre">silent=True</span></tt>.</p>
</div>
<div class="section" id="execution-semantics">
<h4>Execution semantics<a class="headerlink" href="#execution-semantics" title="Permalink to this headline">¶</a></h4>
<p>When the silent flag is false, the execution of use code consists of the
following phases (in silent mode, only the <tt class="docutils literal"><span class="pre">code</span></tt> field is executed):</p>
<ol class="arabic simple">
<li>Run the <tt class="docutils literal"><span class="pre">pre_runcode_hook</span></tt>.</li>
<li>Execute the <tt class="docutils literal"><span class="pre">code</span></tt> field, see below for details.</li>
<li>If #2 succeeds, compute <tt class="docutils literal"><span class="pre">user_variables</span></tt> and <tt class="docutils literal"><span class="pre">user_expressions</span></tt> are
computed. This ensures that any error in the latter don’t harm the main
code execution.</li>
<li>Call any method registered with <tt class="xref py py-meth docutils literal"><span class="pre">register_post_execute()</span></tt>.</li>
</ol>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">The API for running code before/after the main code block is likely to
change soon. Both the <tt class="docutils literal"><span class="pre">pre_runcode_hook</span></tt> and the
<tt class="xref py py-meth docutils literal"><span class="pre">register_post_execute()</span></tt> are susceptible to modification, as we find a
consistent model for both.</p>
</div>
<p>To understand how the <tt class="docutils literal"><span class="pre">code</span></tt> field is executed, one must know that Python
code can be compiled in one of three modes (controlled by the <tt class="docutils literal"><span class="pre">mode</span></tt> argument
to the <a class="reference external" href="http://docs.python.org/2/library/functions.html#compile" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">compile()</span></tt></a> builtin):</p>
<dl class="docutils">
<dt><em>single</em></dt>
<dd><p class="first">Valid for a single interactive statement (though the source can contain
multiple lines, such as a for loop). When compiled in this mode, the
generated bytecode contains special instructions that trigger the calling of
<a class="reference external" href="http://docs.python.org/2/library/sys.html#sys.displayhook" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">sys.displayhook()</span></tt></a> for any expression in the block that returns a value.
This means that a single statement can actually produce multiple calls to
<a class="reference external" href="http://docs.python.org/2/library/sys.html#sys.displayhook" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">sys.displayhook()</span></tt></a>, if for example it contains a loop where each
iteration computes an unassigned expression would generate 10 calls:</p>
<div class="last highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">):</span>
<span class="n">i</span><span class="o">**</span><span class="mi">2</span>
</pre></div>
</div>
</dd>
<dt><em>exec</em></dt>
<dd>An arbitrary amount of source code, this is how modules are compiled.
<a class="reference external" href="http://docs.python.org/2/library/sys.html#sys.displayhook" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">sys.displayhook()</span></tt></a> is <em>never</em> implicitly called.</dd>
<dt><em>eval</em></dt>
<dd>A single expression that returns a value. <a class="reference external" href="http://docs.python.org/2/library/sys.html#sys.displayhook" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">sys.displayhook()</span></tt></a> is <em>never</em>
implicitly called.</dd>
</dl>
<p>The <tt class="docutils literal"><span class="pre">code</span></tt> field is split into individual blocks each of which is valid for
execution in ‘single’ mode, and then:</p>
<ul class="simple">
<li>If there is only a single block: it is executed in ‘single’ mode.</li>
<li>If there is more than one block:<ul>
<li>if the last one is a single line long, run all but the last in ‘exec’ mode
and the very last one in ‘single’ mode. This makes it easy to type simple
expressions at the end to see computed values.</li>
<li>if the last one is no more than two lines long, run all but the last in
‘exec’ mode and the very last one in ‘single’ mode. This makes it easy to
type simple expressions at the end to see computed values. - otherwise
(last one is also multiline), run all in ‘exec’ mode</li>
<li>otherwise (last one is also multiline), run all in ‘exec’ mode as a single
unit.</li>
</ul>
</li>
</ul>
<p>Any error in retrieving the <tt class="docutils literal"><span class="pre">user_variables</span></tt> or evaluating the
<tt class="docutils literal"><span class="pre">user_expressions</span></tt> will result in a simple error message in the return fields
of the form:</p>
<div class="highlight-python"><div class="highlight"><pre>[ERROR] ExceptionType: Exception message
</pre></div>
</div>
<p>The user can simply send the same variable name or expression for evaluation to
see a regular traceback.</p>
<p>Errors in any registered post_execute functions are also reported similarly,
and the failing function is removed from the post_execution set so that it does
not continue triggering failures.</p>
<p>Upon completion of the execution request, the kernel <em>always</em> sends a reply,
with a status code indicating what happened and additional data depending on
the outcome. See <a class="reference internal" href="#execution-results"><em>below</em></a> for the possible return
codes and associated data.</p>
</div>
<div class="section" id="execution-counter-old-prompt-number">
<span id="execution-counter"></span><h4>Execution counter (old prompt number)<a class="headerlink" href="#execution-counter-old-prompt-number" title="Permalink to this headline">¶</a></h4>
<p>The kernel has a single, monotonically increasing counter of all execution
requests that are made with <tt class="docutils literal"><span class="pre">store_history=True</span></tt>. This counter is used to populate
the <tt class="docutils literal"><span class="pre">In[n]</span></tt>, <tt class="docutils literal"><span class="pre">Out[n]</span></tt> and <tt class="docutils literal"><span class="pre">_n</span></tt> variables, so clients will likely want to
display it in some form to the user, which will typically (but not necessarily)
be done in the prompts. The value of this counter will be returned as the
<tt class="docutils literal"><span class="pre">execution_count</span></tt> field of all <tt class="docutils literal"><span class="pre">execute_reply</span></tt> and <tt class="docutils literal"><span class="pre">pyin</span></tt> messages.</p>
</div>
<div class="section" id="execution-results">
<span id="id2"></span><h4>Execution results<a class="headerlink" href="#execution-results" title="Permalink to this headline">¶</a></h4>
<p>Message type: <tt class="docutils literal"><span class="pre">execute_reply</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="c"># One of: 'ok' OR 'error' OR 'abort'</span>
<span class="s">'status'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># The global kernel counter that increases by one with each request that</span>
<span class="c"># stores history. This will typically be used by clients to display</span>
<span class="c"># prompt numbers to the user. If the request did not store history, this will</span>
<span class="c"># be the current value of the counter in the kernel.</span>
<span class="s">'execution_count'</span> <span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
<p>When status is ‘ok’, the following extra fields are present:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
<span class="c"># 'payload' will be a list of payload dicts.</span>
<span class="c"># Each execution payload is a dict with string keys that may have been</span>
<span class="c"># produced by the code being executed. It is retrieved by the kernel at</span>
<span class="c"># the end of the execution and sent back to the front end, which can take</span>
<span class="c"># action on it as needed.</span>
<span class="c"># The only requirement of each payload dict is that it have a 'source' key,</span>
<span class="c"># which is a string classifying the payload (e.g. 'pager').</span>
<span class="s">'payload'</span> <span class="p">:</span> <span class="nb">list</span><span class="p">(</span><span class="nb">dict</span><span class="p">),</span>
<span class="c"># Results for the user_variables and user_expressions.</span>
<span class="s">'user_variables'</span> <span class="p">:</span> <span class="nb">dict</span><span class="p">,</span>
<span class="s">'user_expressions'</span> <span class="p">:</span> <span class="nb">dict</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="admonition-execution-payloads admonition">
<p class="first admonition-title">Execution payloads</p>
<p>The notion of an ‘execution payload’ is different from a return value of a
given set of code, which normally is just displayed on the pyout stream
through the PUB socket. The idea of a payload is to allow special types of
code, typically magics, to populate a data container in the IPython kernel
that will be shipped back to the caller via this channel. The kernel
has an API for this in the PayloadManager:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">ip</span><span class="o">.</span><span class="n">payload_manager</span><span class="o">.</span><span class="n">write_payload</span><span class="p">(</span><span class="n">payload_dict</span><span class="p">)</span>
</pre></div>
</div>
<p>which appends a dictionary to the list of payloads.</p>
<p class="last">The payload API is not yet stabilized,
and should probably not be supported by non-Python kernels at this time.
In such cases, the payload list should always be empty.</p>
</div>
<p>When status is ‘error’, the following extra fields are present:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
<span class="s">'ename'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="c"># Exception name, as a string</span>
<span class="s">'evalue'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="c"># Exception value, as a string</span>
<span class="c"># The traceback will contain a list of frames, represented each as a</span>
<span class="c"># string. For now we'll stick to the existing design of ultraTB, which</span>
<span class="c"># controls exception level of detail statefully. But eventually we'll</span>
<span class="c"># want to grow into a model where more information is collected and</span>
<span class="c"># packed into the traceback object, with clients deciding how little or</span>
<span class="c"># how much of it to unpack. But for now, let's start with a simple list</span>
<span class="c"># of strings, since that requires only minimal changes to ultratb as</span>
<span class="c"># written.</span>
<span class="s">'traceback'</span> <span class="p">:</span> <span class="nb">list</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
<p>When status is ‘abort’, there are for now no additional data fields. This
happens when the kernel was interrupted by a signal.</p>
</div>
</div>
<div class="section" id="object-information">
<h3>Object information<a class="headerlink" href="#object-information" title="Permalink to this headline">¶</a></h3>
<p>One of IPython’s most used capabilities is the introspection of Python objects
in the user’s namespace, typically invoked via the <tt class="docutils literal"><span class="pre">?</span></tt> and <tt class="docutils literal"><span class="pre">??</span></tt> characters
(which in reality are shorthands for the <tt class="docutils literal"><span class="pre">%pinfo</span></tt> magic). This is used often
enough that it warrants an explicit message type, especially because frontends
may want to get object information in response to user keystrokes (like Tab or
F1) besides from the user explicitly typing code like <tt class="docutils literal"><span class="pre">x??</span></tt>.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">object_info_request</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="c"># The (possibly dotted) name of the object to be searched in all</span>
<span class="c"># relevant namespaces</span>
<span class="s">'oname'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># The level of detail desired. The default (0) is equivalent to typing</span>
<span class="c"># 'x?' at the prompt, 1 is equivalent to 'x??'.</span>
<span class="s">'detail_level'</span> <span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The returned information will be a dictionary with keys very similar to the
field names that IPython prints at the terminal.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">object_info_reply</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="c"># The name the object was requested under</span>
<span class="s">'name'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># Boolean flag indicating whether the named object was found or not. If</span>
<span class="c"># it's false, all other fields will be empty.</span>
<span class="s">'found'</span> <span class="p">:</span> <span class="nb">bool</span><span class="p">,</span>
<span class="c"># Flags for magics and system aliases</span>
<span class="s">'ismagic'</span> <span class="p">:</span> <span class="nb">bool</span><span class="p">,</span>
<span class="s">'isalias'</span> <span class="p">:</span> <span class="nb">bool</span><span class="p">,</span>
<span class="c"># The name of the namespace where the object was found ('builtin',</span>
<span class="c"># 'magics', 'alias', 'interactive', etc.)</span>
<span class="s">'namespace'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># The type name will be type.__name__ for normal Python objects, but it</span>
<span class="c"># can also be a string like 'Magic function' or 'System alias'</span>
<span class="s">'type_name'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># The string form of the object, possibly truncated for length if</span>
<span class="c"># detail_level is 0</span>
<span class="s">'string_form'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># For objects with a __class__ attribute this will be set</span>
<span class="s">'base_class'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># For objects with a __len__ attribute this will be set</span>
<span class="s">'length'</span> <span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
<span class="c"># If the object is a function, class or method whose file we can find,</span>
<span class="c"># we give its full path</span>
<span class="s">'file'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># For pure Python callable objects, we can reconstruct the object</span>
<span class="c"># definition line which provides its call signature. For convenience this</span>
<span class="c"># is returned as a single 'definition' field, but below the raw parts that</span>
<span class="c"># compose it are also returned as the argspec field.</span>
<span class="s">'definition'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># The individual parts that together form the definition string. Clients</span>
<span class="c"># with rich display capabilities may use this to provide a richer and more</span>
<span class="c"># precise representation of the definition line (e.g. by highlighting</span>
<span class="c"># arguments based on the user's cursor position). For non-callable</span>
<span class="c"># objects, this field is empty.</span>
<span class="s">'argspec'</span> <span class="p">:</span> <span class="p">{</span> <span class="c"># The names of all the arguments</span>
<span class="n">args</span> <span class="p">:</span> <span class="nb">list</span><span class="p">,</span>
<span class="c"># The name of the varargs (*args), if any</span>
<span class="n">varargs</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># The name of the varkw (**kw), if any</span>
<span class="n">varkw</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># The values (as strings) of all default arguments. Note</span>
<span class="c"># that these must be matched *in reverse* with the 'args'</span>
<span class="c"># list above, since the first positional args have no default</span>
<span class="c"># value at all.</span>
<span class="n">defaults</span> <span class="p">:</span> <span class="nb">list</span><span class="p">,</span>
<span class="p">},</span>
<span class="c"># For instances, provide the constructor signature (the definition of</span>
<span class="c"># the __init__ method):</span>
<span class="s">'init_definition'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># Docstrings: for any object (function, method, module, package) with a</span>
<span class="c"># docstring, we show it. But in addition, we may provide additional</span>
<span class="c"># docstrings. For example, for instances we will show the constructor</span>
<span class="c"># and class docstrings as well, if available.</span>
<span class="s">'docstring'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># For instances, provide the constructor and class docstrings</span>
<span class="s">'init_docstring'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="s">'class_docstring'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># If it's a callable object whose call method has a separate docstring and</span>
<span class="c"># definition line:</span>
<span class="s">'call_def'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="s">'call_docstring'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># If detail_level was 1, we also try to find the source code that</span>
<span class="c"># defines the object, if possible. The string 'None' will indicate</span>
<span class="c"># that no source was found.</span>
<span class="s">'source'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="complete">
<h3>Complete<a class="headerlink" href="#complete" title="Permalink to this headline">¶</a></h3>
<p>Message type: <tt class="docutils literal"><span class="pre">complete_request</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="c"># The text to be completed, such as 'a.is'</span>
<span class="c"># this may be an empty string if the frontend does not do any lexing,</span>
<span class="c"># in which case the kernel must figure out the completion</span>
<span class="c"># based on 'line' and 'cursor_pos'.</span>
<span class="s">'text'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># The full line, such as 'print a.is'. This allows completers to</span>
<span class="c"># make decisions that may require information about more than just the</span>
<span class="c"># current word.</span>
<span class="s">'line'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># The entire block of text where the line is. This may be useful in the</span>
<span class="c"># case of multiline completions where more context may be needed. Note: if</span>
<span class="c"># in practice this field proves unnecessary, remove it to lighten the</span>
<span class="c"># messages.</span>
<span class="s">'block'</span> <span class="p">:</span> <span class="nb">str</span> <span class="ow">or</span> <span class="n">null</span><span class="o">/</span><span class="bp">None</span><span class="p">,</span>
<span class="c"># The position of the cursor where the user hit 'TAB' on the line.</span>
<span class="s">'cursor_pos'</span> <span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Message type: <tt class="docutils literal"><span class="pre">complete_reply</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="c"># The list of all matches to the completion request, such as</span>
<span class="c"># ['a.isalnum', 'a.isalpha'] for the above example.</span>
<span class="s">'matches'</span> <span class="p">:</span> <span class="nb">list</span><span class="p">,</span>
<span class="c"># the substring of the matched text</span>
<span class="c"># this is typically the common prefix of the matches,</span>
<span class="c"># and the text that is already in the block that would be replaced by the full completion.</span>
<span class="c"># This would be 'a.is' in the above example.</span>
<span class="s">'matched_text'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># status should be 'ok' unless an exception was raised during the request,</span>
<span class="c"># in which case it should be 'error', along with the usual error message content</span>
<span class="c"># in other messages.</span>
<span class="s">'status'</span> <span class="p">:</span> <span class="s">'ok'</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="history">
<h3>History<a class="headerlink" href="#history" title="Permalink to this headline">¶</a></h3>
<p>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.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">history_request</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="c"># If True, also return output history in the resulting dict.</span>
<span class="s">'output'</span> <span class="p">:</span> <span class="nb">bool</span><span class="p">,</span>
<span class="c"># If True, return the raw input history, else the transformed input.</span>
<span class="s">'raw'</span> <span class="p">:</span> <span class="nb">bool</span><span class="p">,</span>
<span class="c"># So far, this can be 'range', 'tail' or 'search'.</span>
<span class="s">'hist_access_type'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># If hist_access_type is 'range', get a range of input cells. session can</span>
<span class="c"># be a positive session number, or a negative number to count back from</span>
<span class="c"># the current session.</span>
<span class="s">'session'</span> <span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
<span class="c"># start and stop are line numbers within that session.</span>
<span class="s">'start'</span> <span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
<span class="s">'stop'</span> <span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
<span class="c"># If hist_access_type is 'tail' or 'search', get the last n cells.</span>
<span class="s">'n'</span> <span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
<span class="c"># If hist_access_type is 'search', get cells matching the specified glob</span>
<span class="c"># pattern (with * and ? as wildcards).</span>
<span class="s">'pattern'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># If hist_access_type is 'search' and unique is true, do not</span>
<span class="c"># include duplicated history. Default is false.</span>
<span class="s">'unique'</span> <span class="p">:</span> <span class="nb">bool</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 4.0: </span>The key <tt class="docutils literal"><span class="pre">unique</span></tt> for <tt class="docutils literal"><span class="pre">history_request</span></tt>.</p>
</div>
<p>Message type: <tt class="docutils literal"><span class="pre">history_reply</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="c"># A list of 3 tuples, either:</span>
<span class="c"># (session, line_number, input) or</span>
<span class="c"># (session, line_number, (input, output)),</span>
<span class="c"># depending on whether output was False or True, respectively.</span>
<span class="s">'history'</span> <span class="p">:</span> <span class="nb">list</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="connect">
<h3>Connect<a class="headerlink" href="#connect" title="Permalink to this headline">¶</a></h3>
<p>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.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">connect_request</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Message type: <tt class="docutils literal"><span class="pre">connect_reply</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'shell_port'</span> <span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="c"># The port the shell ROUTER socket is listening on.</span>
<span class="s">'iopub_port'</span> <span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="c"># The port the PUB socket is listening on.</span>
<span class="s">'stdin_port'</span> <span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="c"># The port the stdin ROUTER socket is listening on.</span>
<span class="s">'hb_port'</span> <span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="c"># The port the heartbeat socket is listening on.</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="kernel-info">
<h3>Kernel info<a class="headerlink" href="#kernel-info" title="Permalink to this headline">¶</a></h3>
<p>If a client needs to know information about the kernel, it can
make a request of the kernel’s information.
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.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">kernel_info_request</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Message type: <tt class="docutils literal"><span class="pre">kernel_info_reply</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="c"># Version of messaging protocol (mandatory).</span>
<span class="c"># The first integer indicates major version. It is incremented when</span>
<span class="c"># there is any backward incompatible change.</span>
<span class="c"># The second integer indicates minor version. It is incremented when</span>
<span class="c"># there is any backward compatible change.</span>
<span class="s">'protocol_version'</span><span class="p">:</span> <span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="nb">int</span><span class="p">],</span>
<span class="c"># IPython version number (optional).</span>
<span class="c"># Non-python kernel backend may not have this version number.</span>
<span class="c"># The last component is an extra field, which may be 'dev' or</span>
<span class="c"># 'rc1' in development version. It is an empty string for</span>
<span class="c"># released version.</span>
<span class="s">'ipython_version'</span><span class="p">:</span> <span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="nb">int</span><span class="p">,</span> <span class="nb">int</span><span class="p">,</span> <span class="nb">str</span><span class="p">],</span>
<span class="c"># Language version number (mandatory).</span>
<span class="c"># It is Python version number (e.g., [2, 7, 3]) for the kernel</span>
<span class="c"># included in IPython.</span>
<span class="s">'language_version'</span><span class="p">:</span> <span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="o">...</span><span class="p">],</span>
<span class="c"># Programming language in which kernel is implemented (mandatory).</span>
<span class="c"># Kernel included in IPython returns 'python'.</span>
<span class="s">'language'</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="kernel-shutdown">
<h3>Kernel shutdown<a class="headerlink" href="#kernel-shutdown" title="Permalink to this headline">¶</a></h3>
<p>The clients can request the kernel to shut itself down; this is used in
multiple cases:</p>
<ul class="simple">
<li>when the user chooses to close the client application via a menu or window
control.</li>
<li>when the user types ‘exit’ or ‘quit’ (or their uppercase magic equivalents).</li>
<li>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.</li>
</ul>
<p>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.</p>
<p>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.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">shutdown_request</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'restart'</span> <span class="p">:</span> <span class="nb">bool</span> <span class="c"># whether the shutdown is final, or precedes a restart</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Message type: <tt class="docutils literal"><span class="pre">shutdown_reply</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'restart'</span> <span class="p">:</span> <span class="nb">bool</span> <span class="c"># whether the shutdown is final, or precedes a restart</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">When the clients detect a dead kernel thanks to inactivity on the heartbeat
socket, they simply send a forceful process termination signal, since a dead
process is unlikely to respond in any useful way to messages.</p>
</div>
</div>
</div>
<div class="section" id="messages-on-the-pub-sub-socket">
<h2>Messages on the PUB/SUB socket<a class="headerlink" href="#messages-on-the-pub-sub-socket" title="Permalink to this headline">¶</a></h2>
<div class="section" id="streams-stdout-stderr-etc">
<h3>Streams (stdout, stderr, etc)<a class="headerlink" href="#streams-stdout-stderr-etc" title="Permalink to this headline">¶</a></h3>
<p>Message type: <tt class="docutils literal"><span class="pre">stream</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="c"># The name of the stream is one of 'stdout', 'stderr'</span>
<span class="s">'name'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># The data is an arbitrary string to be written to that stream</span>
<span class="s">'data'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="display-data">
<h3>Display Data<a class="headerlink" href="#display-data" title="Permalink to this headline">¶</a></h3>
<p>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 the
frontend to decide which to use and how. A single message should contain all
possible representations of the same information. Each representation should
be a JSON’able data structure, and should be a valid MIME type.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">display_data</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="c"># Who create the data</span>
<span class="s">'source'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
<span class="c"># The data dict contains key/value pairs, where the keys are MIME</span>
<span class="c"># types and the values are the raw data of the representation in that</span>
<span class="c"># format.</span>
<span class="s">'data'</span> <span class="p">:</span> <span class="nb">dict</span><span class="p">,</span>
<span class="c"># Any metadata that describes the data</span>
<span class="s">'metadata'</span> <span class="p">:</span> <span class="nb">dict</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">metadata</span></tt> contains any metadata that describes the output.
Global keys are assumed to apply to the output as a whole.
The <tt class="docutils literal"><span class="pre">metadata</span></tt> 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 dict
with a reasonably unique name to avoid conflicts.</p>
<p>The only metadata keys currently defined in IPython are the width and height
of images:</p>
<div class="highlight-python"><div class="highlight"><pre>'metadata' : {
'image/png' : {
'width': 640,
'height': 480
}
}
</pre></div>
</div>
</div>
<div class="section" id="raw-data-publication">
<h3>Raw Data Publication<a class="headerlink" href="#raw-data-publication" title="Permalink to this headline">¶</a></h3>
<p><tt class="docutils literal"><span class="pre">display_data</span></tt> lets you publish <em>representations</em> of data, such as images and html.
This <tt class="docutils literal"><span class="pre">data_pub</span></tt> message lets you publish <em>actual raw data</em>, sent via message buffers.</p>
<p>data_pub messages are constructed via the <tt class="xref py py-func docutils literal"><span class="pre">IPython.lib.datapub.publish_data()</span></tt> function:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">IPython.kernel.zmq.datapub</span> <span class="kn">import</span> <span class="n">publish_data</span>
<span class="n">ns</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">(</span><span class="n">x</span><span class="o">=</span><span class="n">my_array</span><span class="p">)</span>
<span class="n">publish_data</span><span class="p">(</span><span class="n">ns</span><span class="p">)</span>
</pre></div>
</div>
<p>Message type: <tt class="docutils literal"><span class="pre">data_pub</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre>content = {
# the keys of the data dict, after it has been unserialized
keys = ['a', 'b']
}
# the namespace dict will be serialized in the message buffers,
# which will have a length of at least one
buffers = ['pdict', ...]
</pre></div>
</div>
<p>The interpretation of a sequence of data_pub messages for a given parent request should be
to update a single namespace with subsequent results.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">No frontends directly handle data_pub messages at this time.
It is currently only used by the client/engines in <a class="reference internal" href="../api/generated/IPython.parallel.html#module-IPython.parallel" title="IPython.parallel"><tt class="xref py py-mod docutils literal"><span class="pre">IPython.parallel</span></tt></a>,
where engines may publish <em>data</em> to the Client,
of which the Client can then publish <em>representations</em> via <tt class="docutils literal"><span class="pre">display_data</span></tt>
to various frontends.</p>
</div>
</div>
<div class="section" id="python-inputs">
<h3>Python inputs<a class="headerlink" href="#python-inputs" title="Permalink to this headline">¶</a></h3>
<p>To let all frontends know what code is being executed at any given time, these
messages contain a re-broadcast of the <tt class="docutils literal"><span class="pre">code</span></tt> portion of an
<a class="reference internal" href="#execute"><em>execute_request</em></a>, along with the <a class="reference internal" href="#execution-counter"><em>execution_count</em></a>.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">pyin</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'code'</span> <span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="c"># Source code to be executed, one or more lines</span>
<span class="c"># The counter for this execution is also provided so that clients can</span>
<span class="c"># display it, since IPython automatically creates variables called _iN</span>
<span class="c"># (for input prompt In[N]).</span>
<span class="s">'execution_count'</span> <span class="p">:</span> <span class="nb">int</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="python-outputs">
<h3>Python outputs<a class="headerlink" href="#python-outputs" title="Permalink to this headline">¶</a></h3>
<p>When Python produces output from code that has been compiled in with the
‘single’ flag to <a class="reference external" href="http://docs.python.org/2/library/functions.html#compile" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">compile()</span></tt></a>, any expression that produces a value (such as
<tt class="docutils literal"><span class="pre">1+1</span></tt>) is passed to <tt class="docutils literal"><span class="pre">sys.displayhook</span></tt>, which is a callable that can do with
this value whatever it wants. The default behavior of <tt class="docutils literal"><span class="pre">sys.displayhook</span></tt> in
the Python interactive prompt is to print to <tt class="docutils literal"><span class="pre">sys.stdout</span></tt> the <a class="reference external" href="http://docs.python.org/2/library/functions.html#repr" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">repr()</span></tt></a> of
the value as long as it is not <tt class="docutils literal"><span class="pre">None</span></tt> (which isn’t printed at all). In our
case, the kernel instantiates as <tt class="docutils literal"><span class="pre">sys.displayhook</span></tt> an object which has
similar behavior, but which instead of printing to stdout, broadcasts these
values as <tt class="docutils literal"><span class="pre">pyout</span></tt> messages for clients to display appropriately.</p>
<p>IPython’s displayhook can handle multiple simultaneous formats depending on its
configuration. The default pretty-printed repr text is always given with the
<tt class="docutils literal"><span class="pre">data</span></tt> entry in this message. Any other formats are provided in the
<tt class="docutils literal"><span class="pre">extra_formats</span></tt> list. Frontends are free to display any or all of these
according to its capabilities. <tt class="docutils literal"><span class="pre">extra_formats</span></tt> list contains 3-tuples of an ID
string, a type string, and the data. The ID is unique to the formatter
implementation that created the data. Frontends will typically ignore the ID
unless if it has requested a particular formatter. The type string tells the
frontend how to interpret the data. It is often, but not always a MIME type.
Frontends should ignore types that it does not understand. The data itself is
any JSON object and depends on the format. It is often, but not always a string.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">pyout</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="c"># The counter for this execution is also provided so that clients can</span>
<span class="c"># display it, since IPython automatically creates variables called _N</span>
<span class="c"># (for prompt N).</span>
<span class="s">'execution_count'</span> <span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
<span class="c"># data and metadata are identical to a display_data message.</span>
<span class="c"># the object being displayed is that passed to the display hook,</span>
<span class="c"># i.e. the *result* of the execution.</span>
<span class="s">'data'</span> <span class="p">:</span> <span class="nb">dict</span><span class="p">,</span>
<span class="s">'metadata'</span> <span class="p">:</span> <span class="nb">dict</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="python-errors">
<h3>Python errors<a class="headerlink" href="#python-errors" title="Permalink to this headline">¶</a></h3>
<p>When an error occurs during code execution</p>
<p>Message type: <tt class="docutils literal"><span class="pre">pyerr</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="c"># Similar content to the execute_reply messages for the 'error' case,</span>
<span class="c"># except the 'status' field is omitted.</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="kernel-status">
<h3>Kernel status<a class="headerlink" href="#kernel-status" title="Permalink to this headline">¶</a></h3>
<p>This message type is used by frontends to monitor the status of the kernel.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">status</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="c"># When the kernel starts to execute code, it will enter the 'busy'</span>
<span class="c"># state and when it finishes, it will enter the 'idle' state.</span>
<span class="c"># The kernel will publish state 'starting' exactly once at process startup.</span>
<span class="n">execution_state</span> <span class="p">:</span> <span class="p">(</span><span class="s">'busy'</span><span class="p">,</span> <span class="s">'idle'</span><span class="p">,</span> <span class="s">'starting'</span><span class="p">)</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="clear-output">
<h3>Clear output<a class="headerlink" href="#clear-output" title="Permalink to this headline">¶</a></h3>
<p>This message type is used to clear the output that is visible on the frontend.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">clear_output</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="c"># Wait to clear the output until new output is available. Clears the</span>
<span class="c"># existing output immediately before the new output is displayed.</span>
<span class="c"># Useful for creating simple animations with minimal flickering.</span>
<span class="s">'wait'</span> <span class="p">:</span> <span class="nb">bool</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 4.1: </span>‘stdout’, ‘stderr’, and ‘display’ boolean keys for selective clearing are removed,
and ‘wait’ is added.
The selective clearing keys are ignored in v4 and the default behavior remains the same,
so v4 clear_output messages will be safely handled by a v4.1 frontend.</p>
</div>
</div>
</div>
<div class="section" id="messages-on-the-stdin-router-dealer-sockets">
<h2>Messages on the stdin ROUTER/DEALER sockets<a class="headerlink" href="#messages-on-the-stdin-router-dealer-sockets" title="Permalink to this headline">¶</a></h2>
<p>This is a socket where the request/reply pattern goes in the opposite direction:
from the kernel to a <em>single</em> frontend, and its purpose is to allow
<tt class="docutils literal"><span class="pre">raw_input</span></tt> and similar operations that read from <tt class="docutils literal"><span class="pre">sys.stdin</span></tt> on the kernel
to be fulfilled by the client. The request should be made to the frontend that
made the execution request that prompted <tt class="docutils literal"><span class="pre">raw_input</span></tt> to be called. For now we
will keep these messages as simple as possible, since they only mean to convey
the <tt class="docutils literal"><span class="pre">raw_input(prompt)</span></tt> call.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">input_request</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span> <span class="s">'prompt'</span> <span class="p">:</span> <span class="nb">str</span> <span class="p">}</span>
</pre></div>
</div>
<p>Message type: <tt class="docutils literal"><span class="pre">input_reply</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span> <span class="s">'value'</span> <span class="p">:</span> <span class="nb">str</span> <span class="p">}</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The stdin socket of the client is required to have the same zmq IDENTITY
as the client’s shell socket.
Because of this, the <tt class="docutils literal"><span class="pre">input_request</span></tt> must be sent with the same IDENTITY
routing prefix as the <tt class="docutils literal"><span class="pre">execute_reply</span></tt> in order for the frontend to receive
the message.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">We do not explicitly try to forward the raw <tt class="docutils literal"><span class="pre">sys.stdin</span></tt> object, because in
practice the kernel should behave like an interactive program. When a
program is opened on the console, the keyboard effectively takes over the
<tt class="docutils literal"><span class="pre">stdin</span></tt> file descriptor, and it can’t be used for raw reading anymore.
Since the IPython kernel effectively behaves like a console program (albeit
one whose “keyboard” is actually living in a separate process and
transported over the zmq connection), raw <tt class="docutils literal"><span class="pre">stdin</span></tt> isn’t expected to be
available.</p>
</div>
</div>
<div class="section" id="heartbeat-for-kernels">
<h2>Heartbeat for kernels<a class="headerlink" href="#heartbeat-for-kernels" title="Permalink to this headline">¶</a></h2>
<p>Initially we had considered using messages like those above over ZMQ for a
kernel ‘heartbeat’ (a way to detect quickly and reliably whether a kernel is
alive at all, even if it may be busy executing user code). But this has the
problem that if the kernel is locked inside extension code, it wouldn’t execute
the python heartbeat code. But it turns out that we can implement a basic
heartbeat with pure ZMQ, without using any Python messaging at all.</p>
<p>The monitor sends out a single zmq message (right now, it is a str of the
monitor’s lifetime in seconds), and gets the same message right back, prefixed
with the zmq identity of the DEALER socket in the heartbeat process. This can be
a uuid, or even a full message, but there doesn’t seem to be a need for packing
up a message when the sender and receiver are the exact same Python object.</p>
<p>The model is this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">monitor</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="nb">str</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">lifetime</span><span class="p">))</span> <span class="c"># '1.2345678910'</span>
</pre></div>
</div>
<p>and the monitor receives some number of messages of the form:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">[</span><span class="s">'uuid-abcd-dead-beef'</span><span class="p">,</span> <span class="s">'1.2345678910'</span><span class="p">]</span>
</pre></div>
</div>
<p>where the first part is the zmq.IDENTITY of the heart’s DEALER on the engine, and
the rest is the message sent by the monitor. No Python code ever has any
access to the message between the monitor’s send, and the monitor’s recv.</p>
</div>
<div class="section" id="custom-messages">
<h2>Custom Messages<a class="headerlink" href="#custom-messages" title="Permalink to this headline">¶</a></h2>
<div class="versionadded">
<p><span class="versionmodified">New in version 4.1.</span></p>
</div>
<p>IPython 2.0 (msgspec v4.1) adds a messaging system for developers to add their own objects with Frontend
and Kernel-side components, and allow them to communicate with each other.
To do this, IPython adds a notion of a <tt class="docutils literal"><span class="pre">Comm</span></tt>, which exists on both sides,
and can communicate in either direction.</p>
<p>These messages are fully symmetrical - both the Kernel and the Frontend can send each message,
and no messages expect a reply.
The Kernel listens for these messages on the Shell channel,
and the Frontend listens for them on the IOPub channel.</p>
<div class="section" id="opening-a-comm">
<h3>Opening a Comm<a class="headerlink" href="#opening-a-comm" title="Permalink to this headline">¶</a></h3>
<p>Opening a Comm produces a <tt class="docutils literal"><span class="pre">comm_open</span></tt> message, to be sent to the other side:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
<span class="s">'comm_id'</span> <span class="p">:</span> <span class="s">'u-u-i-d'</span><span class="p">,</span>
<span class="s">'target_name'</span> <span class="p">:</span> <span class="s">'my_comm'</span><span class="p">,</span>
<span class="s">'data'</span> <span class="p">:</span> <span class="p">{}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Every Comm has an ID and a target name.
The code handling the message on the receiving side is responsible for maintaining a mapping
of target_name keys to constructors.
After a <tt class="docutils literal"><span class="pre">comm_open</span></tt> message has been sent,
there should be a corresponding Comm instance on both sides.
The <tt class="docutils literal"><span class="pre">data</span></tt> key is always a dict and can be any extra JSON information used in initialization of the comm.</p>
<p>If the <tt class="docutils literal"><span class="pre">target_name</span></tt> key is not found on the receiving side,
then it should immediately reply with a <tt class="docutils literal"><span class="pre">comm_close</span></tt> message to avoid an inconsistent state.</p>
</div>
<div class="section" id="comm-messages">
<h3>Comm Messages<a class="headerlink" href="#comm-messages" title="Permalink to this headline">¶</a></h3>
<p>Comm messages are one-way communications to update comm state,
used for synchronizing widget state, or simply requesting actions of a comm’s counterpart.</p>
<p>Essentially, each comm pair defines their own message specification implemented inside the <tt class="docutils literal"><span class="pre">data</span></tt> dict.</p>
<p>There are no expected replies (of course, one side can send another <tt class="docutils literal"><span class="pre">comm_msg</span></tt> in reply).</p>
<p>Message type: <tt class="docutils literal"><span class="pre">comm_msg</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
<span class="s">'comm_id'</span> <span class="p">:</span> <span class="s">'u-u-i-d'</span><span class="p">,</span>
<span class="s">'data'</span> <span class="p">:</span> <span class="p">{}</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="tearing-down-comms">
<h3>Tearing Down Comms<a class="headerlink" href="#tearing-down-comms" title="Permalink to this headline">¶</a></h3>
<p>Since comms live on both sides, when a comm is destroyed the other side must be notified.
This is done with a <tt class="docutils literal"><span class="pre">comm_close</span></tt> message.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">comm_close</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
<span class="s">'comm_id'</span> <span class="p">:</span> <span class="s">'u-u-i-d'</span><span class="p">,</span>
<span class="s">'data'</span> <span class="p">:</span> <span class="p">{}</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="output-side-effects">
<h3>Output Side Effects<a class="headerlink" href="#output-side-effects" title="Permalink to this headline">¶</a></h3>
<p>Since comm messages can execute arbitrary user code,
handlers should set the parent header and publish status busy / idle,
just like an execute request.</p>
</div>
</div>
<div class="section" id="todo">
<h2>ToDo<a class="headerlink" href="#todo" title="Permalink to this headline">¶</a></h2>
<p>Missing things include:</p>
<ul class="simple">
<li>Important: finish thinking through the payload concept and API.</li>
<li>Important: ensure that we have a good solution for magics like %edit. It’s
likely that with the payload concept we can build a full solution, but not
100% clear yet.</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="parallel_messages.html" title="Messaging for Parallel Computing"
>next</a> |</li>
<li class="right" >
<a href="index.html" title="IPython developer’s guide"
>previous</a> |</li>
<li><a href="http://ipython.org">home</a>| </li>
<li><a href="../search.html">search</a>| </li>
<li><a href="../index.html">documentation </a> »</li>
<li><a href="index.html" >IPython developer’s guide</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright The IPython Development Team.
Last updated on Sep 02, 2015.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
</div>
</body>
</html>
distrib
>
Mageia
>
5
>
x86_64
>
media
>
core-updates
>
by-pkgid
>
c044f82ec6193fba7e13c97913613b07
>
files
>
948
