##// 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 20 :maxdepth: 1
21 21
22 22 messaging
23 execution
23 24 parallel_messages
24 25 parallel_connections
25 26 lexer
@@ -9,7 +9,7 b' Versioning'
9 9 ==========
10 10
11 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 15 Introduction
@@ -38,22 +38,13 b' The basic design is explained in the following diagram:'
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 1. stdin: this ROUTER socket is connected to all frontends, and it allows
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
41 1. Shell: this single ROUTER socket allows multiple incoming connections from
51 42 frontends, and this is the socket where requests for code execution, object
52 43 information, prompts, etc. are made to the kernel by any frontend. The
53 44 communication on this socket is a sequence of request/reply actions from
54 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 48 side effects (stdout, stderr, etc.) as well as the requests coming from any
58 49 client over the shell socket and its own requests on the stdin socket. There
59 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 55 about communications taking place with one client over the shell channel
65 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 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 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 75 The actual format of the messages allowed on each of these channels is
73 76 specified below. Messages are dicts of dicts with string keys and values that
74 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 122 'content' : dict,
120 123 }
121 124
125 .. versionchanged:: 5.0.0
126
127 ``version`` key added to the header.
128
122 129 The Wire Protocol
123 130 =================
124 131
@@ -250,13 +257,11 b' Message type: ``execute_request``::'
250 257 'code' : str,
251 258
252 259 # A boolean flag which, if True, signals the kernel to execute
253 # this code as quietly as possible. This means that the kernel
254 # will compile the code with 'exec' instead of 'single' (so
255 # sys.displayhook will not fire), forces store_history to be False,
260 # this code as quietly as possible.
261 # silent=True forces store_history to be False,
256 262 # and will *not*:
257 # - broadcast exceptions on the PUB socket
258 # - do any logging
259 #
263 # - broadcast output on the IOPUB channel
264 # - have an execute_result
260 265 # The default is False.
261 266 'silent' : bool,
262 267
@@ -265,7 +270,7 b' Message type: ``execute_request``::'
265 270 # is forced to be False.
266 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 274 # user's dict. The rich display-data representation of each will be evaluated after execution.
270 275 # See the display_data content for the structure of the representation data.
271 276 'user_expressions' : dict,
@@ -276,12 +281,13 b' Message type: ``execute_request``::'
276 281 'allow_stdin' : True,
277 282 }
278 283
279 The ``code`` field contains a single string (possibly multiline). The kernel
280 is responsible for splitting this into one or more independent execution blocks
281 and deciding whether to compile these in 'single' or 'exec' mode (see below for
282 detailed execution semantics).
284 .. versionchanged:: 5.0.0
283 285
284 The ``user_expressions`` fields deserve a detailed explanation. In the past, IPython had
286 ``user_variables`` removed, because it is redundant with user_expressions.
287
288 The ``code`` field contains a single string (possibly multiline) to be executed.
289
290 The ``user_expressions`` field deserves a detailed explanation. In the past, IPython had
285 291 the notion of a prompt string that allowed arbitrary code to be evaluated, and
286 292 this was put to good use by many in creating prompts that displayed system
287 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 295 between the kernel and the clients, the kernel has no prompt knowledge; prompts
290 296 are a frontend feature, and it should be even possible for different
291 297 frontends to display different prompts while interacting with the same kernel.
292
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.
298 ``user_expressions`` can be used to retrieve this information.
377 299
378 300 Any error in evaluating any expression in ``user_expressions`` will result in
379 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 307 'traceback' : ...
386 308 }
387 309
388 Errors in any registered post_execute functions are also reported,
389 and the failing function is removed from the post_execution set so that it does
390 not continue triggering failures.
310 .. Note::
311
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 316 Upon completion of the execution request, the kernel *always* sends a reply,
393 317 with a status code indicating what happened and additional data depending on
394 318 the outcome. See :ref:`below <execution_results>` for the possible return
395 319 codes and associated data.
396 320
321 .. seealso::
322
323 :ref:`execution_semantics`
397 324
398 325 .. _execution_counter:
399 326
400 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 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
406 display it in some form to the user, which will typically (but not necessarily)
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.
332 the ``In[n]`` and ``Out[n]`` prompts. The value of this counter will be returned as the
333 ``execution_count`` field of all ``execute_reply`` and ``execute_input`` messages.
409 334
410 335 .. _execution_results:
411 336
@@ -441,6 +366,10 b" When status is 'ok', the following extra fields are present::"
441 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 373 .. admonition:: Execution payloads
445 374
446 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 410 happens when the kernel was interrupted by a signal.
482 411
483 412
484 Object information
485 ------------------
413 Introspection
414 -------------
486 415
487 One of IPython's most used capabilities is the introspection of Python objects
488 in the user's namespace, typically invoked via the ``?`` and ``??`` characters
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??``.
416 Code can be inspected to show useful information to the user.
417 It is up to the Kernel to decide what information should be displayed, and its formatting.
493 418
494 Message type: ``object_info_request``::
419 Message type: ``inspect_request``::
495 420
496 421 content = {
497 # The (possibly dotted) name of the object to be searched in all
498 # relevant namespaces
499 'oname' : str,
422 # The code context in which introspection is requested
423 # this may be up to an entire multiline cell.
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 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
507 field names that IPython prints at the terminal.
436 .. versionchanged:: 5.0.0
508 437
509 Message type: ``object_info_reply``::
438 ``object_info_request`` renamed to ``inspect_request``.
510 439
511 content = {
512 # The name the object was requested under
513 'name' : str,
514
515 # Boolean flag indicating whether the named object was found or not. If
516 # it's false, all other fields will be empty.
517 'found' : bool,
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 },
440 .. versionchanged:: 5.0.0
568 441
569 # For instances, provide the constructor signature (the definition of
570 # the __init__ method):
571 'init_definition' : str,
442 ``name`` key replaced with ``code`` and ``cursor_pos``,
443 moving the lexing responsibility to the kernel.
572 444
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,
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.
578 448
579 # For instances, provide the constructor and class docstrings
580 'init_docstring' : str,
581 'class_docstring' : str,
449 Message type: ``inspect_reply``::
582 450
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,
451 content = {
452 # 'ok' if the request succeeded or 'error', with error information as in all other replies.
453 'status' : 'ok',
587 454
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,
455 # data can be empty if nothing is found
456 'data' : dict,
457 'metadata' : dict,
592 458 }
593 459
460 .. versionchanged:: 5.0.0
594 461
595 Complete
596 --------
462 ``object_info_reply`` renamed to ``inspect_reply``.
597 463
598 Message type: ``complete_request``::
464 .. versionchanged:: 5.0.0
599 465
600 content = {
601 # The text to be completed, such as 'a.is'
602 # this may be an empty string if the frontend does not do any lexing,
603 # in which case the kernel must figure out the completion
604 # based on 'line' and 'cursor_pos'.
605 'text' : str,
466 Reply is changed from structured data to a mime bundle, allowing formatting decisions to be made by the kernel.
606 467
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,
468 Completion
469 ----------
611 470
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.
471 Message type: ``complete_request``::
616 472
617 'block' : str or null/None,
473 content = {
474 # The code context in which completion is requested
475 # this may be up to an entire multiline cell, such as
476 # 'foo = a.isal'
477 'code' : str,
618 478
619 # The position of the cursor where the user hit 'TAB' on the line.
479 # The cursor position within 'code' (in unicode characters) where completion is requested
620 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 489 Message type: ``complete_reply``::
624 490
625 491 content = {
@@ -627,11 +493,13 b' Message type: ``complete_reply``::'
627 493 # ['a.isalnum', 'a.isalpha'] for the above example.
628 494 'matches' : list,
629 495
630 # the substring of the matched text
631 # this is typically the common prefix of the matches,
632 # and the text that is already in the block that would be replaced by the full completion.
633 # This would be 'a.is' in the above example.
634 'matched_text' : str,
496 # The range of text that should be replaced by the above matches when a completion is accepted.
497 # typically cursor_end is the same as cursor_pos in the request.
498 'cursor_start' : int,
499 'cursor_end' : int,
500
501 # Information that frontend plugins might use for extra display information about completions.
502 'metadata' : dict,
635 503
636 504 # status should be 'ok' unless an exception was raised during the request,
637 505 # in which case it should be 'error', along with the usual error message content
@@ -639,6 +507,11 b' Message type: ``complete_reply``::'
639 507 'status' : 'ok'
640 508 }
641 509
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
642 515
643 516 History
644 517 -------
@@ -735,32 +608,47 b' Message type: ``kernel_info_request``::'
735 608 Message type: ``kernel_info_reply``::
736 609
737 610 content = {
738 # Version of messaging protocol (mandatory).
611 # Version of messaging protocol.
739 612 # The first integer indicates major version. It is incremented when
740 613 # there is any backward incompatible change.
741 614 # The second integer indicates minor version. It is incremented when
742 615 # there is any backward compatible change.
743 616 'protocol_version': 'X.Y.Z',
744 617
745 # IPython version number (optional).
746 # Non-python kernel backend may not have this version number.
747 # could be '2.0.0-dev' for development version
748 'ipython_version': 'X.Y.Z',
618 # The kernel implementation name
619 # (e.g. 'ipython' for the IPython kernel)
620 'implementation': str,
749 621
750 # Language version number (mandatory).
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',
626
627 # Programming language in which kernel is implemented.
628 # Kernel included in IPython returns 'python'.
629 'language': str,
630
631 # Language version number.
751 632 # It is Python version number (e.g., '2.7.3') for the kernel
752 633 # included in IPython.
753 634 'language_version': 'X.Y.Z',
754 635
755 # Programming language in which kernel is implemented (mandatory).
756 # Kernel included in IPython returns 'python'.
757 'language': str,
636 # A banner of information about the kernel,
637 # which may be desplayed in console environments.
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,
763 not version strings.
649 .. versionchanged:: 5.0.0
650
651 ``implementation``, ``implementation_version``, and ``banner`` keys are added.
764 652
765 653
766 654 Kernel shutdown
@@ -833,7 +721,9 b' Some questions remain about this design:'
833 721
834 722 * Do we use this message type for execute_result/displayhook? Probably not, because
835 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 728 Message type: ``display_data``::
839 729
@@ -862,7 +752,7 b' with a reasonably unique name to avoid conflicts.'
862 752 The only metadata keys currently defined in IPython are the width and height
863 753 of images::
864 754
865 'metadata' : {
755 metadata = {
866 756 'image/png' : {
867 757 'width': 640,
868 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 769 Raw Data Publication
874 770 --------------------
875 771
@@ -889,11 +785,11 b' Message type: ``data_pub``::'
889 785
890 786 content = {
891 787 # the keys of the data dict, after it has been unserialized
892 keys = ['a', 'b']
788 'keys' : ['a', 'b']
893 789 }
894 790 # the namespace dict will be serialized in the message buffers,
895 791 # which will have a length of at least one
896 buffers = ['pdict', ...]
792 buffers = [b'pdict', ...]
897 793
898 794
899 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 803 of which the Client can then publish *representations* via ``display_data``
908 804 to various frontends.
909 805
910 Python inputs
911 -------------
806 Code inputs
807 -----------
912 808
913 809 To let all frontends know what code is being executed at any given time, these
914 810 messages contain a re-broadcast of the ``code`` portion of an
915 811 :ref:`execute_request <execute>`, along with the :ref:`execution_count
916 812 <execution_counter>`.
917 813
918 Message type: ``pyin``::
814 Message type: ``execute_input``::
919 815
920 816 content = {
921 817 'code' : str, # Source code to be executed, one or more lines
@@ -926,29 +822,22 b' Message type: ``pyin``::'
926 822 'execution_count' : int
927 823 }
928 824
929 Python outputs
930 --------------
825 .. versionchanged:: 5.0.0
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
933 'single' flag to :func:`compile`, any expression that produces a value (such as
934 ``1+1``) is passed to ``sys.displayhook``, which is a callable that can do with
935 this value whatever it wants. The default behavior of ``sys.displayhook`` in
936 the Python interactive prompt is to print to ``sys.stdout`` the :func:`repr` of
937 the value as long as it is not ``None`` (which isn't printed at all). In our
938 case, the kernel instantiates as ``sys.displayhook`` an object which has
939 similar behavior, but which instead of printing to stdout, broadcasts these
940 values as ``execute_result`` messages for clients to display appropriately.
941
942 IPython's displayhook can handle multiple simultaneous formats depending on its
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
830 Execution results
831 -----------------
832
833 Results of an execution are published as an ``execute_result``.
834 These are identical to `display_data`_ messages, with the addition of an ``execution_count`` key.
835
836 Results can have multiple simultaneous formats depending on its
837 configuration. A plain text representation should always be provided
838 in the ``text/plain`` mime-type. Frontends are free to display any or all of these
839 according to its capabilities.
840 Frontends should ignore mime-types they do not understand. The data itself is
952 841 any JSON object and depends on the format. It is often, but not always a string.
953 842
954 843 Message type: ``execute_result``::
@@ -967,8 +856,8 b' Message type: ``execute_result``::'
967 856 'metadata' : dict,
968 857 }
969 858
970 Python errors
971 -------------
859 Execution errors
860 ----------------
972 861
973 862 When an error occurs during code execution
974 863
@@ -979,6 +868,10 b' Message type: ``error``::'
979 868 # except the 'status' field is omitted.
980 869 }
981 870
871 .. versionchanged:: 5.0.0
872
873 ``pyerr`` renamed to ``error``
874
982 875 Kernel status
983 876 -------------
984 877
@@ -1010,8 +903,8 b' Message type: ``clear_output``::'
1010 903
1011 904 .. versionchanged:: 4.1
1012 905
1013 'stdout', 'stderr', and 'display' boolean keys for selective clearing are removed,
1014 and 'wait' is added.
906 ``stdout``, ``stderr``, and ``display`` boolean keys for selective clearing are removed,
907 and ``wait`` is added.
1015 908 The selective clearing keys are ignored in v4 and the default behavior remains the same,
1016 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 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 933 Message type: ``input_reply``::
1035 934
@@ -1038,9 +937,9 b' Message type: ``input_reply``::'
1038 937
1039 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 944 .. note::
1046 945
@@ -1065,30 +964,9 b' When ``password`` is True, the frontend should not echo the input as it is enter'
1065 964 Heartbeat for kernels
1066 965 =====================
1067 966
1068 Initially we had considered using messages like those above over ZMQ for a
1069 kernel 'heartbeat' (a way to detect quickly and reliably whether a kernel is
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
1083 monitor.send(str(self.lifetime)) # '1.2345678910'
967 Clients send ping messages on a REQ socket, which are echoed right back
968 from the Kernel's REP socket. These are simple bytestrings, not full JSON messages described above.
1084 969
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 971 Custom Messages
1094 972 ===============
@@ -1165,14 +1043,10 b' just like an execute request.'
1165 1043
1166 1044
1167 1045 ToDo
1168 ====
1046 =====
1169 1047
1170 1048 Missing things include:
1171 1049
1172 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 1052 .. include:: ../links.txt
General Comments 0
You need to be logged in to leave comments. Login now