##// END OF EJS Templates
msg spec 5.0
MinRK -
Show More
@@ -0,0 +1,70 b''
1 .. _execution_semantics:
2
3 Execution semantics in the IPython kernel
4 =========================================
5
6 The execution of use code consists of the following phases:
7
8 1. Fire the ``pre_execute`` event.
9 2. Fire the ``pre_run_cell`` event unless silent is True.
10 3. Execute the ``code`` field, see below for details.
11 4. If execution succeeds, expressions in ``user_expressions`` are computed.
12 This ensures that any error in the expressions don't affect the main code execution.
13 5. Fire the post_execute eventCall any method registered with :meth:`register_post_execute`.
14
15 .. warning::
16
17 The API for running code before/after the main code block is likely to
18 change soon. Both the ``pre_runcode_hook`` and the
19 :meth:`register_post_execute` are susceptible to modification, as we find a
20 consistent model for both.
21
22 To understand how the ``code`` field is executed, one must know that Python
23 code can be compiled in one of three modes (controlled by the ``mode`` argument
24 to the :func:`compile` builtin):
25
26 *single*
27 Valid for a single interactive statement (though the source can contain
28 multiple lines, such as a for loop). When compiled in this mode, the
29 generated bytecode contains special instructions that trigger the calling of
30 :func:`sys.displayhook` for any expression in the block that returns a value.
31 This means that a single statement can actually produce multiple calls to
32 :func:`sys.displayhook`, if for example it contains a loop where each
33 iteration computes an unassigned expression would generate 10 calls::
34
35 for i in range(10):
36 i**2
37
38 *exec*
39 An arbitrary amount of source code, this is how modules are compiled.
40 :func:`sys.displayhook` is *never* implicitly called.
41
42 *eval*
43 A single expression that returns a value. :func:`sys.displayhook` is *never*
44 implicitly called.
45
46
47 The ``code`` field is split into individual blocks each of which is valid for
48 execution in 'single' mode, and then:
49
50 - If there is only a single block: it is executed in 'single' mode.
51
52 - If there is more than one block:
53
54 * if the last one is a single line long, run all but the last in 'exec' mode
55 and the very last one in 'single' mode. This makes it easy to type simple
56 expressions at the end to see computed values.
57
58 * if the last one is no more than two lines long, run all but the last in
59 'exec' mode and the very last one in 'single' mode. This makes it easy to
60 type simple expressions at the end to see computed values. - otherwise
61 (last one is also multiline), run all in 'exec' mode
62
63 * otherwise (last one is also multiline), run all in 'exec' mode as a single
64 unit.
65
66
67 Errors in any registered post_execute functions are reported,
68 and the failing function is removed from the post_execution set so that it does
69 not continue triggering failures.
70
@@ -20,6 +20,7 b' on the IPython GitHub wiki.'
20 :maxdepth: 1
20 :maxdepth: 1
21
21
22 messaging
22 messaging
23 execution
23 parallel_messages
24 parallel_messages
24 parallel_connections
25 parallel_connections
25 lexer
26 lexer
This diff has been collapsed as it changes many lines, (522 lines changed) Show them Hide them
@@ -9,7 +9,7 b' Versioning'
9 ==========
9 ==========
10
10
11 The IPython message specification is versioned independently of IPython.
11 The IPython message specification is versioned independently of IPython.
12 The current version of the specification is 4.1.
12 The current version of the specification is 5.0.0.
13
13
14
14
15 Introduction
15 Introduction
@@ -38,22 +38,13 b' The basic design is explained in the following diagram:'
38 A single kernel can be simultaneously connected to one or more frontends. The
38 A single kernel can be simultaneously connected to one or more frontends. The
39 kernel has three sockets that serve the following functions:
39 kernel has three sockets that serve the following functions:
40
40
41 1. stdin: this ROUTER socket is connected to all frontends, and it allows
41 1. Shell: this single ROUTER socket allows multiple incoming connections from
42 the kernel to request input from the active frontend when :func:`raw_input` is called.
43 The frontend that executed the code has a DEALER socket that acts as a 'virtual keyboard'
44 for the kernel while this communication is happening (illustrated in the
45 figure by the black outline around the central keyboard). In practice,
46 frontends may display such kernel requests using a special input widget or
47 otherwise indicating that the user is to type input for the kernel instead
48 of normal commands in the frontend.
49
50 2. Shell: this single ROUTER socket allows multiple incoming connections from
51 frontends, and this is the socket where requests for code execution, object
42 frontends, and this is the socket where requests for code execution, object
52 information, prompts, etc. are made to the kernel by any frontend. The
43 information, prompts, etc. are made to the kernel by any frontend. The
53 communication on this socket is a sequence of request/reply actions from
44 communication on this socket is a sequence of request/reply actions from
54 each frontend and the kernel.
45 each frontend and the kernel.
55
46
56 3. IOPub: this socket is the 'broadcast channel' where the kernel publishes all
47 2. IOPub: this socket is the 'broadcast channel' where the kernel publishes all
57 side effects (stdout, stderr, etc.) as well as the requests coming from any
48 side effects (stdout, stderr, etc.) as well as the requests coming from any
58 client over the shell socket and its own requests on the stdin socket. There
49 client over the shell socket and its own requests on the stdin socket. There
59 are a number of actions in Python which generate side effects: :func:`print`
50 are a number of actions in Python which generate side effects: :func:`print`
@@ -64,11 +55,23 b' kernel has three sockets that serve the following functions:'
64 about communications taking place with one client over the shell channel
55 about communications taking place with one client over the shell channel
65 to be made available to all clients in a uniform manner.
56 to be made available to all clients in a uniform manner.
66
57
58 3. stdin: this ROUTER socket is connected to all frontends, and it allows
59 the kernel to request input from the active frontend when :func:`raw_input` is called.
60 The frontend that executed the code has a DEALER socket that acts as a 'virtual keyboard'
61 for the kernel while this communication is happening (illustrated in the
62 figure by the black outline around the central keyboard). In practice,
63 frontends may display such kernel requests using a special input widget or
64 otherwise indicating that the user is to type input for the kernel instead
65 of normal commands in the frontend.
66
67 All messages are tagged with enough information (details below) for clients
67 All messages are tagged with enough information (details below) for clients
68 to know which messages come from their own interaction with the kernel and
68 to know which messages come from their own interaction with the kernel and
69 which ones are from other clients, so they can display each type
69 which ones are from other clients, so they can display each type
70 appropriately.
70 appropriately.
71
71
72 4. Control: This channel is identical to Shell, but operates on a separate socket,
73 to allow important messages to avoid queueing behind execution requests (e.g. shutdown or abort).
74
72 The actual format of the messages allowed on each of these channels is
75 The actual format of the messages allowed on each of these channels is
73 specified below. Messages are dicts of dicts with string keys and values that
76 specified below. Messages are dicts of dicts with string keys and values that
74 are reasonably representable in JSON. Our current implementation uses JSON
77 are reasonably representable in JSON. Our current implementation uses JSON
@@ -119,6 +122,10 b' A message is defined by the following four-dictionary structure::'
119 'content' : dict,
122 'content' : dict,
120 }
123 }
121
124
125 .. versionchanged:: 5.0.0
126
127 ``version`` key added to the header.
128
122 The Wire Protocol
129 The Wire Protocol
123 =================
130 =================
124
131
@@ -250,13 +257,11 b' Message type: ``execute_request``::'
250 'code' : str,
257 'code' : str,
251
258
252 # A boolean flag which, if True, signals the kernel to execute
259 # A boolean flag which, if True, signals the kernel to execute
253 # this code as quietly as possible. This means that the kernel
260 # this code as quietly as possible.
254 # will compile the code with 'exec' instead of 'single' (so
261 # silent=True forces store_history to be False,
255 # sys.displayhook will not fire), forces store_history to be False,
256 # and will *not*:
262 # and will *not*:
257 # - broadcast exceptions on the PUB socket
263 # - broadcast output on the IOPUB channel
258 # - do any logging
264 # - have an execute_result
259 #
260 # The default is False.
265 # The default is False.
261 'silent' : bool,
266 'silent' : bool,
262
267
@@ -265,7 +270,7 b' Message type: ``execute_request``::'
265 # is forced to be False.
270 # is forced to be False.
266 'store_history' : bool,
271 'store_history' : bool,
267
272
268 # Similarly, a dict mapping names to expressions to be evaluated in the
273 # A dict mapping names to expressions to be evaluated in the
269 # user's dict. The rich display-data representation of each will be evaluated after execution.
274 # user's dict. The rich display-data representation of each will be evaluated after execution.
270 # See the display_data content for the structure of the representation data.
275 # See the display_data content for the structure of the representation data.
271 'user_expressions' : dict,
276 'user_expressions' : dict,
@@ -276,12 +281,13 b' Message type: ``execute_request``::'
276 'allow_stdin' : True,
281 'allow_stdin' : True,
277 }
282 }
278
283
279 The ``code`` field contains a single string (possibly multiline). The kernel
284 .. versionchanged:: 5.0.0
280 is responsible for splitting this into one or more independent execution blocks
285
281 and deciding whether to compile these in 'single' or 'exec' mode (see below for
286 ``user_variables`` removed, because it is redundant with user_expressions.
282 detailed execution semantics).
287
288 The ``code`` field contains a single string (possibly multiline) to be executed.
283
289
284 The ``user_expressions`` fields deserve a detailed explanation. In the past, IPython had
290 The ``user_expressions`` field deserves a detailed explanation. In the past, IPython had
285 the notion of a prompt string that allowed arbitrary code to be evaluated, and
291 the notion of a prompt string that allowed arbitrary code to be evaluated, and
286 this was put to good use by many in creating prompts that displayed system
292 this was put to good use by many in creating prompts that displayed system
287 status, path information, and even more esoteric uses like remote instrument
293 status, path information, and even more esoteric uses like remote instrument
@@ -289,91 +295,7 b' status acquired over the network. But now that IPython has a clean separation'
289 between the kernel and the clients, the kernel has no prompt knowledge; prompts
295 between the kernel and the clients, the kernel has no prompt knowledge; prompts
290 are a frontend feature, and it should be even possible for different
296 are a frontend feature, and it should be even possible for different
291 frontends to display different prompts while interacting with the same kernel.
297 frontends to display different prompts while interacting with the same kernel.
292
298 ``user_expressions`` can be used to retrieve this information.
293 The kernel provides the ability to retrieve data from the user's namespace
294 after the execution of the main ``code``, thanks to two fields in the
295 ``execute_request`` message:
296
297 - ``user_expressions``: For more complex expressions that require function
298 evaluations, a dict can be provided with string keys and arbitrary python
299 expressions as values. The return message will contain also a dict with the
300 same keys and the rich representations of the evaluated expressions as value.
301
302 With this information, frontends can display any status information they wish
303 in the form that best suits each frontend (a status line, a popup, inline for a
304 terminal, etc).
305
306 .. Note::
307
308 In order to obtain the current execution counter for the purposes of
309 displaying input prompts, frontends simply make an execution request with an
310 empty code string and ``silent=True``.
311
312 Execution semantics
313 ~~~~~~~~~~~~~~~~~~~
314
315 When the silent flag is false, the execution of use code consists of the
316 following phases (in silent mode, only the ``code`` field is executed):
317
318 1. Run the ``pre_runcode_hook``.
319
320 2. Execute the ``code`` field, see below for details.
321
322 3. If #2 succeeds, expressions in ``user_expressions`` are computed.
323 This ensures that any error in the expressions don't affect the main code execution.
324
325 4. Call any method registered with :meth:`register_post_execute`.
326
327 .. warning::
328
329 The API for running code before/after the main code block is likely to
330 change soon. Both the ``pre_runcode_hook`` and the
331 :meth:`register_post_execute` are susceptible to modification, as we find a
332 consistent model for both.
333
334 To understand how the ``code`` field is executed, one must know that Python
335 code can be compiled in one of three modes (controlled by the ``mode`` argument
336 to the :func:`compile` builtin):
337
338 *single*
339 Valid for a single interactive statement (though the source can contain
340 multiple lines, such as a for loop). When compiled in this mode, the
341 generated bytecode contains special instructions that trigger the calling of
342 :func:`sys.displayhook` for any expression in the block that returns a value.
343 This means that a single statement can actually produce multiple calls to
344 :func:`sys.displayhook`, if for example it contains a loop where each
345 iteration computes an unassigned expression would generate 10 calls::
346
347 for i in range(10):
348 i**2
349
350 *exec*
351 An arbitrary amount of source code, this is how modules are compiled.
352 :func:`sys.displayhook` is *never* implicitly called.
353
354 *eval*
355 A single expression that returns a value. :func:`sys.displayhook` is *never*
356 implicitly called.
357
358
359 The ``code`` field is split into individual blocks each of which is valid for
360 execution in 'single' mode, and then:
361
362 - If there is only a single block: it is executed in 'single' mode.
363
364 - If there is more than one block:
365
366 * if the last one is a single line long, run all but the last in 'exec' mode
367 and the very last one in 'single' mode. This makes it easy to type simple
368 expressions at the end to see computed values.
369
370 * if the last one is no more than two lines long, run all but the last in
371 'exec' mode and the very last one in 'single' mode. This makes it easy to
372 type simple expressions at the end to see computed values. - otherwise
373 (last one is also multiline), run all in 'exec' mode
374
375 * otherwise (last one is also multiline), run all in 'exec' mode as a single
376 unit.
377
299
378 Any error in evaluating any expression in ``user_expressions`` will result in
300 Any error in evaluating any expression in ``user_expressions`` will result in
379 only that key containing a standard error message, of the form::
301 only that key containing a standard error message, of the form::
@@ -385,27 +307,30 b' only that key containing a standard error message, of the form::'
385 'traceback' : ...
307 'traceback' : ...
386 }
308 }
387
309
388 Errors in any registered post_execute functions are also reported,
310 .. Note::
389 and the failing function is removed from the post_execution set so that it does
311
390 not continue triggering failures.
312 In order to obtain the current execution counter for the purposes of
313 displaying input prompts, frontends may make an execution request with an
314 empty code string and ``silent=True``.
391
315
392 Upon completion of the execution request, the kernel *always* sends a reply,
316 Upon completion of the execution request, the kernel *always* sends a reply,
393 with a status code indicating what happened and additional data depending on
317 with a status code indicating what happened and additional data depending on
394 the outcome. See :ref:`below <execution_results>` for the possible return
318 the outcome. See :ref:`below <execution_results>` for the possible return
395 codes and associated data.
319 codes and associated data.
396
320
321 .. seealso::
322
323 :ref:`execution_semantics`
397
324
398 .. _execution_counter:
325 .. _execution_counter:
399
326
400 Execution counter (prompt number)
327 Execution counter (prompt number)
401 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
328 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
402
329
403 The kernel has a single, monotonically increasing counter of all execution
330 The kernel should have a single, monotonically increasing counter of all execution
404 requests that are made with ``store_history=True``. This counter is used to populate
331 requests that are made with ``store_history=True``. This counter is used to populate
405 the ``In[n]``, ``Out[n]`` and ``_n`` variables, so clients will likely want to
332 the ``In[n]`` and ``Out[n]`` prompts. The value of this counter will be returned as the
406 display it in some form to the user, which will typically (but not necessarily)
333 ``execution_count`` field of all ``execute_reply`` and ``execute_input`` messages.
407 be done in the prompts. The value of this counter will be returned as the
408 ``execution_count`` field of all ``execute_reply`` and ``pyin`` messages.
409
334
410 .. _execution_results:
335 .. _execution_results:
411
336
@@ -441,6 +366,10 b" When status is 'ok', the following extra fields are present::"
441 'user_expressions' : dict,
366 'user_expressions' : dict,
442 }
367 }
443
368
369 .. versionchanged:: 5.0.0
370
371 ``user_variables`` is removed, use user_expressions instead.
372
444 .. admonition:: Execution payloads
373 .. admonition:: Execution payloads
445
374
446 The notion of an 'execution payload' is different from a return value of a
375 The notion of an 'execution payload' is different from a return value of a
@@ -481,145 +410,82 b" When status is 'abort', there are for now no additional data fields. This"
481 happens when the kernel was interrupted by a signal.
410 happens when the kernel was interrupted by a signal.
482
411
483
412
484 Object information
413 Introspection
485 ------------------
414 -------------
486
415
487 One of IPython's most used capabilities is the introspection of Python objects
416 Code can be inspected to show useful information to the user.
488 in the user's namespace, typically invoked via the ``?`` and ``??`` characters
417 It is up to the Kernel to decide what information should be displayed, and its formatting.
489 (which in reality are shorthands for the ``%pinfo`` magic). This is used often
490 enough that it warrants an explicit message type, especially because frontends
491 may want to get object information in response to user keystrokes (like Tab or
492 F1) besides from the user explicitly typing code like ``x??``.
493
418
494 Message type: ``object_info_request``::
419 Message type: ``inspect_request``::
495
420
496 content = {
421 content = {
497 # The (possibly dotted) name of the object to be searched in all
422 # The code context in which introspection is requested
498 # relevant namespaces
423 # this may be up to an entire multiline cell.
499 'oname' : str,
424 'code' : str,
425
426 # The cursor position within 'code' (in unicode characters) where inspection is requested
427 'cursor_pos' : int,
500
428
501 # The level of detail desired. The default (0) is equivalent to typing
429 # The level of detail desired. In IPython, the default (0) is equivalent to typing
502 # 'x?' at the prompt, 1 is equivalent to 'x??'.
430 # 'x?' at the prompt, 1 is equivalent to 'x??'.
503 'detail_level' : int,
431 # The difference is up to kernels, but in IPython level 1 includes the source code
432 # if available.
433 'detail_level' : 0 or 1,
504 }
434 }
505
435
506 The returned information will be a dictionary with keys very similar to the
436 .. versionchanged:: 5.0.0
507 field names that IPython prints at the terminal.
437
508
438 ``object_info_request`` renamed to ``inspect_request``.
509 Message type: ``object_info_reply``::
439
440 .. versionchanged:: 5.0.0
441
442 ``name`` key replaced with ``code`` and ``cursor_pos``,
443 moving the lexing responsibility to the kernel.
444
445 The reply is a mime-bundle, like a `display_data`_ message,
446 which should be a formatted representation of information about the context.
447 In the notebook, this is used to show tooltips over function calls, etc.
448
449 Message type: ``inspect_reply``::
510
450
511 content = {
451 content = {
512 # The name the object was requested under
452 # 'ok' if the request succeeded or 'error', with error information as in all other replies.
513 'name' : str,
453 'status' : 'ok',
514
454
515 # Boolean flag indicating whether the named object was found or not. If
455 # data can be empty if nothing is found
516 # it's false, all other fields will be empty.
456 'data' : dict,
517 'found' : bool,
457 'metadata' : dict,
518
519 # Flags for magics and system aliases
520 'ismagic' : bool,
521 'isalias' : bool,
522
523 # The name of the namespace where the object was found ('builtin',
524 # 'magics', 'alias', 'interactive', etc.)
525 'namespace' : str,
526
527 # The type name will be type.__name__ for normal Python objects, but it
528 # can also be a string like 'Magic function' or 'System alias'
529 'type_name' : str,
530
531 # The string form of the object, possibly truncated for length if
532 # detail_level is 0
533 'string_form' : str,
534
535 # For objects with a __class__ attribute this will be set
536 'base_class' : str,
537
538 # For objects with a __len__ attribute this will be set
539 'length' : int,
540
541 # If the object is a function, class or method whose file we can find,
542 # we give its full path
543 'file' : str,
544
545 # For pure Python callable objects, we can reconstruct the object
546 # definition line which provides its call signature. For convenience this
547 # is returned as a single 'definition' field, but below the raw parts that
548 # compose it are also returned as the argspec field.
549 'definition' : str,
550
551 # The individual parts that together form the definition string. Clients
552 # with rich display capabilities may use this to provide a richer and more
553 # precise representation of the definition line (e.g. by highlighting
554 # arguments based on the user's cursor position). For non-callable
555 # objects, this field is empty.
556 'argspec' : { # The names of all the arguments
557 args : list,
558 # The name of the varargs (*args), if any
559 varargs : str,
560 # The name of the varkw (**kw), if any
561 varkw : str,
562 # The values (as strings) of all default arguments. Note
563 # that these must be matched *in reverse* with the 'args'
564 # list above, since the first positional args have no default
565 # value at all.
566 defaults : list,
567 },
568
569 # For instances, provide the constructor signature (the definition of
570 # the __init__ method):
571 'init_definition' : str,
572
573 # Docstrings: for any object (function, method, module, package) with a
574 # docstring, we show it. But in addition, we may provide additional
575 # docstrings. For example, for instances we will show the constructor
576 # and class docstrings as well, if available.
577 'docstring' : str,
578
579 # For instances, provide the constructor and class docstrings
580 'init_docstring' : str,
581 'class_docstring' : str,
582
583 # If it's a callable object whose call method has a separate docstring and
584 # definition line:
585 'call_def' : str,
586 'call_docstring' : str,
587
588 # If detail_level was 1, we also try to find the source code that
589 # defines the object, if possible. The string 'None' will indicate
590 # that no source was found.
591 'source' : str,
592 }
458 }
593
459
594
460 .. versionchanged:: 5.0.0
595 Complete
461
596 --------
462 ``object_info_reply`` renamed to ``inspect_reply``.
463
464 .. versionchanged:: 5.0.0
465
466 Reply is changed from structured data to a mime bundle, allowing formatting decisions to be made by the kernel.
467
468 Completion
469 ----------
597
470
598 Message type: ``complete_request``::
471 Message type: ``complete_request``::
599
472
600 content = {
473 content = {
601 # The text to be completed, such as 'a.is'
474 # The code context in which completion is requested
602 # this may be an empty string if the frontend does not do any lexing,
475 # this may be up to an entire multiline cell, such as
603 # in which case the kernel must figure out the completion
476 # 'foo = a.isal'
604 # based on 'line' and 'cursor_pos'.
477 'code' : str,
605 'text' : str,
478
606
479 # The cursor position within 'code' (in unicode characters) where completion is requested
607 # The full line, such as 'print a.is'. This allows completers to
608 # make decisions that may require information about more than just the
609 # current word.
610 'line' : str,
611
612 # The entire block of text where the line is. This may be useful in the
613 # case of multiline completions where more context may be needed. Note: if
614 # in practice this field proves unnecessary, remove it to lighten the
615 # messages.
616
617 'block' : str or null/None,
618
619 # The position of the cursor where the user hit 'TAB' on the line.
620 'cursor_pos' : int,
480 'cursor_pos' : int,
621 }
481 }
622
482
483 .. versionchanged:: 5.0.0
484
485 ``line``, ``block``, and ``text`` keys are removed in favor of a single ``code`` for context.
486 Lexing is up to the kernel.
487
488
623 Message type: ``complete_reply``::
489 Message type: ``complete_reply``::
624
490
625 content = {
491 content = {
@@ -627,11 +493,13 b' Message type: ``complete_reply``::'
627 # ['a.isalnum', 'a.isalpha'] for the above example.
493 # ['a.isalnum', 'a.isalpha'] for the above example.
628 'matches' : list,
494 'matches' : list,
629
495
630 # the substring of the matched text
496 # The range of text that should be replaced by the above matches when a completion is accepted.
631 # this is typically the common prefix of the matches,
497 # typically cursor_end is the same as cursor_pos in the request.
632 # and the text that is already in the block that would be replaced by the full completion.
498 'cursor_start' : int,
633 # This would be 'a.is' in the above example.
499 'cursor_end' : int,
634 'matched_text' : str,
500
501 # Information that frontend plugins might use for extra display information about completions.
502 'metadata' : dict,
635
503
636 # status should be 'ok' unless an exception was raised during the request,
504 # status should be 'ok' unless an exception was raised during the request,
637 # in which case it should be 'error', along with the usual error message content
505 # in which case it should be 'error', along with the usual error message content
@@ -639,7 +507,12 b' Message type: ``complete_reply``::'
639 'status' : 'ok'
507 'status' : 'ok'
640 }
508 }
641
509
642
510 .. versionchanged:: 5.0.0
511
512 - ``matched_text`` is removed in favor of ``cursor_start`` and ``cursor_end``.
513 - ``metadata`` is added for extended information.
514
515
643 History
516 History
644 -------
517 -------
645
518
@@ -735,32 +608,47 b' Message type: ``kernel_info_request``::'
735 Message type: ``kernel_info_reply``::
608 Message type: ``kernel_info_reply``::
736
609
737 content = {
610 content = {
738 # Version of messaging protocol (mandatory).
611 # Version of messaging protocol.
739 # The first integer indicates major version. It is incremented when
612 # The first integer indicates major version. It is incremented when
740 # there is any backward incompatible change.
613 # there is any backward incompatible change.
741 # The second integer indicates minor version. It is incremented when
614 # The second integer indicates minor version. It is incremented when
742 # there is any backward compatible change.
615 # there is any backward compatible change.
743 'protocol_version': 'X.Y.Z',
616 'protocol_version': 'X.Y.Z',
744
617
745 # IPython version number (optional).
618 # The kernel implementation name
746 # Non-python kernel backend may not have this version number.
619 # (e.g. 'ipython' for the IPython kernel)
747 # could be '2.0.0-dev' for development version
620 'implementation': str,
748 'ipython_version': 'X.Y.Z',
621
622 # Implementation version number.
623 # The version number of the kernel's implementation
624 # (e.g. IPython.__version__ for the IPython kernel)
625 'implementation_version': 'X.Y.Z',
749
626
750 # Language version number (mandatory).
627 # Programming language in which kernel is implemented.
628 # Kernel included in IPython returns 'python'.
629 'language': str,
630
631 # Language version number.
751 # It is Python version number (e.g., '2.7.3') for the kernel
632 # It is Python version number (e.g., '2.7.3') for the kernel
752 # included in IPython.
633 # included in IPython.
753 'language_version': 'X.Y.Z',
634 'language_version': 'X.Y.Z',
754
635
755 # Programming language in which kernel is implemented (mandatory).
636 # A banner of information about the kernel,
756 # Kernel included in IPython returns 'python'.
637 # which may be desplayed in console environments.
757 'language': str,
638 'banner' : str,
758 }
639 }
759
640
760 .. versionchanged:: 5.0
641 .. versionchanged:: 5.0.0
642
643 Versions changed from lists of integers to strings.
644
645 .. versionchanged:: 5.0.0
646
647 ``ipython_version`` is removed.
761
648
762 In protocol version 4.0, versions were given as lists of numbers,
649 .. versionchanged:: 5.0.0
763 not version strings.
650
651 ``implementation``, ``implementation_version``, and ``banner`` keys are added.
764
652
765
653
766 Kernel shutdown
654 Kernel shutdown
@@ -833,7 +721,9 b' Some questions remain about this design:'
833
721
834 * Do we use this message type for execute_result/displayhook? Probably not, because
722 * Do we use this message type for execute_result/displayhook? Probably not, because
835 the displayhook also has to handle the Out prompt display. On the other hand
723 the displayhook also has to handle the Out prompt display. On the other hand
836 we could put that information into the metadata secion.
724 we could put that information into the metadata section.
725
726 .. _display_data:
837
727
838 Message type: ``display_data``::
728 Message type: ``display_data``::
839
729
@@ -862,7 +752,7 b' with a reasonably unique name to avoid conflicts.'
862 The only metadata keys currently defined in IPython are the width and height
752 The only metadata keys currently defined in IPython are the width and height
863 of images::
753 of images::
864
754
865 'metadata' : {
755 metadata = {
866 'image/png' : {
756 'image/png' : {
867 'width': 640,
757 'width': 640,
868 'height': 480
758 'height': 480
@@ -870,6 +760,12 b' of images::'
870 }
760 }
871
761
872
762
763 .. versionchanged:: 5.0.0
764
765 `application/json` data should be unpacked JSON data,
766 not double-serialized as a JSON string.
767
768
873 Raw Data Publication
769 Raw Data Publication
874 --------------------
770 --------------------
875
771
@@ -889,11 +785,11 b' Message type: ``data_pub``::'
889
785
890 content = {
786 content = {
891 # the keys of the data dict, after it has been unserialized
787 # the keys of the data dict, after it has been unserialized
892 keys = ['a', 'b']
788 'keys' : ['a', 'b']
893 }
789 }
894 # the namespace dict will be serialized in the message buffers,
790 # the namespace dict will be serialized in the message buffers,
895 # which will have a length of at least one
791 # which will have a length of at least one
896 buffers = ['pdict', ...]
792 buffers = [b'pdict', ...]
897
793
898
794
899 The interpretation of a sequence of data_pub messages for a given parent request should be
795 The interpretation of a sequence of data_pub messages for a given parent request should be
@@ -907,15 +803,15 b' to update a single namespace with subsequent results.'
907 of which the Client can then publish *representations* via ``display_data``
803 of which the Client can then publish *representations* via ``display_data``
908 to various frontends.
804 to various frontends.
909
805
910 Python inputs
806 Code inputs
911 -------------
807 -----------
912
808
913 To let all frontends know what code is being executed at any given time, these
809 To let all frontends know what code is being executed at any given time, these
914 messages contain a re-broadcast of the ``code`` portion of an
810 messages contain a re-broadcast of the ``code`` portion of an
915 :ref:`execute_request <execute>`, along with the :ref:`execution_count
811 :ref:`execute_request <execute>`, along with the :ref:`execution_count
916 <execution_counter>`.
812 <execution_counter>`.
917
813
918 Message type: ``pyin``::
814 Message type: ``execute_input``::
919
815
920 content = {
816 content = {
921 'code' : str, # Source code to be executed, one or more lines
817 'code' : str, # Source code to be executed, one or more lines
@@ -926,29 +822,22 b' Message type: ``pyin``::'
926 'execution_count' : int
822 'execution_count' : int
927 }
823 }
928
824
929 Python outputs
825 .. versionchanged:: 5.0.0
930 --------------
826
827 ``pyin`` is renamed to ``execute_input``.
828
931
829
932 When Python produces output from code that has been compiled in with the
830 Execution results
933 'single' flag to :func:`compile`, any expression that produces a value (such as
831 -----------------
934 ``1+1``) is passed to ``sys.displayhook``, which is a callable that can do with
832
935 this value whatever it wants. The default behavior of ``sys.displayhook`` in
833 Results of an execution are published as an ``execute_result``.
936 the Python interactive prompt is to print to ``sys.stdout`` the :func:`repr` of
834 These are identical to `display_data`_ messages, with the addition of an ``execution_count`` key.
937 the value as long as it is not ``None`` (which isn't printed at all). In our
835
938 case, the kernel instantiates as ``sys.displayhook`` an object which has
836 Results can have multiple simultaneous formats depending on its
939 similar behavior, but which instead of printing to stdout, broadcasts these
837 configuration. A plain text representation should always be provided
940 values as ``execute_result`` messages for clients to display appropriately.
838 in the ``text/plain`` mime-type. Frontends are free to display any or all of these
941
839 according to its capabilities.
942 IPython's displayhook can handle multiple simultaneous formats depending on its
840 Frontends should ignore mime-types they do not understand. The data itself is
943 configuration. The default pretty-printed repr text is always given with the
944 ``data`` entry in this message. Any other formats are provided in the
945 ``extra_formats`` list. Frontends are free to display any or all of these
946 according to its capabilities. ``extra_formats`` list contains 3-tuples of an ID
947 string, a type string, and the data. The ID is unique to the formatter
948 implementation that created the data. Frontends will typically ignore the ID
949 unless if it has requested a particular formatter. The type string tells the
950 frontend how to interpret the data. It is often, but not always a MIME type.
951 Frontends should ignore types that it does not understand. The data itself is
952 any JSON object and depends on the format. It is often, but not always a string.
841 any JSON object and depends on the format. It is often, but not always a string.
953
842
954 Message type: ``execute_result``::
843 Message type: ``execute_result``::
@@ -959,16 +848,16 b' Message type: ``execute_result``::'
959 # display it, since IPython automatically creates variables called _N
848 # display it, since IPython automatically creates variables called _N
960 # (for prompt N).
849 # (for prompt N).
961 'execution_count' : int,
850 'execution_count' : int,
962
851
963 # data and metadata are identical to a display_data message.
852 # data and metadata are identical to a display_data message.
964 # the object being displayed is that passed to the display hook,
853 # the object being displayed is that passed to the display hook,
965 # i.e. the *result* of the execution.
854 # i.e. the *result* of the execution.
966 'data' : dict,
855 'data' : dict,
967 'metadata' : dict,
856 'metadata' : dict,
968 }
857 }
969
858
970 Python errors
859 Execution errors
971 -------------
860 ----------------
972
861
973 When an error occurs during code execution
862 When an error occurs during code execution
974
863
@@ -979,6 +868,10 b' Message type: ``error``::'
979 # except the 'status' field is omitted.
868 # except the 'status' field is omitted.
980 }
869 }
981
870
871 .. versionchanged:: 5.0.0
872
873 ``pyerr`` renamed to ``error``
874
982 Kernel status
875 Kernel status
983 -------------
876 -------------
984
877
@@ -1010,8 +903,8 b' Message type: ``clear_output``::'
1010
903
1011 .. versionchanged:: 4.1
904 .. versionchanged:: 4.1
1012
905
1013 'stdout', 'stderr', and 'display' boolean keys for selective clearing are removed,
906 ``stdout``, ``stderr``, and ``display`` boolean keys for selective clearing are removed,
1014 and 'wait' is added.
907 and ``wait`` is added.
1015 The selective clearing keys are ignored in v4 and the default behavior remains the same,
908 The selective clearing keys are ignored in v4 and the default behavior remains the same,
1016 so v4 clear_output messages will be safely handled by a v4.1 frontend.
909 so v4 clear_output messages will be safely handled by a v4.1 frontend.
1017
910
@@ -1029,7 +922,13 b' the ``raw_input(prompt)`` call.'
1029
922
1030 Message type: ``input_request``::
923 Message type: ``input_request``::
1031
924
1032 content = { 'prompt' : str, 'password' : bool }
925 content = {
926 # the text to show at the prompt
927 'prompt' : str,
928 # Is the request for a password?
929 # If so, the frontend shouldn't echo input.
930 'password' : bool
931 }
1033
932
1034 Message type: ``input_reply``::
933 Message type: ``input_reply``::
1035
934
@@ -1038,9 +937,9 b' Message type: ``input_reply``::'
1038
937
1039 When ``password`` is True, the frontend should not echo the input as it is entered.
938 When ``password`` is True, the frontend should not echo the input as it is entered.
1040
939
1041 .. versionchanged:: 5.0
940 .. versionchanged:: 5.0.0
1042
941
1043 ``password`` key added in msg spec 5.0.
942 ``password`` key added.
1044
943
1045 .. note::
944 .. note::
1046
945
@@ -1061,34 +960,13 b' When ``password`` is True, the frontend should not echo the input as it is enter'
1061 transported over the zmq connection), raw ``stdin`` isn't expected to be
960 transported over the zmq connection), raw ``stdin`` isn't expected to be
1062 available.
961 available.
1063
962
1064
963
1065 Heartbeat for kernels
964 Heartbeat for kernels
1066 =====================
965 =====================
1067
966
1068 Initially we had considered using messages like those above over ZMQ for a
967 Clients send ping messages on a REQ socket, which are echoed right back
1069 kernel 'heartbeat' (a way to detect quickly and reliably whether a kernel is
968 from the Kernel's REP socket. These are simple bytestrings, not full JSON messages described above.
1070 alive at all, even if it may be busy executing user code). But this has the
1071 problem that if the kernel is locked inside extension code, it wouldn't execute
1072 the python heartbeat code. But it turns out that we can implement a basic
1073 heartbeat with pure ZMQ, without using any Python messaging at all.
1074
1075 The monitor sends out a single zmq message (right now, it is a str of the
1076 monitor's lifetime in seconds), and gets the same message right back, prefixed
1077 with the zmq identity of the DEALER socket in the heartbeat process. This can be
1078 a uuid, or even a full message, but there doesn't seem to be a need for packing
1079 up a message when the sender and receiver are the exact same Python object.
1080
1081 The model is this::
1082
969
1083 monitor.send(str(self.lifetime)) # '1.2345678910'
1084
1085 and the monitor receives some number of messages of the form::
1086
1087 ['uuid-abcd-dead-beef', '1.2345678910']
1088
1089 where the first part is the zmq.IDENTITY of the heart's DEALER on the engine, and
1090 the rest is the message sent by the monitor. No Python code ever has any
1091 access to the message between the monitor's send, and the monitor's recv.
1092
970
1093 Custom Messages
971 Custom Messages
1094 ===============
972 ===============
@@ -1164,15 +1042,11 b' handlers should set the parent header and publish status busy / idle,'
1164 just like an execute request.
1042 just like an execute request.
1165
1043
1166
1044
1167 ToDo
1045 To Do
1168 ====
1046 =====
1169
1047
1170 Missing things include:
1048 Missing things include:
1171
1049
1172 * Important: finish thinking through the payload concept and API.
1050 * Important: finish thinking through the payload concept and API.
1173
1051
1174 * Important: ensure that we have a good solution for magics like %edit. It's
1175 likely that with the payload concept we can build a full solution, but not
1176 100% clear yet.
1177
1178 .. include:: ../links.txt
1052 .. include:: ../links.txt
General Comments 0
You need to be logged in to leave comments. Login now