messaging.rst
1063 lines
| 35.6 KiB
| text/x-rst
|
RstLexer
|
r2790 | .. _messaging: | ||
|
r2735 | ====================== | ||
Messaging in IPython | ||||
====================== | ||||
|
r2727 | |||
|
r14975 | Versioning | ||
========== | ||||
The IPython message specification is versioned independently of IPython. | ||||
|
r16665 | The current version of the specification is 5.0. | ||
|
r14975 | |||
|
r2735 | Introduction | ||
============ | ||||
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 ZeroMQ_ library for messaging | ||||
within and between hosts. | ||||
.. Note:: | ||||
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. | ||||
The basic design is explained in the following diagram: | ||||
|
r4423 | .. image:: figs/frontend-kernel.png | ||
|
r2735 | :width: 450px | ||
:alt: IPython kernel/frontend messaging architecture. | ||||
:align: center | ||||
:target: ../_images/frontend-kernel.png | ||||
A single kernel can be simultaneously connected to one or more frontends. The | ||||
kernel has three sockets that serve the following functions: | ||||
|
r16594 | 1. Shell: this single ROUTER socket allows multiple incoming connections from | ||
|
r2735 | 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. | ||||
|
r16594 | 2. IOPub: this socket is the 'broadcast channel' where the kernel publishes all | ||
|
r2735 | side effects (stdout, stderr, etc.) as well as the requests coming from any | ||
|
r4953 | client over the shell socket and its own requests on the stdin socket. There | ||
|
r2735 | are a number of actions in Python which generate side effects: :func:`print` | ||
writes to ``sys.stdout``, 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 | ||||
|
r4953 | about communications taking place with one client over the shell channel | ||
|
r2735 | to be made available to all clients in a uniform manner. | ||
|
r16594 | 3. stdin: this ROUTER socket is connected to all frontends, and it allows | ||
the kernel to request input from the active frontend when :func:`raw_input` 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. | ||||
|
r2735 | 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. | ||||
|
r16594 | 4. Control: This channel is identical to Shell, but operates on a separate socket, | ||
to allow important messages to avoid queueing behind execution requests (e.g. shutdown or abort). | ||||
|
r2735 | 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. | ||||
.. Note:: | ||||
Not all of these have yet been fully fleshed out, but the key ones are, see | ||||
kernel and frontend files for actual implementation details. | ||||
|
r2599 | General Message Format | ||
====================== | ||||
|
r7952 | A message is defined by the following four-dictionary structure:: | ||
|
r7656 | |||
|
r2735 | { | ||
# The message header contains a pair of unique identifiers for the | ||||
# originating session and the actual message id, in addition to the | ||||
# username for the process that generated the message. This is useful in | ||||
# collaborative settings where multiple users may be interacting with the | ||||
# same kernel simultaneously, so that frontends can label the various | ||||
# messages in a meaningful way. | ||||
|
r4235 | 'header' : { | ||
'msg_id' : uuid, | ||||
'username' : str, | ||||
|
r11700 | 'session' : uuid, | ||
|
r4235 | # All recognized message type strings are listed below. | ||
'msg_type' : str, | ||||
|
r16572 | # the message protocol version | ||
|
r16665 | 'version' : '5.0', | ||
|
r2803 | }, | ||
|
r2600 | |||
|
r2735 | # In a chain of messages, the header from the parent is copied so that | ||
# clients can track where messages come from. | ||||
'parent_header' : dict, | ||||
|
r7952 | |||
|
r7955 | # Any metadata associated with the message. | ||
|
r7952 | 'metadata' : dict, | ||
|
r11698 | |||
# The actual content of the message must be a dict, whose structure | ||||
# depends on the message type. | ||||
'content' : dict, | ||||
|
r2727 | } | ||
|
r16665 | .. versionchanged:: 5.0 | ||
|
r16594 | |||
``version`` key added to the header. | ||||
|
r11658 | The Wire Protocol | ||
================= | ||||
|
r11698 | |||
|
r11658 | This message format exists at a high level, | ||
but does not describe the actual *implementation* at the wire level in zeromq. | ||||
The canonical implementation of the message spec is our :class:`~IPython.kernel.zmq.session.Session` class. | ||||
|
r11698 | |||
.. note:: | ||||
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 :class:`IPython.kernel.zmq.session.Session` object. | ||||
|
r11658 | Every message is serialized to a sequence of at least six blobs of bytes: | ||
.. sourcecode:: python | ||||
[ | ||||
b'u-u-i-d', # zmq identity(ies) | ||||
b'<IDS|MSG>', # delimiter | ||||
b'baddad42', # HMAC signature | ||||
b'{header}', # serialized header dict | ||||
b'{parent_header}', # serialized parent header dict | ||||
b'{metadata}', # serialized metadata dict | ||||
b'{content}, # serialized content dict | ||||
b'blob', # extra raw data buffer(s) | ||||
... | ||||
] | ||||
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 ``<IDS|MSG>``. | ||||
|
r11698 | In the case of IOPub, there should be just one prefix component, | ||
|
r16572 | which is the topic for IOPub subscribers, e.g. ``execute_result``, ``display_data``. | ||
|
r11658 | |||
.. note:: | ||||
In most cases, the IOPub topics are irrelevant and completely ignored, | ||||
because frontends just subscribe to all topics. | ||||
|
r11698 | The convention used in the IPython kernel is to use the msg_type as the topic, | ||
|
r16572 | and possibly extra information about the message, e.g. ``execute_result`` or ``stream.stdout`` | ||
|
r11658 | |||
After the delimiter is the `HMAC`_ 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. | ||||
.. _HMAC: http://en.wikipedia.org/wiki/HMAC | ||||
.. note:: | ||||
To disable authentication and signature checking, | ||||
set the `key` field of a connection file to an empty string. | ||||
|
r11698 | The signature is the HMAC hex digest of the concatenation of: | ||
|
r11658 | |||
|
r11698 | - A shared key (typically the ``key`` field of a connection file) | ||
|
r11658 | - The serialized header dict | ||
- The serialized parent header dict | ||||
- The serialized metadata dict | ||||
- The serialized content dict | ||||
|
r11698 | In Python, this is implemented via: | ||
.. sourcecode:: python | ||||
# once: | ||||
digester = HMAC(key, digestmod=hashlib.sha256) | ||||
# for each message | ||||
d = digester.copy() | ||||
for serialized_dict in (header, parent, metadata, content): | ||||
d.update(serialized_dict) | ||||
signature = d.hexdigest() | ||||
After the signature is the actual message, always in four frames of bytes. | ||||
|
r11658 | 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. | ||||
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). | ||||
|
r7656 | Python functional API | ||
===================== | ||||
As messages are dicts, they map naturally to a ``func(**kw)`` 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. | ||||
In addition, the Python implementation of the message specification extends | ||||
messages upon deserialization to the following form for convenience:: | ||||
{ | ||||
'header' : dict, | ||||
# The msg's unique identifier and type are always stored in the header, | ||||
# but the Python implementation copies them to the top level. | ||||
'msg_id' : uuid, | ||||
'msg_type' : str, | ||||
|
r7660 | 'parent_header' : dict, | ||
'content' : dict, | ||||
|
r7955 | 'metadata' : dict, | ||
|
r7656 | } | ||
All messages sent to or received by any IPython process should have this | ||||
extended structure. | ||||
|
r2727 | |||
|
r2600 | |||
|
r4953 | Messages on the shell ROUTER/DEALER sockets | ||
=========================================== | ||||
|
r2600 | |||
|
r2735 | .. _execute: | ||
|
r2599 | |||
Execute | ||||
------- | ||||
|
r2893 | 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). | ||||
|
r2885 | |||
|
r2735 | Message type: ``execute_request``:: | ||
|
r2600 | |||
content = { | ||||
|
r2735 | # Source code to be executed by the kernel, one or more lines. | ||
|
r2803 | 'code' : str, | ||
|
r5805 | # A boolean flag which, if True, signals the kernel to execute | ||
|
r16594 | # this code as quietly as possible. | ||
# silent=True forces store_history to be False, | ||||
|
r7999 | # and will *not*: | ||
|
r16594 | # - broadcast output on the IOPUB channel | ||
# - have an execute_result | ||||
|
r2803 | # The default is False. | ||
'silent' : bool, | ||||
|
r2885 | |||
|
r7981 | # A boolean flag which, if True, signals the kernel to populate history | ||
|
r7999 | # The default is True if silent is False. If silent is True, store_history | ||
# is forced to be False. | ||||
|
r7981 | 'store_history' : bool, | ||
|
r16594 | # A dict mapping names to expressions to be evaluated in the | ||
|
r16572 | # 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. | ||||
|
r2893 | 'user_expressions' : dict, | ||
|
r4953 | |||
|
r16572 | # Some frontends do not support stdin requests. | ||
# If raw_input is called from code executed from such a frontend, | ||||
# a StdinNotImplementedError will be raised. | ||||
|
r4953 | 'allow_stdin' : True, | ||
|
r2600 | } | ||
|
r2599 | |||
|
r16665 | .. versionchanged:: 5.0 | ||
|
r16594 | |||
``user_variables`` removed, because it is redundant with user_expressions. | ||||
The ``code`` field contains a single string (possibly multiline) to be executed. | ||||
|
r2893 | |||
|
r16594 | The ``user_expressions`` field deserves a detailed explanation. In the past, IPython had | ||
|
r2893 | 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 | ||||
|
r10340 | status acquired over the network. But now that IPython has a clean separation | ||
|
r3050 | between the kernel and the clients, the kernel has no prompt knowledge; prompts | ||
|
r16572 | are a frontend feature, and it should be even possible for different | ||
|
r3050 | frontends to display different prompts while interacting with the same kernel. | ||
|
r16594 | ``user_expressions`` can be used to retrieve this information. | ||
|
r3050 | |||
|
r16572 | Any error in evaluating any expression in ``user_expressions`` will result in | ||
only that key containing a standard error message, of the form:: | ||||
|
r3050 | |||
|
r16572 | { | ||
'status' : 'error', | ||||
'ename' : 'NameError', | ||||
'evalue' : 'foo', | ||||
'traceback' : ... | ||||
} | ||||
|
r3050 | |||
|
r16594 | .. Note:: | ||
In order to obtain the current execution counter for the purposes of | ||||
displaying input prompts, frontends may make an execution request with an | ||||
empty code string and ``silent=True``. | ||||
|
r3050 | |||
Upon completion of the execution request, the kernel *always* sends a reply, | ||||
with a status code indicating what happened and additional data depending on | ||||
the outcome. See :ref:`below <execution_results>` for the possible return | ||||
codes and associated data. | ||||
|
r2885 | |||
|
r16594 | .. seealso:: | ||
:ref:`execution_semantics` | ||||
|
r2885 | |||
|
r15002 | .. _execution_counter: | ||
|
r16572 | Execution counter (prompt number) | ||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||||
|
r3050 | |||
|
r16594 | The kernel should have a single, monotonically increasing counter of all execution | ||
requests that are made with ``store_history=True``. This counter is used to populate | ||||
the ``In[n]`` and ``Out[n]`` prompts. The value of this counter will be returned as the | ||||
``execution_count`` field of all ``execute_reply`` and ``execute_input`` messages. | ||||
|
r3050 | |||
.. _execution_results: | ||||
|
r2599 | |||
|
r3050 | Execution results | ||
~~~~~~~~~~~~~~~~~ | ||||
|
r2735 | Message type: ``execute_reply``:: | ||
|
r2600 | |||
content = { | ||||
|
r2735 | # One of: 'ok' OR 'error' OR 'abort' | ||
'status' : str, | ||||
|
r7981 | # 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 | ||||
|
r2885 | # be the current value of the counter in the kernel. | ||
'execution_count' : int, | ||||
|
r2799 | } | ||
When status is 'ok', the following extra fields are present:: | ||||
|
r2727 | |||
|
r2799 | { | ||
|
r6553 | # 'payload' will be a list of payload dicts. | ||
# Each execution payload is a dict with string keys that may have been | ||||
|
r2735 | # produced by the code being executed. It is retrieved by the kernel at | ||
# the end of the execution and sent back to the front end, which can take | ||||
|
r13219 | # action on it as needed. | ||
# The only requirement of each payload dict is that it have a 'source' key, | ||||
# which is a string classifying the payload (e.g. 'pager'). | ||||
|
r6553 | 'payload' : list(dict), | ||
|
r2926 | |||
|
r16572 | # Results for the user_expressions. | ||
|
r2926 | 'user_expressions' : dict, | ||
|
r6553 | } | ||
|
r2727 | |||
|
r16665 | .. versionchanged:: 5.0 | ||
|
r16594 | |||
``user_variables`` is removed, use user_expressions instead. | ||||
|
r2735 | .. admonition:: Execution payloads | ||
The notion of an 'execution payload' is different from a return value of a | ||||
|
r16572 | given set of code, which normally is just displayed on the execute_result stream | ||
|
r2735 | 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 | ||||
|
r6553 | that will be shipped back to the caller via this channel. The kernel | ||
has an API for this in the PayloadManager:: | ||||
|
r2735 | |||
|
r6553 | ip.payload_manager.write_payload(payload_dict) | ||
|
r2735 | |||
|
r6553 | which appends a dictionary to the list of payloads. | ||
|
r11858 | |||
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. | ||||
|
r2735 | |||
|
r2727 | When status is 'error', the following extra fields are present:: | ||
{ | ||||
|
r6555 | 'ename' : str, # Exception name, as a string | ||
'evalue' : str, # Exception value, as a string | ||||
|
r2727 | |||
# The traceback will contain a list of frames, represented each as a | ||||
# string. For now we'll stick to the existing design of ultraTB, which | ||||
# controls exception level of detail statefully. But eventually we'll | ||||
# want to grow into a model where more information is collected and | ||||
# packed into the traceback object, with clients deciding how little or | ||||
# how much of it to unpack. But for now, let's start with a simple list | ||||
# of strings, since that requires only minimal changes to ultratb as | ||||
# written. | ||||
|
r2735 | 'traceback' : list, | ||
|
r2727 | } | ||
|
r2735 | When status is 'abort', there are for now no additional data fields. This | ||
happens when the kernel was interrupted by a signal. | ||||
|
r2727 | |||
|
r16859 | .. _msging_inspection: | ||
|
r2727 | |||
|
r16594 | Introspection | ||
------------- | ||||
|
r2735 | |||
|
r16594 | 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. | ||||
|
r2735 | |||
|
r16594 | Message type: ``inspect_request``:: | ||
|
r2735 | |||
content = { | ||||
|
r16594 | # 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, | ||||
|
r2735 | |||
|
r16594 | # The level of detail desired. In IPython, the default (0) is equivalent to typing | ||
|
r11696 | # 'x?' at the prompt, 1 is equivalent to 'x??'. | ||
|
r16594 | # The difference is up to kernels, but in IPython level 1 includes the source code | ||
# if available. | ||||
'detail_level' : 0 or 1, | ||||
|
r2735 | } | ||
|
r16665 | .. versionchanged:: 5.0 | ||
|
r16594 | |||
``object_info_request`` renamed to ``inspect_request``. | ||||
|
r16665 | .. versionchanged:: 5.0 | ||
|
r16594 | |||
``name`` key replaced with ``code`` and ``cursor_pos``, | ||||
moving the lexing responsibility to the kernel. | ||||
The reply is a mime-bundle, like a `display_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``:: | ||||
|
r2735 | |||
content = { | ||||
|
r16594 | # 'ok' if the request succeeded or 'error', with error information as in all other replies. | ||
'status' : 'ok', | ||||
# data can be empty if nothing is found | ||||
'data' : dict, | ||||
'metadata' : dict, | ||||
|
r2735 | } | ||
|
r7660 | |||
|
r16665 | .. versionchanged:: 5.0 | ||
|
r16594 | |||
``object_info_reply`` renamed to ``inspect_reply``. | ||||
|
r16665 | .. versionchanged:: 5.0 | ||
|
r16594 | |||
Reply is changed from structured data to a mime bundle, allowing formatting decisions to be made by the kernel. | ||||
|
r16859 | .. _msging_completion: | ||
|
r16594 | Completion | ||
---------- | ||||
|
r2599 | |||
|
r2735 | Message type: ``complete_request``:: | ||
|
r2599 | |||
|
r2600 | content = { | ||
|
r16594 | # 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 | ||||
|
r11696 | 'cursor_pos' : int, | ||
|
r2600 | } | ||
|
r16665 | .. versionchanged:: 5.0 | ||
|
r16594 | |||
``line``, ``block``, and ``text`` keys are removed in favor of a single ``code`` for context. | ||||
Lexing is up to the kernel. | ||||
|
r2735 | Message type: ``complete_reply``:: | ||
|
r2600 | |||
content = { | ||||
|
r11696 | # The list of all matches to the completion request, such as | ||
|
r2803 | # ['a.isalnum', 'a.isalpha'] for the above example. | ||
|
r11696 | 'matches' : list, | ||
|
r16594 | # 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, | ||||
|
r11696 | |||
# 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' | ||||
|
r2600 | } | ||
|
r2599 | |||
|
r16665 | .. versionchanged:: 5.0 | ||
|
r16594 | |||
- ``matched_text`` is removed in favor of ``cursor_start`` and ``cursor_end``. | ||||
- ``metadata`` is added for extended information. | ||||
|
r16859 | .. _msging_history: | ||
|
r16594 | |||
|
r2727 | History | ||
------- | ||||
|
r2735 | 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. | ||||
|
r2727 | |||
|
r2735 | Message type: ``history_request``:: | ||
|
r2727 | |||
content = { | ||||
|
r2735 | |||
|
r2794 | # If True, also return output history in the resulting dict. | ||
|
r2735 | 'output' : bool, | ||
|
r2794 | # If True, return the raw input history, else the transformed input. | ||
'raw' : bool, | ||||
|
r3818 | # 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 can | ||||
# be a positive session number, or a negative number to count back from | ||||
# the current session. | ||||
'session' : int, | ||||
# start and stop are line numbers within that session. | ||||
'start' : int, | ||||
'stop' : int, | ||||
|
r8401 | # If hist_access_type is 'tail' or 'search', get the last n cells. | ||
|
r3818 | 'n' : int, | ||
# If hist_access_type is 'search', get cells matching the specified glob | ||||
# pattern (with * and ? as wildcards). | ||||
'pattern' : str, | ||||
|
r9414 | |||
# If hist_access_type is 'search' and unique is true, do not | ||||
# include duplicated history. Default is false. | ||||
'unique' : bool, | ||||
|
r3818 | |||
|
r2727 | } | ||
|
r9416 | .. versionadded:: 4.0 | ||
The key ``unique`` for ``history_request``. | ||||
|
r2735 | Message type: ``history_reply``:: | ||
|
r2727 | |||
content = { | ||||
|
r3818 | # 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, | ||||
|
r2794 | } | ||
|
r2972 | |||
|
r3019 | Connect | ||
------- | ||||
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 | ||||
|
r4953 | to know about a single port (the shell channel) to connect to a kernel. | ||
|
r3019 | |||
Message type: ``connect_request``:: | ||||
content = { | ||||
} | ||||
Message type: ``connect_reply``:: | ||||
content = { | ||||
|
r11696 | '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. | ||||
|
r3019 | } | ||
|
r16859 | .. _msging_kernel_info: | ||
|
r3019 | |||
|
r8879 | Kernel info | ||
----------- | ||||
|
r8876 | |||
|
r11696 | 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 | ||||
|
r8876 | kernel, including language (e.g., Python), language version number and | ||
|
r11696 | IPython version number, and the IPython message spec version number. | ||
|
r8876 | |||
|
r8879 | Message type: ``kernel_info_request``:: | ||
|
r8876 | |||
content = { | ||||
} | ||||
|
r8879 | Message type: ``kernel_info_reply``:: | ||
|
r8876 | |||
content = { | ||||
|
r16594 | # Version of messaging protocol. | ||
|
r8876 | # 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. | ||||
|
r16572 | 'protocol_version': 'X.Y.Z', | ||
|
r8876 | |||
|
r16594 | # 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', | ||||
|
r8876 | |||
|
r16594 | # Programming language in which kernel is implemented. | ||
# Kernel included in IPython returns 'python'. | ||||
'language': str, | ||||
# Language version number. | ||||
|
r16572 | # It is Python version number (e.g., '2.7.3') for the kernel | ||
|
r8876 | # included in IPython. | ||
|
r16572 | 'language_version': 'X.Y.Z', | ||
|
r8876 | |||
|
r16594 | # A banner of information about the kernel, | ||
# which may be desplayed in console environments. | ||||
'banner' : str, | ||||
|
r8876 | } | ||
|
r16665 | .. versionchanged:: 5.0 | ||
|
r16594 | |||
Versions changed from lists of integers to strings. | ||||
|
r16665 | .. versionchanged:: 5.0 | ||
|
r16594 | |||
``ipython_version`` is removed. | ||||
|
r16572 | |||
|
r16665 | .. versionchanged:: 5.0 | ||
|
r16594 | |||
``implementation``, ``implementation_version``, and ``banner`` keys are added. | ||||
|
r16572 | |||
|
r16859 | .. _msging_shutdown: | ||
|
r3019 | |||
|
r2972 | Kernel shutdown | ||
--------------- | ||||
The clients can request the kernel to shut itself down; this is used in | ||||
multiple cases: | ||||
- when the user chooses to close the client application via a menu or window | ||||
control. | ||||
- 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 the | ||||
IPythonQt client) to force a kernel restart to get a clean kernel without | ||||
losing client-side state like history or inlined figures. | ||||
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. | ||||
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. | ||||
Message type: ``shutdown_request``:: | ||||
content = { | ||||
|
r3100 | 'restart' : bool # whether the shutdown is final, or precedes a restart | ||
|
r2972 | } | ||
Message type: ``shutdown_reply``:: | ||||
content = { | ||||
|
r3100 | 'restart' : bool # whether the shutdown is final, or precedes a restart | ||
|
r2972 | } | ||
.. Note:: | ||||
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. | ||||
|
r2893 | |||
|
r2972 | |||
|
r2735 | Messages on the PUB/SUB socket | ||
============================== | ||||
Streams (stdout, stderr, etc) | ||||
------------------------------ | ||||
Message type: ``stream``:: | ||||
content = { | ||||
|
r11696 | # The name of the stream is one of 'stdout', 'stderr' | ||
|
r3278 | 'name' : str, | ||
|
r2803 | |||
|
r3278 | # The data is an arbitrary string to be written to that stream | ||
'data' : str, | ||||
|
r2735 | } | ||
|
r3277 | Display Data | ||
------------ | ||||
|
r3275 | |||
|
r13880 | This type of message is used to bring back data that should be displayed (text, | ||
|
r3277 | 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. | ||||
|
r3275 | |||
|
r16572 | Some questions remain about this design: | ||
* Do we use this message type for execute_result/displayhook? Probably not, because | ||||
the displayhook also has to handle the Out prompt display. On the other hand | ||||
|
r16594 | we could put that information into the metadata section. | ||
.. _display_data: | ||||
|
r16572 | |||
|
r3277 | Message type: ``display_data``:: | ||
|
r3275 | |||
content = { | ||||
|
r3278 | # Who create the data | ||
'source' : str, | ||||
|
r3277 | |||
|
r13880 | # The data dict contains key/value pairs, where the keys are MIME | ||
|
r3278 | # types and the values are the raw data of the representation in that | ||
|
r10465 | # format. | ||
|
r3278 | 'data' : dict, | ||
|
r3275 | |||
|
r3278 | # Any metadata that describes the data | ||
'metadata' : dict | ||||
|
r3275 | } | ||
|
r8110 | |||
|
r10465 | The ``metadata`` contains any metadata that describes the output. | ||
Global keys are assumed to apply to the output as a whole. | ||||
The ``metadata`` 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. | ||||
The only metadata keys currently defined in IPython are the width and height | ||||
of images:: | ||||
|
r16594 | metadata = { | ||
|
r10465 | 'image/png' : { | ||
'width': 640, | ||||
'height': 480 | ||||
} | ||||
} | ||||
|
r16665 | .. versionchanged:: 5.0 | ||
|
r16594 | |||
`application/json` data should be unpacked JSON data, | ||||
not double-serialized as a JSON string. | ||||
|
r8110 | Raw Data Publication | ||
-------------------- | ||||
``display_data`` lets you publish *representations* of data, such as images and html. | ||||
This ``data_pub`` message lets you publish *actual raw data*, sent via message buffers. | ||||
data_pub messages are constructed via the :func:`IPython.lib.datapub.publish_data` function: | ||||
.. sourcecode:: python | ||||
|
r9455 | from IPython.kernel.zmq.datapub import publish_data | ||
|
r8110 | ns = dict(x=my_array) | ||
publish_data(ns) | ||||
Message type: ``data_pub``:: | ||||
content = { | ||||
# the keys of the data dict, after it has been unserialized | ||||
|
r16594 | 'keys' : ['a', 'b'] | ||
|
r8110 | } | ||
# the namespace dict will be serialized in the message buffers, | ||||
# which will have a length of at least one | ||||
|
r16594 | buffers = [b'pdict', ...] | ||
|
r8110 | |||
The interpretation of a sequence of data_pub messages for a given parent request should be | ||||
to update a single namespace with subsequent results. | ||||
.. note:: | ||||
No frontends directly handle data_pub messages at this time. | ||||
It is currently only used by the client/engines in :mod:`IPython.parallel`, | ||||
where engines may publish *data* to the Client, | ||||
of which the Client can then publish *representations* via ``display_data`` | ||||
to various frontends. | ||||
|
r16594 | Code inputs | ||
----------- | ||||
|
r2735 | |||
|
r15002 | To let all frontends know what code is being executed at any given time, these | ||
messages contain a re-broadcast of the ``code`` portion of an | ||||
:ref:`execute_request <execute>`, along with the :ref:`execution_count | ||||
<execution_counter>`. | ||||
|
r2735 | |||
|
r16594 | Message type: ``execute_input``:: | ||
|
r2735 | |||
content = { | ||||
|
r6544 | '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 | ||||
|
r2735 | } | ||
|
r16665 | .. versionchanged:: 5.0 | ||
|
r16594 | |||
``pyin`` is renamed to ``execute_input``. | ||||
|
r2735 | |||
|
r16594 | Execution results | ||
----------------- | ||||
Results of an execution are published as an ``execute_result``. | ||||
These are identical to `display_data`_ messages, with the addition of an ``execution_count`` key. | ||||
Results can have multiple simultaneous formats depending on its | ||||
configuration. A plain text representation should always be provided | ||||
in the ``text/plain`` mime-type. Frontends are free to display any or all of these | ||||
according to its capabilities. | ||||
Frontends should ignore mime-types they do not understand. The data itself is | ||||
|
r3215 | any JSON object and depends on the format. It is often, but not always a string. | ||
|
r16572 | Message type: ``execute_result``:: | ||
|
r2735 | |||
content = { | ||||
|
r3278 | |||
|
r3215 | # 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, | ||||
|
r16594 | |||
|
r11822 | # 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. | ||||
|
r3278 | 'data' : dict, | ||
|
r11822 | 'metadata' : dict, | ||
|
r2735 | } | ||
|
r16594 | |||
Execution errors | ||||
---------------- | ||||
|
r2735 | |||
When an error occurs during code execution | ||||
|
r16572 | Message type: ``error``:: | ||
|
r2735 | |||
content = { | ||||
# Similar content to the execute_reply messages for the 'error' case, | ||||
# except the 'status' field is omitted. | ||||
} | ||||
|
r16665 | .. versionchanged:: 5.0 | ||
|
r16594 | |||
``pyerr`` renamed to ``error`` | ||||
|
r3035 | Kernel status | ||
------------- | ||||
This message type is used by frontends to monitor the status of the kernel. | ||||
Message type: ``status``:: | ||||
content = { | ||||
|
r17099 | # When the kernel starts to handle a message, it will enter the 'busy' | ||
|
r3035 | # state and when it finishes, it will enter the 'idle' state. | ||
|
r10340 | # The kernel will publish state 'starting' exactly once at process startup. | ||
execution_state : ('busy', 'idle', 'starting') | ||||
|
r3035 | } | ||
|
r2735 | |||
|
r17099 | .. versionchanged:: 5.0 | ||
|
r17117 | Busy and idle messages should be sent before/after handling every message, | ||
|
r17099 | not just execution. | ||
|
r12592 | 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, | ||||
} | ||||
|
r2735 | |||
|
r14975 | .. versionchanged:: 4.1 | ||
|
r16594 | ``stdout``, ``stderr``, and ``display`` boolean keys for selective clearing are removed, | ||
and ``wait`` is added. | ||||
|
r14975 | 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. | ||||
|
r4953 | Messages on the stdin ROUTER/DEALER sockets | ||
=========================================== | ||||
This is a socket where the request/reply pattern goes in the opposite direction: | ||||
from the kernel to a *single* frontend, and its purpose is to allow | ||||
``raw_input`` and similar operations that read from ``sys.stdin`` on the kernel | ||||
to be fulfilled by the client. The request should be made to the frontend that | ||||
made the execution request that prompted ``raw_input`` to be called. For now we | ||||
will keep these messages as simple as possible, since they only mean to convey | ||||
the ``raw_input(prompt)`` call. | ||||
|
r2735 | |||
Message type: ``input_request``:: | ||||
|
r16594 | content = { | ||
# the text to show at the prompt | ||||
'prompt' : str, | ||||
# Is the request for a password? | ||||
# If so, the frontend shouldn't echo input. | ||||
'password' : bool | ||||
} | ||||
|
r2735 | |||
Message type: ``input_reply``:: | ||||
content = { 'value' : str } | ||||
|
r16575 | |||
When ``password`` is True, the frontend should not echo the input as it is entered. | ||||
|
r16665 | .. versionchanged:: 5.0 | ||
|
r16575 | |||
|
r16594 | ``password`` key added. | ||
|
r16575 | |||
|
r13577 | .. note:: | ||
The stdin socket of the client is required to have the same zmq IDENTITY | ||||
as the client's shell socket. | ||||
Because of this, the ``input_request`` must be sent with the same IDENTITY | ||||
routing prefix as the ``execute_reply`` in order for the frontend to receive | ||||
the message. | ||||
.. note:: | ||||
|
r2735 | |||
We do not explicitly try to forward the raw ``sys.stdin`` 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 | ||||
``stdin`` 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 ``stdin`` isn't expected to be | ||||
available. | ||||
|
r16594 | |||
|
r2743 | Heartbeat for kernels | ||
===================== | ||||
|
r16594 | Clients send ping messages on a REQ socket, which are echoed right back | ||
from the Kernel's REP socket. These are simple bytestrings, not full JSON messages described above. | ||||
|
r2743 | |||
|
r13211 | Custom Messages | ||
|
r13190 | =============== | ||
|
r14975 | .. versionadded:: 4.1 | ||
IPython 2.0 (msgspec v4.1) adds a messaging system for developers to add their own objects with Frontend | ||||
|
r13211 | and Kernel-side components, and allow them to communicate with each other. | ||
To do this, IPython adds a notion of a ``Comm``, which exists on both sides, | ||||
and can communicate in either direction. | ||||
These messages are fully symmetrical - both the Kernel and the Frontend can send each message, | ||||
|
r13193 | 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. | ||||
|
r13190 | |||
|
r13211 | Opening a Comm | ||
-------------- | ||||
|
r13190 | |||
|
r13211 | Opening a Comm produces a ``comm_open`` message, to be sent to the other side:: | ||
|
r13190 | |||
{ | ||||
|
r13211 | 'comm_id' : 'u-u-i-d', | ||
'target_name' : 'my_comm', | ||||
|
r13190 | 'data' : {} | ||
} | ||||
|
r13211 | Every Comm has an ID and a target name. | ||
|
r13193 | The code handling the message on the receiving side is responsible for maintaining a mapping | ||
|
r13211 | of target_name keys to constructors. | ||
After a ``comm_open`` message has been sent, | ||||
there should be a corresponding Comm instance on both sides. | ||||
The ``data`` key is always a dict and can be any extra JSON information used in initialization of the comm. | ||||
|
r13190 | |||
|
r13211 | If the ``target_name`` key is not found on the receiving side, | ||
then it should immediately reply with a ``comm_close`` message to avoid an inconsistent state. | ||||
Comm Messages | ||||
------------- | ||||
|
r13190 | |||
|
r13211 | Comm messages are one-way communications to update comm state, | ||
used for synchronizing widget state, or simply requesting actions of a comm's counterpart. | ||||
|
r13190 | |||
|
r13211 | Essentially, each comm pair defines their own message specification implemented inside the ``data`` dict. | ||
|
r13190 | |||
|
r13211 | There are no expected replies (of course, one side can send another ``comm_msg`` in reply). | ||
|
r13190 | |||
|
r13211 | Message type: ``comm_msg``:: | ||
|
r13190 | |||
{ | ||||
|
r13211 | 'comm_id' : 'u-u-i-d', | ||
|
r13190 | 'data' : {} | ||
} | ||||
|
r13211 | Tearing Down Comms | ||
------------------ | ||||
|
r13190 | |||
|
r13211 | Since comms live on both sides, when a comm is destroyed the other side must be notified. | ||
This is done with a ``comm_close`` message. | ||||
|
r13190 | |||
|
r13211 | Message type: ``comm_close``:: | ||
|
r13190 | |||
{ | ||||
|
r13211 | 'comm_id' : 'u-u-i-d', | ||
|
r13190 | 'data' : {} | ||
} | ||||
|
r13211 | 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. | ||||
|
r2735 | |||
|
r16594 | To Do | ||
===== | ||||
|
r2735 | |||
Missing things include: | ||||
* Important: finish thinking through the payload concept and API. | ||||
|
r11730 | .. include:: ../links.txt | ||