Show More
@@ -1,1216 +1,1219 | |||
|
1 | 1 | .. _messaging: |
|
2 | 2 | |
|
3 | 3 | ====================== |
|
4 | 4 | Messaging in IPython |
|
5 | 5 | ====================== |
|
6 | 6 | |
|
7 | 7 | |
|
8 | 8 | Versioning |
|
9 | 9 | ========== |
|
10 | 10 | |
|
11 | 11 | The IPython message specification is versioned independently of IPython. |
|
12 | 12 | The current version of the specification is 5.0. |
|
13 | 13 | |
|
14 | 14 | |
|
15 | 15 | Introduction |
|
16 | 16 | ============ |
|
17 | 17 | |
|
18 | 18 | This document explains the basic communications design and messaging |
|
19 | 19 | specification for how the various IPython objects interact over a network |
|
20 | 20 | transport. The current implementation uses the ZeroMQ_ library for messaging |
|
21 | 21 | within and between hosts. |
|
22 | 22 | |
|
23 | 23 | .. Note:: |
|
24 | 24 | |
|
25 | 25 | This document should be considered the authoritative description of the |
|
26 | 26 | IPython messaging protocol, and all developers are strongly encouraged to |
|
27 | 27 | keep it updated as the implementation evolves, so that we have a single |
|
28 | 28 | common reference for all protocol details. |
|
29 | 29 | |
|
30 | 30 | The basic design is explained in the following diagram: |
|
31 | 31 | |
|
32 | 32 | .. image:: figs/frontend-kernel.png |
|
33 | 33 | :width: 450px |
|
34 | 34 | :alt: IPython kernel/frontend messaging architecture. |
|
35 | 35 | :align: center |
|
36 | 36 | :target: ../_images/frontend-kernel.png |
|
37 | 37 | |
|
38 | 38 | A single kernel can be simultaneously connected to one or more frontends. The |
|
39 | 39 | kernel has three sockets that serve the following functions: |
|
40 | 40 | |
|
41 | 41 | 1. Shell: this single ROUTER socket allows multiple incoming connections from |
|
42 | 42 | frontends, and this is the socket where requests for code execution, object |
|
43 | 43 | information, prompts, etc. are made to the kernel by any frontend. The |
|
44 | 44 | communication on this socket is a sequence of request/reply actions from |
|
45 | 45 | each frontend and the kernel. |
|
46 | 46 | |
|
47 | 47 | 2. IOPub: this socket is the 'broadcast channel' where the kernel publishes all |
|
48 | 48 | side effects (stdout, stderr, etc.) as well as the requests coming from any |
|
49 | 49 | client over the shell socket and its own requests on the stdin socket. There |
|
50 | 50 | are a number of actions in Python which generate side effects: :func:`print` |
|
51 | 51 | writes to ``sys.stdout``, errors generate tracebacks, etc. Additionally, in |
|
52 | 52 | a multi-client scenario, we want all frontends to be able to know what each |
|
53 | 53 | other has sent to the kernel (this can be useful in collaborative scenarios, |
|
54 | 54 | for example). This socket allows both side effects and the information |
|
55 | 55 | about communications taking place with one client over the shell channel |
|
56 | 56 | to be made available to all clients in a uniform manner. |
|
57 | 57 | |
|
58 | 58 | 3. stdin: this ROUTER socket is connected to all frontends, and it allows |
|
59 | 59 | the kernel to request input from the active frontend when :func:`raw_input` is called. |
|
60 | 60 | The frontend that executed the code has a DEALER socket that acts as a 'virtual keyboard' |
|
61 | 61 | for the kernel while this communication is happening (illustrated in the |
|
62 | 62 | figure by the black outline around the central keyboard). In practice, |
|
63 | 63 | frontends may display such kernel requests using a special input widget or |
|
64 | 64 | otherwise indicating that the user is to type input for the kernel instead |
|
65 | 65 | of normal commands in the frontend. |
|
66 | 66 | |
|
67 | 67 | All messages are tagged with enough information (details below) for clients |
|
68 | 68 | to know which messages come from their own interaction with the kernel and |
|
69 | 69 | which ones are from other clients, so they can display each type |
|
70 | 70 | appropriately. |
|
71 | 71 | |
|
72 | 72 | 4. Control: This channel is identical to Shell, but operates on a separate socket, |
|
73 | 73 | to allow important messages to avoid queueing behind execution requests (e.g. shutdown or abort). |
|
74 | 74 | |
|
75 | 75 | The actual format of the messages allowed on each of these channels is |
|
76 | 76 | specified below. Messages are dicts of dicts with string keys and values that |
|
77 | 77 | are reasonably representable in JSON. Our current implementation uses JSON |
|
78 | 78 | explicitly as its message format, but this shouldn't be considered a permanent |
|
79 | 79 | feature. As we've discovered that JSON has non-trivial performance issues due |
|
80 | 80 | to excessive copying, we may in the future move to a pure pickle-based raw |
|
81 | 81 | message format. However, it should be possible to easily convert from the raw |
|
82 | 82 | objects to JSON, since we may have non-python clients (e.g. a web frontend). |
|
83 | 83 | As long as it's easy to make a JSON version of the objects that is a faithful |
|
84 | 84 | representation of all the data, we can communicate with such clients. |
|
85 | 85 | |
|
86 | 86 | .. Note:: |
|
87 | 87 | |
|
88 | 88 | Not all of these have yet been fully fleshed out, but the key ones are, see |
|
89 | 89 | kernel and frontend files for actual implementation details. |
|
90 | 90 | |
|
91 | 91 | General Message Format |
|
92 | 92 | ====================== |
|
93 | 93 | |
|
94 | 94 | A message is defined by the following four-dictionary structure:: |
|
95 | 95 | |
|
96 | 96 | { |
|
97 | 97 | # The message header contains a pair of unique identifiers for the |
|
98 | 98 | # originating session and the actual message id, in addition to the |
|
99 | 99 | # username for the process that generated the message. This is useful in |
|
100 | 100 | # collaborative settings where multiple users may be interacting with the |
|
101 | 101 | # same kernel simultaneously, so that frontends can label the various |
|
102 | 102 | # messages in a meaningful way. |
|
103 | 103 | 'header' : { |
|
104 | 104 | 'msg_id' : uuid, |
|
105 | 105 | 'username' : str, |
|
106 | 106 | 'session' : uuid, |
|
107 | 107 | # All recognized message type strings are listed below. |
|
108 | 108 | 'msg_type' : str, |
|
109 | 109 | # the message protocol version |
|
110 | 110 | 'version' : '5.0', |
|
111 | 111 | }, |
|
112 | 112 | |
|
113 | 113 | # In a chain of messages, the header from the parent is copied so that |
|
114 | 114 | # clients can track where messages come from. |
|
115 | 115 | 'parent_header' : dict, |
|
116 | 116 | |
|
117 | 117 | # Any metadata associated with the message. |
|
118 | 118 | 'metadata' : dict, |
|
119 | 119 | |
|
120 | 120 | # The actual content of the message must be a dict, whose structure |
|
121 | 121 | # depends on the message type. |
|
122 | 122 | 'content' : dict, |
|
123 | 123 | } |
|
124 | 124 | |
|
125 | 125 | .. versionchanged:: 5.0 |
|
126 | 126 | |
|
127 | 127 | ``version`` key added to the header. |
|
128 | 128 | |
|
129 | 129 | .. _wire_protocol: |
|
130 | 130 | |
|
131 | 131 | The Wire Protocol |
|
132 | 132 | ================= |
|
133 | 133 | |
|
134 | 134 | |
|
135 | 135 | This message format exists at a high level, |
|
136 | 136 | but does not describe the actual *implementation* at the wire level in zeromq. |
|
137 | 137 | The canonical implementation of the message spec is our :class:`~IPython.kernel.zmq.session.Session` class. |
|
138 | 138 | |
|
139 | 139 | .. note:: |
|
140 | 140 | |
|
141 | 141 | This section should only be relevant to non-Python consumers of the protocol. |
|
142 | 142 | Python consumers should simply import and use IPython's own implementation of the wire protocol |
|
143 | 143 | in the :class:`IPython.kernel.zmq.session.Session` object. |
|
144 | 144 | |
|
145 | 145 | Every message is serialized to a sequence of at least six blobs of bytes: |
|
146 | 146 | |
|
147 | 147 | .. sourcecode:: python |
|
148 | 148 | |
|
149 | 149 | [ |
|
150 | 150 | b'u-u-i-d', # zmq identity(ies) |
|
151 | 151 | b'<IDS|MSG>', # delimiter |
|
152 | 152 | b'baddad42', # HMAC signature |
|
153 | 153 | b'{header}', # serialized header dict |
|
154 | 154 | b'{parent_header}', # serialized parent header dict |
|
155 | 155 | b'{metadata}', # serialized metadata dict |
|
156 | 156 | b'{content}', # serialized content dict |
|
157 | 157 | b'blob', # extra raw data buffer(s) |
|
158 | 158 | ... |
|
159 | 159 | ] |
|
160 | 160 | |
|
161 | 161 | The front of the message is the ZeroMQ routing prefix, |
|
162 | 162 | which can be zero or more socket identities. |
|
163 | 163 | This is every piece of the message prior to the delimiter key ``<IDS|MSG>``. |
|
164 | 164 | In the case of IOPub, there should be just one prefix component, |
|
165 | 165 | which is the topic for IOPub subscribers, e.g. ``execute_result``, ``display_data``. |
|
166 | 166 | |
|
167 | 167 | .. note:: |
|
168 | 168 | |
|
169 | 169 | In most cases, the IOPub topics are irrelevant and completely ignored, |
|
170 | 170 | because frontends just subscribe to all topics. |
|
171 | 171 | The convention used in the IPython kernel is to use the msg_type as the topic, |
|
172 | 172 | and possibly extra information about the message, e.g. ``execute_result`` or ``stream.stdout`` |
|
173 | 173 | |
|
174 | 174 | After the delimiter is the `HMAC`_ signature of the message, used for authentication. |
|
175 | 175 | If authentication is disabled, this should be an empty string. |
|
176 | 176 | By default, the hashing function used for computing these signatures is sha256. |
|
177 | 177 | |
|
178 | 178 | .. _HMAC: http://en.wikipedia.org/wiki/HMAC |
|
179 | 179 | |
|
180 | 180 | .. note:: |
|
181 | 181 | |
|
182 | 182 | To disable authentication and signature checking, |
|
183 | 183 | set the `key` field of a connection file to an empty string. |
|
184 | 184 | |
|
185 | 185 | The signature is the HMAC hex digest of the concatenation of: |
|
186 | 186 | |
|
187 | 187 | - A shared key (typically the ``key`` field of a connection file) |
|
188 | 188 | - The serialized header dict |
|
189 | 189 | - The serialized parent header dict |
|
190 | 190 | - The serialized metadata dict |
|
191 | 191 | - The serialized content dict |
|
192 | 192 | |
|
193 | 193 | In Python, this is implemented via: |
|
194 | 194 | |
|
195 | 195 | .. sourcecode:: python |
|
196 | 196 | |
|
197 | 197 | # once: |
|
198 | 198 | digester = HMAC(key, digestmod=hashlib.sha256) |
|
199 | 199 | |
|
200 | 200 | # for each message |
|
201 | 201 | d = digester.copy() |
|
202 | 202 | for serialized_dict in (header, parent, metadata, content): |
|
203 | 203 | d.update(serialized_dict) |
|
204 | 204 | signature = d.hexdigest() |
|
205 | 205 | |
|
206 | 206 | After the signature is the actual message, always in four frames of bytes. |
|
207 | 207 | The four dictionaries that compose a message are serialized separately, |
|
208 | 208 | in the order of header, parent header, metadata, and content. |
|
209 | 209 | These can be serialized by any function that turns a dict into bytes. |
|
210 | 210 | The default and most common serialization is JSON, but msgpack and pickle |
|
211 | 211 | are common alternatives. |
|
212 | 212 | |
|
213 | 213 | After the serialized dicts are zero to many raw data buffers, |
|
214 | 214 | which can be used by message types that support binary data (mainly apply and data_pub). |
|
215 | 215 | |
|
216 | 216 | |
|
217 | 217 | Python functional API |
|
218 | 218 | ===================== |
|
219 | 219 | |
|
220 | 220 | As messages are dicts, they map naturally to a ``func(**kw)`` call form. We |
|
221 | 221 | should develop, at a few key points, functional forms of all the requests that |
|
222 | 222 | take arguments in this manner and automatically construct the necessary dict |
|
223 | 223 | for sending. |
|
224 | 224 | |
|
225 | 225 | In addition, the Python implementation of the message specification extends |
|
226 | 226 | messages upon deserialization to the following form for convenience:: |
|
227 | 227 | |
|
228 | 228 | { |
|
229 | 229 | 'header' : dict, |
|
230 | 230 | # The msg's unique identifier and type are always stored in the header, |
|
231 | 231 | # but the Python implementation copies them to the top level. |
|
232 | 232 | 'msg_id' : uuid, |
|
233 | 233 | 'msg_type' : str, |
|
234 | 234 | 'parent_header' : dict, |
|
235 | 235 | 'content' : dict, |
|
236 | 236 | 'metadata' : dict, |
|
237 | 237 | } |
|
238 | 238 | |
|
239 | 239 | All messages sent to or received by any IPython process should have this |
|
240 | 240 | extended structure. |
|
241 | 241 | |
|
242 | 242 | |
|
243 | 243 | Messages on the shell ROUTER/DEALER sockets |
|
244 | 244 | =========================================== |
|
245 | 245 | |
|
246 | 246 | .. _execute: |
|
247 | 247 | |
|
248 | 248 | Execute |
|
249 | 249 | ------- |
|
250 | 250 | |
|
251 | 251 | This message type is used by frontends to ask the kernel to execute code on |
|
252 | 252 | behalf of the user, in a namespace reserved to the user's variables (and thus |
|
253 | 253 | separate from the kernel's own internal code and variables). |
|
254 | 254 | |
|
255 | 255 | Message type: ``execute_request``:: |
|
256 | 256 | |
|
257 | 257 | content = { |
|
258 | 258 | # Source code to be executed by the kernel, one or more lines. |
|
259 | 259 | 'code' : str, |
|
260 | 260 | |
|
261 | 261 | # A boolean flag which, if True, signals the kernel to execute |
|
262 | 262 | # this code as quietly as possible. |
|
263 | 263 | # silent=True forces store_history to be False, |
|
264 | 264 | # and will *not*: |
|
265 | 265 | # - broadcast output on the IOPUB channel |
|
266 | 266 | # - have an execute_result |
|
267 | 267 | # The default is False. |
|
268 | 268 | 'silent' : bool, |
|
269 | 269 | |
|
270 | 270 | # A boolean flag which, if True, signals the kernel to populate history |
|
271 | 271 | # The default is True if silent is False. If silent is True, store_history |
|
272 | 272 | # is forced to be False. |
|
273 | 273 | 'store_history' : bool, |
|
274 | 274 | |
|
275 | 275 | # A dict mapping names to expressions to be evaluated in the |
|
276 | 276 | # user's dict. The rich display-data representation of each will be evaluated after execution. |
|
277 | 277 | # See the display_data content for the structure of the representation data. |
|
278 | 278 | 'user_expressions' : dict, |
|
279 | 279 | |
|
280 | 280 | # Some frontends do not support stdin requests. |
|
281 | 281 | # If raw_input is called from code executed from such a frontend, |
|
282 | 282 | # a StdinNotImplementedError will be raised. |
|
283 | 283 | 'allow_stdin' : True, |
|
284 | 284 | |
|
285 | 285 | # A boolean flag, which, if True, does not abort the execution queue, if an exception is encountered. |
|
286 | 286 | # This allows the queued execution of multiple execute_requests, even if they generate exceptions. |
|
287 | 287 | 'stop_on_error' : False, |
|
288 | 288 | } |
|
289 | 289 | |
|
290 | 290 | .. versionchanged:: 5.0 |
|
291 | 291 | |
|
292 | 292 | ``user_variables`` removed, because it is redundant with user_expressions. |
|
293 | 293 | |
|
294 | 294 | The ``code`` field contains a single string (possibly multiline) to be executed. |
|
295 | 295 | |
|
296 | 296 | The ``user_expressions`` field deserves a detailed explanation. In the past, IPython had |
|
297 | 297 | the notion of a prompt string that allowed arbitrary code to be evaluated, and |
|
298 | 298 | this was put to good use by many in creating prompts that displayed system |
|
299 | 299 | status, path information, and even more esoteric uses like remote instrument |
|
300 | 300 | status acquired over the network. But now that IPython has a clean separation |
|
301 | 301 | between the kernel and the clients, the kernel has no prompt knowledge; prompts |
|
302 | 302 | are a frontend feature, and it should be even possible for different |
|
303 | 303 | frontends to display different prompts while interacting with the same kernel. |
|
304 | 304 | ``user_expressions`` can be used to retrieve this information. |
|
305 | 305 | |
|
306 | 306 | Any error in evaluating any expression in ``user_expressions`` will result in |
|
307 | 307 | only that key containing a standard error message, of the form:: |
|
308 | 308 | |
|
309 | 309 | { |
|
310 | 310 | 'status' : 'error', |
|
311 | 311 | 'ename' : 'NameError', |
|
312 | 312 | 'evalue' : 'foo', |
|
313 | 313 | 'traceback' : ... |
|
314 | 314 | } |
|
315 | 315 | |
|
316 | 316 | .. Note:: |
|
317 | 317 | |
|
318 | 318 | In order to obtain the current execution counter for the purposes of |
|
319 | 319 | displaying input prompts, frontends may make an execution request with an |
|
320 | 320 | empty code string and ``silent=True``. |
|
321 | 321 | |
|
322 | 322 | Upon completion of the execution request, the kernel *always* sends a reply, |
|
323 | 323 | with a status code indicating what happened and additional data depending on |
|
324 | 324 | the outcome. See :ref:`below <execution_results>` for the possible return |
|
325 | 325 | codes and associated data. |
|
326 | 326 | |
|
327 | 327 | .. seealso:: |
|
328 | 328 | |
|
329 | 329 | :ref:`execution_semantics` |
|
330 | 330 | |
|
331 | 331 | .. _execution_counter: |
|
332 | 332 | |
|
333 | 333 | Execution counter (prompt number) |
|
334 | 334 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
335 | 335 | |
|
336 | 336 | The kernel should have a single, monotonically increasing counter of all execution |
|
337 | 337 | requests that are made with ``store_history=True``. This counter is used to populate |
|
338 | 338 | the ``In[n]`` and ``Out[n]`` prompts. The value of this counter will be returned as the |
|
339 | 339 | ``execution_count`` field of all ``execute_reply`` and ``execute_input`` messages. |
|
340 | 340 | |
|
341 | 341 | .. _execution_results: |
|
342 | 342 | |
|
343 | 343 | Execution results |
|
344 | 344 | ~~~~~~~~~~~~~~~~~ |
|
345 | 345 | |
|
346 | 346 | Message type: ``execute_reply``:: |
|
347 | 347 | |
|
348 | 348 | content = { |
|
349 | 349 | # One of: 'ok' OR 'error' OR 'abort' |
|
350 | 350 | 'status' : str, |
|
351 | 351 | |
|
352 | 352 | # The global kernel counter that increases by one with each request that |
|
353 | 353 | # stores history. This will typically be used by clients to display |
|
354 | 354 | # prompt numbers to the user. If the request did not store history, this will |
|
355 | 355 | # be the current value of the counter in the kernel. |
|
356 | 356 | 'execution_count' : int, |
|
357 | 357 | } |
|
358 | 358 | |
|
359 | 359 | When status is 'ok', the following extra fields are present:: |
|
360 | 360 | |
|
361 | 361 | { |
|
362 | 362 | # 'payload' will be a list of payload dicts, and is optional. |
|
363 | 363 | # payloads are considered deprecated. |
|
364 | 364 | # The only requirement of each payload dict is that it have a 'source' key, |
|
365 | 365 | # which is a string classifying the payload (e.g. 'page'). |
|
366 | 366 | |
|
367 | 367 | 'payload' : list(dict), |
|
368 | 368 | |
|
369 | 369 | # Results for the user_expressions. |
|
370 | 370 | 'user_expressions' : dict, |
|
371 | 371 | } |
|
372 | 372 | |
|
373 | 373 | .. versionchanged:: 5.0 |
|
374 | 374 | |
|
375 | 375 | ``user_variables`` is removed, use user_expressions instead. |
|
376 | 376 | |
|
377 | 377 | When status is 'error', the following extra fields are present:: |
|
378 | 378 | |
|
379 | 379 | { |
|
380 | 380 | 'ename' : str, # Exception name, as a string |
|
381 | 381 | 'evalue' : str, # Exception value, as a string |
|
382 | 382 | |
|
383 | 383 | # The traceback will contain a list of frames, represented each as a |
|
384 | 384 | # string. For now we'll stick to the existing design of ultraTB, which |
|
385 | 385 | # controls exception level of detail statefully. But eventually we'll |
|
386 | 386 | # want to grow into a model where more information is collected and |
|
387 | 387 | # packed into the traceback object, with clients deciding how little or |
|
388 | 388 | # how much of it to unpack. But for now, let's start with a simple list |
|
389 | 389 | # of strings, since that requires only minimal changes to ultratb as |
|
390 | 390 | # written. |
|
391 | 391 | 'traceback' : list, |
|
392 | 392 | } |
|
393 | 393 | |
|
394 | 394 | |
|
395 | 395 | When status is 'abort', there are for now no additional data fields. This |
|
396 | 396 | happens when the kernel was interrupted by a signal. |
|
397 | 397 | |
|
398 | 398 | Payloads |
|
399 | 399 | ******** |
|
400 | 400 | |
|
401 | 401 | .. admonition:: Execution payloads |
|
402 | 402 | |
|
403 | 403 | Payloads are considered deprecated, though their replacement is not yet implemented. |
|
404 | 404 | |
|
405 | 405 | Payloads are a way to trigger frontend actions from the kernel. Current payloads: |
|
406 | 406 | |
|
407 | 407 | **page**: display data in a pager. |
|
408 | 408 | |
|
409 | 409 | Pager output is used for introspection, or other displayed information that's not considered output. |
|
410 | 410 | Pager payloads are generally displayed in a separate pane, that can be viewed alongside code, |
|
411 | 411 | and are not included in notebook documents. |
|
412 | 412 | |
|
413 | 413 | .. sourcecode:: python |
|
414 | 414 | |
|
415 | 415 | { |
|
416 | 416 | "source": "page", |
|
417 | 417 | # mime-bundle of data to display in the pager. |
|
418 | 418 | # Must include text/plain. |
|
419 | 419 | "data": mimebundle, |
|
420 | 420 | # line offset to start from |
|
421 | 421 | "start": int, |
|
422 | 422 | } |
|
423 | 423 | |
|
424 | 424 | **set_next_input**: create a new output |
|
425 | 425 | |
|
426 | 426 | used to create new cells in the notebook, |
|
427 | 427 | or set the next input in a console interface. |
|
428 | 428 | The main example being ``%load``. |
|
429 | 429 | |
|
430 | 430 | .. sourcecode:: python |
|
431 | 431 | |
|
432 | 432 | { |
|
433 | 433 | "source": "set_next_input", |
|
434 | 434 | # the text contents of the cell to create |
|
435 | 435 | "text": "some cell content", |
|
436 | 436 | # If true, replace the current cell in document UIs instead of inserting |
|
437 | 437 | # a cell. Ignored in console UIs. |
|
438 | 438 | "replace": bool, |
|
439 | 439 | } |
|
440 | 440 | |
|
441 | 441 | **edit**: open a file for editing. |
|
442 | 442 | |
|
443 | 443 | Triggered by `%edit`. Only the QtConsole currently supports edit payloads. |
|
444 | 444 | |
|
445 | 445 | .. sourcecode:: python |
|
446 | 446 | |
|
447 | 447 | { |
|
448 | 448 | "source": "edit", |
|
449 | 449 | "filename": "/path/to/file.py", # the file to edit |
|
450 | 450 | "line_number": int, # the line number to start with |
|
451 | 451 | } |
|
452 | 452 | |
|
453 | 453 | **ask_exit**: instruct the frontend to prompt the user for exit |
|
454 | 454 | |
|
455 | 455 | Allows the kernel to request exit, e.g. via ``%exit`` in IPython. |
|
456 | 456 | Only for console frontends. |
|
457 | 457 | |
|
458 | 458 | .. sourcecode:: python |
|
459 | 459 | |
|
460 | 460 | { |
|
461 | 461 | "source": "ask_exit", |
|
462 | 462 | # whether the kernel should be left running, only closing the client |
|
463 | 463 | "keepkernel": bool, |
|
464 | 464 | } |
|
465 | 465 | |
|
466 | 466 | |
|
467 | 467 | .. _msging_inspection: |
|
468 | 468 | |
|
469 | 469 | Introspection |
|
470 | 470 | ------------- |
|
471 | 471 | |
|
472 | 472 | Code can be inspected to show useful information to the user. |
|
473 | 473 | It is up to the Kernel to decide what information should be displayed, and its formatting. |
|
474 | 474 | |
|
475 | 475 | Message type: ``inspect_request``:: |
|
476 | 476 | |
|
477 | 477 | content = { |
|
478 | 478 | # The code context in which introspection is requested |
|
479 | 479 | # this may be up to an entire multiline cell. |
|
480 | 480 | 'code' : str, |
|
481 | 481 | |
|
482 | 482 | # The cursor position within 'code' (in unicode characters) where inspection is requested |
|
483 | 483 | 'cursor_pos' : int, |
|
484 | 484 | |
|
485 | 485 | # The level of detail desired. In IPython, the default (0) is equivalent to typing |
|
486 | 486 | # 'x?' at the prompt, 1 is equivalent to 'x??'. |
|
487 | 487 | # The difference is up to kernels, but in IPython level 1 includes the source code |
|
488 | 488 | # if available. |
|
489 | 489 | 'detail_level' : 0 or 1, |
|
490 | 490 | } |
|
491 | 491 | |
|
492 | 492 | .. versionchanged:: 5.0 |
|
493 | 493 | |
|
494 | 494 | ``object_info_request`` renamed to ``inspect_request``. |
|
495 | 495 | |
|
496 | 496 | .. versionchanged:: 5.0 |
|
497 | 497 | |
|
498 | 498 | ``name`` key replaced with ``code`` and ``cursor_pos``, |
|
499 | 499 | moving the lexing responsibility to the kernel. |
|
500 | 500 | |
|
501 | 501 | The reply is a mime-bundle, like a `display_data`_ message, |
|
502 | 502 | which should be a formatted representation of information about the context. |
|
503 | 503 | In the notebook, this is used to show tooltips over function calls, etc. |
|
504 | 504 | |
|
505 | 505 | Message type: ``inspect_reply``:: |
|
506 | 506 | |
|
507 | 507 | content = { |
|
508 | 508 | # 'ok' if the request succeeded or 'error', with error information as in all other replies. |
|
509 | 509 | 'status' : 'ok', |
|
510 | 510 | |
|
511 | # found should be true if an object was found, false otherwise | |
|
512 | 'found' : bool, | |
|
513 | ||
|
511 | 514 | # data can be empty if nothing is found |
|
512 | 515 | 'data' : dict, |
|
513 | 516 | 'metadata' : dict, |
|
514 | 517 | } |
|
515 | 518 | |
|
516 | 519 | .. versionchanged:: 5.0 |
|
517 | 520 | |
|
518 | 521 | ``object_info_reply`` renamed to ``inspect_reply``. |
|
519 | 522 | |
|
520 | 523 | .. versionchanged:: 5.0 |
|
521 | 524 | |
|
522 | 525 | Reply is changed from structured data to a mime bundle, allowing formatting decisions to be made by the kernel. |
|
523 | 526 | |
|
524 | 527 | .. _msging_completion: |
|
525 | 528 | |
|
526 | 529 | Completion |
|
527 | 530 | ---------- |
|
528 | 531 | |
|
529 | 532 | Message type: ``complete_request``:: |
|
530 | 533 | |
|
531 | 534 | content = { |
|
532 | 535 | # The code context in which completion is requested |
|
533 | 536 | # this may be up to an entire multiline cell, such as |
|
534 | 537 | # 'foo = a.isal' |
|
535 | 538 | 'code' : str, |
|
536 | 539 | |
|
537 | 540 | # The cursor position within 'code' (in unicode characters) where completion is requested |
|
538 | 541 | 'cursor_pos' : int, |
|
539 | 542 | } |
|
540 | 543 | |
|
541 | 544 | .. versionchanged:: 5.0 |
|
542 | 545 | |
|
543 | 546 | ``line``, ``block``, and ``text`` keys are removed in favor of a single ``code`` for context. |
|
544 | 547 | Lexing is up to the kernel. |
|
545 | 548 | |
|
546 | 549 | |
|
547 | 550 | Message type: ``complete_reply``:: |
|
548 | 551 | |
|
549 | 552 | content = { |
|
550 | 553 | # The list of all matches to the completion request, such as |
|
551 | 554 | # ['a.isalnum', 'a.isalpha'] for the above example. |
|
552 | 555 | 'matches' : list, |
|
553 | 556 | |
|
554 | 557 | # The range of text that should be replaced by the above matches when a completion is accepted. |
|
555 | 558 | # typically cursor_end is the same as cursor_pos in the request. |
|
556 | 559 | 'cursor_start' : int, |
|
557 | 560 | 'cursor_end' : int, |
|
558 | 561 | |
|
559 | 562 | # Information that frontend plugins might use for extra display information about completions. |
|
560 | 563 | 'metadata' : dict, |
|
561 | 564 | |
|
562 | 565 | # status should be 'ok' unless an exception was raised during the request, |
|
563 | 566 | # in which case it should be 'error', along with the usual error message content |
|
564 | 567 | # in other messages. |
|
565 | 568 | 'status' : 'ok' |
|
566 | 569 | } |
|
567 | 570 | |
|
568 | 571 | .. versionchanged:: 5.0 |
|
569 | 572 | |
|
570 | 573 | - ``matched_text`` is removed in favor of ``cursor_start`` and ``cursor_end``. |
|
571 | 574 | - ``metadata`` is added for extended information. |
|
572 | 575 | |
|
573 | 576 | .. _msging_history: |
|
574 | 577 | |
|
575 | 578 | History |
|
576 | 579 | ------- |
|
577 | 580 | |
|
578 | 581 | For clients to explicitly request history from a kernel. The kernel has all |
|
579 | 582 | the actual execution history stored in a single location, so clients can |
|
580 | 583 | request it from the kernel when needed. |
|
581 | 584 | |
|
582 | 585 | Message type: ``history_request``:: |
|
583 | 586 | |
|
584 | 587 | content = { |
|
585 | 588 | |
|
586 | 589 | # If True, also return output history in the resulting dict. |
|
587 | 590 | 'output' : bool, |
|
588 | 591 | |
|
589 | 592 | # If True, return the raw input history, else the transformed input. |
|
590 | 593 | 'raw' : bool, |
|
591 | 594 | |
|
592 | 595 | # So far, this can be 'range', 'tail' or 'search'. |
|
593 | 596 | 'hist_access_type' : str, |
|
594 | 597 | |
|
595 | 598 | # If hist_access_type is 'range', get a range of input cells. session can |
|
596 | 599 | # be a positive session number, or a negative number to count back from |
|
597 | 600 | # the current session. |
|
598 | 601 | 'session' : int, |
|
599 | 602 | # start and stop are line numbers within that session. |
|
600 | 603 | 'start' : int, |
|
601 | 604 | 'stop' : int, |
|
602 | 605 | |
|
603 | 606 | # If hist_access_type is 'tail' or 'search', get the last n cells. |
|
604 | 607 | 'n' : int, |
|
605 | 608 | |
|
606 | 609 | # If hist_access_type is 'search', get cells matching the specified glob |
|
607 | 610 | # pattern (with * and ? as wildcards). |
|
608 | 611 | 'pattern' : str, |
|
609 | 612 | |
|
610 | 613 | # If hist_access_type is 'search' and unique is true, do not |
|
611 | 614 | # include duplicated history. Default is false. |
|
612 | 615 | 'unique' : bool, |
|
613 | 616 | |
|
614 | 617 | } |
|
615 | 618 | |
|
616 | 619 | .. versionadded:: 4.0 |
|
617 | 620 | The key ``unique`` for ``history_request``. |
|
618 | 621 | |
|
619 | 622 | Message type: ``history_reply``:: |
|
620 | 623 | |
|
621 | 624 | content = { |
|
622 | 625 | # A list of 3 tuples, either: |
|
623 | 626 | # (session, line_number, input) or |
|
624 | 627 | # (session, line_number, (input, output)), |
|
625 | 628 | # depending on whether output was False or True, respectively. |
|
626 | 629 | 'history' : list, |
|
627 | 630 | } |
|
628 | 631 | |
|
629 | 632 | .. _msging_is_complete: |
|
630 | 633 | |
|
631 | 634 | Code completeness |
|
632 | 635 | ----------------- |
|
633 | 636 | |
|
634 | 637 | .. versionadded:: 5.0 |
|
635 | 638 | |
|
636 | 639 | When the user enters a line in a console style interface, the console must |
|
637 | 640 | decide whether to immediately execute the current code, or whether to show a |
|
638 | 641 | continuation prompt for further input. For instance, in Python ``a = 5`` would |
|
639 | 642 | be executed immediately, while ``for i in range(5):`` would expect further input. |
|
640 | 643 | |
|
641 | 644 | There are four possible replies: |
|
642 | 645 | |
|
643 | 646 | - *complete* code is ready to be executed |
|
644 | 647 | - *incomplete* code should prompt for another line |
|
645 | 648 | - *invalid* code will typically be sent for execution, so that the user sees the |
|
646 | 649 | error soonest. |
|
647 | 650 | - *unknown* - if the kernel is not able to determine this. The frontend should |
|
648 | 651 | also handle the kernel not replying promptly. It may default to sending the |
|
649 | 652 | code for execution, or it may implement simple fallback heuristics for whether |
|
650 | 653 | to execute the code (e.g. execute after a blank line). |
|
651 | 654 | |
|
652 | 655 | Frontends may have ways to override this, forcing the code to be sent for |
|
653 | 656 | execution or forcing a continuation prompt. |
|
654 | 657 | |
|
655 | 658 | Message type: ``is_complete_request``:: |
|
656 | 659 | |
|
657 | 660 | content = { |
|
658 | 661 | # The code entered so far as a multiline string |
|
659 | 662 | 'code' : str, |
|
660 | 663 | } |
|
661 | 664 | |
|
662 | 665 | Message type: ``is_complete_reply``:: |
|
663 | 666 | |
|
664 | 667 | content = { |
|
665 | 668 | # One of 'complete', 'incomplete', 'invalid', 'unknown' |
|
666 | 669 | 'status' : str, |
|
667 | 670 | |
|
668 | 671 | # If status is 'incomplete', indent should contain the characters to use |
|
669 | 672 | # to indent the next line. This is only a hint: frontends may ignore it |
|
670 | 673 | # and use their own autoindentation rules. For other statuses, this |
|
671 | 674 | # field does not exist. |
|
672 | 675 | 'indent': str, |
|
673 | 676 | } |
|
674 | 677 | |
|
675 | 678 | Connect |
|
676 | 679 | ------- |
|
677 | 680 | |
|
678 | 681 | When a client connects to the request/reply socket of the kernel, it can issue |
|
679 | 682 | a connect request to get basic information about the kernel, such as the ports |
|
680 | 683 | the other ZeroMQ sockets are listening on. This allows clients to only have |
|
681 | 684 | to know about a single port (the shell channel) to connect to a kernel. |
|
682 | 685 | |
|
683 | 686 | Message type: ``connect_request``:: |
|
684 | 687 | |
|
685 | 688 | content = { |
|
686 | 689 | } |
|
687 | 690 | |
|
688 | 691 | Message type: ``connect_reply``:: |
|
689 | 692 | |
|
690 | 693 | content = { |
|
691 | 694 | 'shell_port' : int, # The port the shell ROUTER socket is listening on. |
|
692 | 695 | 'iopub_port' : int, # The port the PUB socket is listening on. |
|
693 | 696 | 'stdin_port' : int, # The port the stdin ROUTER socket is listening on. |
|
694 | 697 | 'hb_port' : int, # The port the heartbeat socket is listening on. |
|
695 | 698 | } |
|
696 | 699 | |
|
697 | 700 | .. _msging_kernel_info: |
|
698 | 701 | |
|
699 | 702 | Kernel info |
|
700 | 703 | ----------- |
|
701 | 704 | |
|
702 | 705 | If a client needs to know information about the kernel, it can |
|
703 | 706 | make a request of the kernel's information. |
|
704 | 707 | This message can be used to fetch core information of the |
|
705 | 708 | kernel, including language (e.g., Python), language version number and |
|
706 | 709 | IPython version number, and the IPython message spec version number. |
|
707 | 710 | |
|
708 | 711 | Message type: ``kernel_info_request``:: |
|
709 | 712 | |
|
710 | 713 | content = { |
|
711 | 714 | } |
|
712 | 715 | |
|
713 | 716 | Message type: ``kernel_info_reply``:: |
|
714 | 717 | |
|
715 | 718 | content = { |
|
716 | 719 | # Version of messaging protocol. |
|
717 | 720 | # The first integer indicates major version. It is incremented when |
|
718 | 721 | # there is any backward incompatible change. |
|
719 | 722 | # The second integer indicates minor version. It is incremented when |
|
720 | 723 | # there is any backward compatible change. |
|
721 | 724 | 'protocol_version': 'X.Y.Z', |
|
722 | 725 | |
|
723 | 726 | # The kernel implementation name |
|
724 | 727 | # (e.g. 'ipython' for the IPython kernel) |
|
725 | 728 | 'implementation': str, |
|
726 | 729 | |
|
727 | 730 | # Implementation version number. |
|
728 | 731 | # The version number of the kernel's implementation |
|
729 | 732 | # (e.g. IPython.__version__ for the IPython kernel) |
|
730 | 733 | 'implementation_version': 'X.Y.Z', |
|
731 | 734 | |
|
732 | 735 | # Information about the language of code for the kernel |
|
733 | 736 | 'language_info': { |
|
734 | 737 | # Name of the programming language in which kernel is implemented. |
|
735 | 738 | # Kernel included in IPython returns 'python'. |
|
736 | 739 | 'name': str, |
|
737 | 740 | |
|
738 | 741 | # Language version number. |
|
739 | 742 | # It is Python version number (e.g., '2.7.3') for the kernel |
|
740 | 743 | # included in IPython. |
|
741 | 744 | 'version': 'X.Y.Z', |
|
742 | 745 | |
|
743 | 746 | # mimetype for script files in this language |
|
744 | 747 | 'mimetype': str, |
|
745 | 748 | |
|
746 | 749 | # Extension including the dot, e.g. '.py' |
|
747 | 750 | 'file_extension': str, |
|
748 | 751 | |
|
749 | 752 | # Pygments lexer, for highlighting |
|
750 | 753 | # Only needed if it differs from the top level 'language' field. |
|
751 | 754 | 'pygments_lexer': str, |
|
752 | 755 | |
|
753 | 756 | # Codemirror mode, for for highlighting in the notebook. |
|
754 | 757 | # Only needed if it differs from the top level 'language' field. |
|
755 | 758 | 'codemirror_mode': str or dict, |
|
756 | 759 | |
|
757 | 760 | # Nbconvert exporter, if notebooks written with this kernel should |
|
758 | 761 | # be exported with something other than the general 'script' |
|
759 | 762 | # exporter. |
|
760 | 763 | 'nbconvert_exporter': str, |
|
761 | 764 | }, |
|
762 | 765 | |
|
763 | 766 | # A banner of information about the kernel, |
|
764 | 767 | # which may be desplayed in console environments. |
|
765 | 768 | 'banner' : str, |
|
766 | 769 | |
|
767 | 770 | # Optional: A list of dictionaries, each with keys 'text' and 'url'. |
|
768 | 771 | # These will be displayed in the help menu in the notebook UI. |
|
769 | 772 | 'help_links': [ |
|
770 | 773 | {'text': str, 'url': str} |
|
771 | 774 | ], |
|
772 | 775 | } |
|
773 | 776 | |
|
774 | 777 | Refer to the lists of available `Pygments lexers <http://pygments.org/docs/lexers/>`_ |
|
775 | 778 | and `codemirror modes <http://codemirror.net/mode/index.html>`_ for those fields. |
|
776 | 779 | |
|
777 | 780 | .. versionchanged:: 5.0 |
|
778 | 781 | |
|
779 | 782 | Versions changed from lists of integers to strings. |
|
780 | 783 | |
|
781 | 784 | .. versionchanged:: 5.0 |
|
782 | 785 | |
|
783 | 786 | ``ipython_version`` is removed. |
|
784 | 787 | |
|
785 | 788 | .. versionchanged:: 5.0 |
|
786 | 789 | |
|
787 | 790 | ``language_info``, ``implementation``, ``implementation_version``, ``banner`` |
|
788 | 791 | and ``help_links`` keys are added. |
|
789 | 792 | |
|
790 | 793 | .. versionchanged:: 5.0 |
|
791 | 794 | |
|
792 | 795 | ``language_version`` moved to ``language_info.version`` |
|
793 | 796 | |
|
794 | 797 | .. versionchanged:: 5.0 |
|
795 | 798 | |
|
796 | 799 | ``language`` moved to ``language_info.name`` |
|
797 | 800 | |
|
798 | 801 | .. _msging_shutdown: |
|
799 | 802 | |
|
800 | 803 | Kernel shutdown |
|
801 | 804 | --------------- |
|
802 | 805 | |
|
803 | 806 | The clients can request the kernel to shut itself down; this is used in |
|
804 | 807 | multiple cases: |
|
805 | 808 | |
|
806 | 809 | - when the user chooses to close the client application via a menu or window |
|
807 | 810 | control. |
|
808 | 811 | - when the user types 'exit' or 'quit' (or their uppercase magic equivalents). |
|
809 | 812 | - when the user chooses a GUI method (like the 'Ctrl-C' shortcut in the |
|
810 | 813 | IPythonQt client) to force a kernel restart to get a clean kernel without |
|
811 | 814 | losing client-side state like history or inlined figures. |
|
812 | 815 | |
|
813 | 816 | The client sends a shutdown request to the kernel, and once it receives the |
|
814 | 817 | reply message (which is otherwise empty), it can assume that the kernel has |
|
815 | 818 | completed shutdown safely. |
|
816 | 819 | |
|
817 | 820 | Upon their own shutdown, client applications will typically execute a last |
|
818 | 821 | minute sanity check and forcefully terminate any kernel that is still alive, to |
|
819 | 822 | avoid leaving stray processes in the user's machine. |
|
820 | 823 | |
|
821 | 824 | Message type: ``shutdown_request``:: |
|
822 | 825 | |
|
823 | 826 | content = { |
|
824 | 827 | 'restart' : bool # whether the shutdown is final, or precedes a restart |
|
825 | 828 | } |
|
826 | 829 | |
|
827 | 830 | Message type: ``shutdown_reply``:: |
|
828 | 831 | |
|
829 | 832 | content = { |
|
830 | 833 | 'restart' : bool # whether the shutdown is final, or precedes a restart |
|
831 | 834 | } |
|
832 | 835 | |
|
833 | 836 | .. Note:: |
|
834 | 837 | |
|
835 | 838 | When the clients detect a dead kernel thanks to inactivity on the heartbeat |
|
836 | 839 | socket, they simply send a forceful process termination signal, since a dead |
|
837 | 840 | process is unlikely to respond in any useful way to messages. |
|
838 | 841 | |
|
839 | 842 | |
|
840 | 843 | Messages on the PUB/SUB socket |
|
841 | 844 | ============================== |
|
842 | 845 | |
|
843 | 846 | Streams (stdout, stderr, etc) |
|
844 | 847 | ------------------------------ |
|
845 | 848 | |
|
846 | 849 | Message type: ``stream``:: |
|
847 | 850 | |
|
848 | 851 | content = { |
|
849 | 852 | # The name of the stream is one of 'stdout', 'stderr' |
|
850 | 853 | 'name' : str, |
|
851 | 854 | |
|
852 | 855 | # The text is an arbitrary string to be written to that stream |
|
853 | 856 | 'text' : str, |
|
854 | 857 | } |
|
855 | 858 | |
|
856 | 859 | .. versionchanged:: 5.0 |
|
857 | 860 | |
|
858 | 861 | 'data' key renamed to 'text' for conistency with the notebook format. |
|
859 | 862 | |
|
860 | 863 | Display Data |
|
861 | 864 | ------------ |
|
862 | 865 | |
|
863 | 866 | This type of message is used to bring back data that should be displayed (text, |
|
864 | 867 | html, svg, etc.) in the frontends. This data is published to all frontends. |
|
865 | 868 | Each message can have multiple representations of the data; it is up to the |
|
866 | 869 | frontend to decide which to use and how. A single message should contain all |
|
867 | 870 | possible representations of the same information. Each representation should |
|
868 | 871 | be a JSON'able data structure, and should be a valid MIME type. |
|
869 | 872 | |
|
870 | 873 | Some questions remain about this design: |
|
871 | 874 | |
|
872 | 875 | * Do we use this message type for execute_result/displayhook? Probably not, because |
|
873 | 876 | the displayhook also has to handle the Out prompt display. On the other hand |
|
874 | 877 | we could put that information into the metadata section. |
|
875 | 878 | |
|
876 | 879 | .. _display_data: |
|
877 | 880 | |
|
878 | 881 | Message type: ``display_data``:: |
|
879 | 882 | |
|
880 | 883 | content = { |
|
881 | 884 | |
|
882 | 885 | # Who create the data |
|
883 | 886 | 'source' : str, |
|
884 | 887 | |
|
885 | 888 | # The data dict contains key/value pairs, where the keys are MIME |
|
886 | 889 | # types and the values are the raw data of the representation in that |
|
887 | 890 | # format. |
|
888 | 891 | 'data' : dict, |
|
889 | 892 | |
|
890 | 893 | # Any metadata that describes the data |
|
891 | 894 | 'metadata' : dict |
|
892 | 895 | } |
|
893 | 896 | |
|
894 | 897 | |
|
895 | 898 | The ``metadata`` contains any metadata that describes the output. |
|
896 | 899 | Global keys are assumed to apply to the output as a whole. |
|
897 | 900 | The ``metadata`` dict can also contain mime-type keys, which will be sub-dictionaries, |
|
898 | 901 | which are interpreted as applying only to output of that type. |
|
899 | 902 | Third parties should put any data they write into a single dict |
|
900 | 903 | with a reasonably unique name to avoid conflicts. |
|
901 | 904 | |
|
902 | 905 | The only metadata keys currently defined in IPython are the width and height |
|
903 | 906 | of images:: |
|
904 | 907 | |
|
905 | 908 | metadata = { |
|
906 | 909 | 'image/png' : { |
|
907 | 910 | 'width': 640, |
|
908 | 911 | 'height': 480 |
|
909 | 912 | } |
|
910 | 913 | } |
|
911 | 914 | |
|
912 | 915 | |
|
913 | 916 | .. versionchanged:: 5.0 |
|
914 | 917 | |
|
915 | 918 | `application/json` data should be unpacked JSON data, |
|
916 | 919 | not double-serialized as a JSON string. |
|
917 | 920 | |
|
918 | 921 | |
|
919 | 922 | Raw Data Publication |
|
920 | 923 | -------------------- |
|
921 | 924 | |
|
922 | 925 | ``display_data`` lets you publish *representations* of data, such as images and html. |
|
923 | 926 | This ``data_pub`` message lets you publish *actual raw data*, sent via message buffers. |
|
924 | 927 | |
|
925 | 928 | data_pub messages are constructed via the :func:`IPython.lib.datapub.publish_data` function: |
|
926 | 929 | |
|
927 | 930 | .. sourcecode:: python |
|
928 | 931 | |
|
929 | 932 | from IPython.kernel.zmq.datapub import publish_data |
|
930 | 933 | ns = dict(x=my_array) |
|
931 | 934 | publish_data(ns) |
|
932 | 935 | |
|
933 | 936 | |
|
934 | 937 | Message type: ``data_pub``:: |
|
935 | 938 | |
|
936 | 939 | content = { |
|
937 | 940 | # the keys of the data dict, after it has been unserialized |
|
938 | 941 | 'keys' : ['a', 'b'] |
|
939 | 942 | } |
|
940 | 943 | # the namespace dict will be serialized in the message buffers, |
|
941 | 944 | # which will have a length of at least one |
|
942 | 945 | buffers = [b'pdict', ...] |
|
943 | 946 | |
|
944 | 947 | |
|
945 | 948 | The interpretation of a sequence of data_pub messages for a given parent request should be |
|
946 | 949 | to update a single namespace with subsequent results. |
|
947 | 950 | |
|
948 | 951 | .. note:: |
|
949 | 952 | |
|
950 | 953 | No frontends directly handle data_pub messages at this time. |
|
951 | 954 | It is currently only used by the client/engines in :mod:`IPython.parallel`, |
|
952 | 955 | where engines may publish *data* to the Client, |
|
953 | 956 | of which the Client can then publish *representations* via ``display_data`` |
|
954 | 957 | to various frontends. |
|
955 | 958 | |
|
956 | 959 | Code inputs |
|
957 | 960 | ----------- |
|
958 | 961 | |
|
959 | 962 | To let all frontends know what code is being executed at any given time, these |
|
960 | 963 | messages contain a re-broadcast of the ``code`` portion of an |
|
961 | 964 | :ref:`execute_request <execute>`, along with the :ref:`execution_count |
|
962 | 965 | <execution_counter>`. |
|
963 | 966 | |
|
964 | 967 | Message type: ``execute_input``:: |
|
965 | 968 | |
|
966 | 969 | content = { |
|
967 | 970 | 'code' : str, # Source code to be executed, one or more lines |
|
968 | 971 | |
|
969 | 972 | # The counter for this execution is also provided so that clients can |
|
970 | 973 | # display it, since IPython automatically creates variables called _iN |
|
971 | 974 | # (for input prompt In[N]). |
|
972 | 975 | 'execution_count' : int |
|
973 | 976 | } |
|
974 | 977 | |
|
975 | 978 | .. versionchanged:: 5.0 |
|
976 | 979 | |
|
977 | 980 | ``pyin`` is renamed to ``execute_input``. |
|
978 | 981 | |
|
979 | 982 | |
|
980 | 983 | Execution results |
|
981 | 984 | ----------------- |
|
982 | 985 | |
|
983 | 986 | Results of an execution are published as an ``execute_result``. |
|
984 | 987 | These are identical to `display_data`_ messages, with the addition of an ``execution_count`` key. |
|
985 | 988 | |
|
986 | 989 | Results can have multiple simultaneous formats depending on its |
|
987 | 990 | configuration. A plain text representation should always be provided |
|
988 | 991 | in the ``text/plain`` mime-type. Frontends are free to display any or all of these |
|
989 | 992 | according to its capabilities. |
|
990 | 993 | Frontends should ignore mime-types they do not understand. The data itself is |
|
991 | 994 | any JSON object and depends on the format. It is often, but not always a string. |
|
992 | 995 | |
|
993 | 996 | Message type: ``execute_result``:: |
|
994 | 997 | |
|
995 | 998 | content = { |
|
996 | 999 | |
|
997 | 1000 | # The counter for this execution is also provided so that clients can |
|
998 | 1001 | # display it, since IPython automatically creates variables called _N |
|
999 | 1002 | # (for prompt N). |
|
1000 | 1003 | 'execution_count' : int, |
|
1001 | 1004 | |
|
1002 | 1005 | # data and metadata are identical to a display_data message. |
|
1003 | 1006 | # the object being displayed is that passed to the display hook, |
|
1004 | 1007 | # i.e. the *result* of the execution. |
|
1005 | 1008 | 'data' : dict, |
|
1006 | 1009 | 'metadata' : dict, |
|
1007 | 1010 | } |
|
1008 | 1011 | |
|
1009 | 1012 | Execution errors |
|
1010 | 1013 | ---------------- |
|
1011 | 1014 | |
|
1012 | 1015 | When an error occurs during code execution |
|
1013 | 1016 | |
|
1014 | 1017 | Message type: ``error``:: |
|
1015 | 1018 | |
|
1016 | 1019 | content = { |
|
1017 | 1020 | # Similar content to the execute_reply messages for the 'error' case, |
|
1018 | 1021 | # except the 'status' field is omitted. |
|
1019 | 1022 | } |
|
1020 | 1023 | |
|
1021 | 1024 | .. versionchanged:: 5.0 |
|
1022 | 1025 | |
|
1023 | 1026 | ``pyerr`` renamed to ``error`` |
|
1024 | 1027 | |
|
1025 | 1028 | Kernel status |
|
1026 | 1029 | ------------- |
|
1027 | 1030 | |
|
1028 | 1031 | This message type is used by frontends to monitor the status of the kernel. |
|
1029 | 1032 | |
|
1030 | 1033 | Message type: ``status``:: |
|
1031 | 1034 | |
|
1032 | 1035 | content = { |
|
1033 | 1036 | # When the kernel starts to handle a message, it will enter the 'busy' |
|
1034 | 1037 | # state and when it finishes, it will enter the 'idle' state. |
|
1035 | 1038 | # The kernel will publish state 'starting' exactly once at process startup. |
|
1036 | 1039 | execution_state : ('busy', 'idle', 'starting') |
|
1037 | 1040 | } |
|
1038 | 1041 | |
|
1039 | 1042 | .. versionchanged:: 5.0 |
|
1040 | 1043 | |
|
1041 | 1044 | Busy and idle messages should be sent before/after handling every message, |
|
1042 | 1045 | not just execution. |
|
1043 | 1046 | |
|
1044 | 1047 | .. note:: |
|
1045 | 1048 | |
|
1046 | 1049 | Extra status messages are added between the notebook webserver and websocket clients |
|
1047 | 1050 | that are not sent by the kernel. These are: |
|
1048 | 1051 | |
|
1049 | 1052 | - restarting (kernel has died, but will be automatically restarted) |
|
1050 | 1053 | - dead (kernel has died, restarting has failed) |
|
1051 | 1054 | |
|
1052 | 1055 | Clear output |
|
1053 | 1056 | ------------ |
|
1054 | 1057 | |
|
1055 | 1058 | This message type is used to clear the output that is visible on the frontend. |
|
1056 | 1059 | |
|
1057 | 1060 | Message type: ``clear_output``:: |
|
1058 | 1061 | |
|
1059 | 1062 | content = { |
|
1060 | 1063 | |
|
1061 | 1064 | # Wait to clear the output until new output is available. Clears the |
|
1062 | 1065 | # existing output immediately before the new output is displayed. |
|
1063 | 1066 | # Useful for creating simple animations with minimal flickering. |
|
1064 | 1067 | 'wait' : bool, |
|
1065 | 1068 | } |
|
1066 | 1069 | |
|
1067 | 1070 | .. versionchanged:: 4.1 |
|
1068 | 1071 | |
|
1069 | 1072 | ``stdout``, ``stderr``, and ``display`` boolean keys for selective clearing are removed, |
|
1070 | 1073 | and ``wait`` is added. |
|
1071 | 1074 | The selective clearing keys are ignored in v4 and the default behavior remains the same, |
|
1072 | 1075 | so v4 clear_output messages will be safely handled by a v4.1 frontend. |
|
1073 | 1076 | |
|
1074 | 1077 | |
|
1075 | 1078 | Messages on the stdin ROUTER/DEALER sockets |
|
1076 | 1079 | =========================================== |
|
1077 | 1080 | |
|
1078 | 1081 | This is a socket where the request/reply pattern goes in the opposite direction: |
|
1079 | 1082 | from the kernel to a *single* frontend, and its purpose is to allow |
|
1080 | 1083 | ``raw_input`` and similar operations that read from ``sys.stdin`` on the kernel |
|
1081 | 1084 | to be fulfilled by the client. The request should be made to the frontend that |
|
1082 | 1085 | made the execution request that prompted ``raw_input`` to be called. For now we |
|
1083 | 1086 | will keep these messages as simple as possible, since they only mean to convey |
|
1084 | 1087 | the ``raw_input(prompt)`` call. |
|
1085 | 1088 | |
|
1086 | 1089 | Message type: ``input_request``:: |
|
1087 | 1090 | |
|
1088 | 1091 | content = { |
|
1089 | 1092 | # the text to show at the prompt |
|
1090 | 1093 | 'prompt' : str, |
|
1091 | 1094 | # Is the request for a password? |
|
1092 | 1095 | # If so, the frontend shouldn't echo input. |
|
1093 | 1096 | 'password' : bool |
|
1094 | 1097 | } |
|
1095 | 1098 | |
|
1096 | 1099 | Message type: ``input_reply``:: |
|
1097 | 1100 | |
|
1098 | 1101 | content = { 'value' : str } |
|
1099 | 1102 | |
|
1100 | 1103 | |
|
1101 | 1104 | When ``password`` is True, the frontend should not echo the input as it is entered. |
|
1102 | 1105 | |
|
1103 | 1106 | .. versionchanged:: 5.0 |
|
1104 | 1107 | |
|
1105 | 1108 | ``password`` key added. |
|
1106 | 1109 | |
|
1107 | 1110 | .. note:: |
|
1108 | 1111 | |
|
1109 | 1112 | The stdin socket of the client is required to have the same zmq IDENTITY |
|
1110 | 1113 | as the client's shell socket. |
|
1111 | 1114 | Because of this, the ``input_request`` must be sent with the same IDENTITY |
|
1112 | 1115 | routing prefix as the ``execute_reply`` in order for the frontend to receive |
|
1113 | 1116 | the message. |
|
1114 | 1117 | |
|
1115 | 1118 | .. note:: |
|
1116 | 1119 | |
|
1117 | 1120 | We do not explicitly try to forward the raw ``sys.stdin`` object, because in |
|
1118 | 1121 | practice the kernel should behave like an interactive program. When a |
|
1119 | 1122 | program is opened on the console, the keyboard effectively takes over the |
|
1120 | 1123 | ``stdin`` file descriptor, and it can't be used for raw reading anymore. |
|
1121 | 1124 | Since the IPython kernel effectively behaves like a console program (albeit |
|
1122 | 1125 | one whose "keyboard" is actually living in a separate process and |
|
1123 | 1126 | transported over the zmq connection), raw ``stdin`` isn't expected to be |
|
1124 | 1127 | available. |
|
1125 | 1128 | |
|
1126 | 1129 | .. _kernel_heartbeat: |
|
1127 | 1130 | |
|
1128 | 1131 | Heartbeat for kernels |
|
1129 | 1132 | ===================== |
|
1130 | 1133 | |
|
1131 | 1134 | Clients send ping messages on a REQ socket, which are echoed right back |
|
1132 | 1135 | from the Kernel's REP socket. These are simple bytestrings, not full JSON messages described above. |
|
1133 | 1136 | |
|
1134 | 1137 | |
|
1135 | 1138 | Custom Messages |
|
1136 | 1139 | =============== |
|
1137 | 1140 | |
|
1138 | 1141 | .. versionadded:: 4.1 |
|
1139 | 1142 | |
|
1140 | 1143 | IPython 2.0 (msgspec v4.1) adds a messaging system for developers to add their own objects with Frontend |
|
1141 | 1144 | and Kernel-side components, and allow them to communicate with each other. |
|
1142 | 1145 | To do this, IPython adds a notion of a ``Comm``, which exists on both sides, |
|
1143 | 1146 | and can communicate in either direction. |
|
1144 | 1147 | |
|
1145 | 1148 | These messages are fully symmetrical - both the Kernel and the Frontend can send each message, |
|
1146 | 1149 | and no messages expect a reply. |
|
1147 | 1150 | The Kernel listens for these messages on the Shell channel, |
|
1148 | 1151 | and the Frontend listens for them on the IOPub channel. |
|
1149 | 1152 | |
|
1150 | 1153 | Opening a Comm |
|
1151 | 1154 | -------------- |
|
1152 | 1155 | |
|
1153 | 1156 | Opening a Comm produces a ``comm_open`` message, to be sent to the other side:: |
|
1154 | 1157 | |
|
1155 | 1158 | { |
|
1156 | 1159 | 'comm_id' : 'u-u-i-d', |
|
1157 | 1160 | 'target_name' : 'my_comm', |
|
1158 | 1161 | 'data' : {} |
|
1159 | 1162 | } |
|
1160 | 1163 | |
|
1161 | 1164 | Every Comm has an ID and a target name. |
|
1162 | 1165 | The code handling the message on the receiving side is responsible for maintaining a mapping |
|
1163 | 1166 | of target_name keys to constructors. |
|
1164 | 1167 | After a ``comm_open`` message has been sent, |
|
1165 | 1168 | there should be a corresponding Comm instance on both sides. |
|
1166 | 1169 | The ``data`` key is always a dict and can be any extra JSON information used in initialization of the comm. |
|
1167 | 1170 | |
|
1168 | 1171 | If the ``target_name`` key is not found on the receiving side, |
|
1169 | 1172 | then it should immediately reply with a ``comm_close`` message to avoid an inconsistent state. |
|
1170 | 1173 | |
|
1171 | 1174 | Comm Messages |
|
1172 | 1175 | ------------- |
|
1173 | 1176 | |
|
1174 | 1177 | Comm messages are one-way communications to update comm state, |
|
1175 | 1178 | used for synchronizing widget state, or simply requesting actions of a comm's counterpart. |
|
1176 | 1179 | |
|
1177 | 1180 | Essentially, each comm pair defines their own message specification implemented inside the ``data`` dict. |
|
1178 | 1181 | |
|
1179 | 1182 | There are no expected replies (of course, one side can send another ``comm_msg`` in reply). |
|
1180 | 1183 | |
|
1181 | 1184 | Message type: ``comm_msg``:: |
|
1182 | 1185 | |
|
1183 | 1186 | { |
|
1184 | 1187 | 'comm_id' : 'u-u-i-d', |
|
1185 | 1188 | 'data' : {} |
|
1186 | 1189 | } |
|
1187 | 1190 | |
|
1188 | 1191 | Tearing Down Comms |
|
1189 | 1192 | ------------------ |
|
1190 | 1193 | |
|
1191 | 1194 | Since comms live on both sides, when a comm is destroyed the other side must be notified. |
|
1192 | 1195 | This is done with a ``comm_close`` message. |
|
1193 | 1196 | |
|
1194 | 1197 | Message type: ``comm_close``:: |
|
1195 | 1198 | |
|
1196 | 1199 | { |
|
1197 | 1200 | 'comm_id' : 'u-u-i-d', |
|
1198 | 1201 | 'data' : {} |
|
1199 | 1202 | } |
|
1200 | 1203 | |
|
1201 | 1204 | Output Side Effects |
|
1202 | 1205 | ------------------- |
|
1203 | 1206 | |
|
1204 | 1207 | Since comm messages can execute arbitrary user code, |
|
1205 | 1208 | handlers should set the parent header and publish status busy / idle, |
|
1206 | 1209 | just like an execute request. |
|
1207 | 1210 | |
|
1208 | 1211 | |
|
1209 | 1212 | To Do |
|
1210 | 1213 | ===== |
|
1211 | 1214 | |
|
1212 | 1215 | Missing things include: |
|
1213 | 1216 | |
|
1214 | 1217 | * Important: finish thinking through the payload concept and API. |
|
1215 | 1218 | |
|
1216 | 1219 | .. include:: ../links.txt |
General Comments 0
You need to be logged in to leave comments.
Login now