Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 1044 lines (764 sloc) 38.282 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043
.. _messaging:

======================
 Messaging in IPython
======================


Introduction
============

This document explains the basic communications design and messaging
specification for how the various IPython objects interact over a network
transport. The current implementation uses the ZeroMQ_ library for messaging
within and between hosts.

.. Note::

   This document should be considered the authoritative description of the
   IPython messaging protocol, and all developers are strongly encouraged to
   keep it updated as the implementation evolves, so that we have a single
   common reference for all protocol details.
   
The basic design is explained in the following diagram:

.. image:: figs/frontend-kernel.png
   :width: 450px
   :alt: IPython kernel/frontend messaging architecture.
   :align: center
   :target: ../_images/frontend-kernel.png

A single kernel can be simultaneously connected to one or more frontends. The
kernel has three sockets that serve the following functions:

1. stdin: this ROUTER socket is connected to all frontends, and it allows
   the kernel to request input from the active frontend when :func:`raw_input` is called.
   The frontend that executed the code has a DEALER socket that acts as a 'virtual keyboard'
   for the kernel while this communication is happening (illustrated in the
   figure by the black outline around the central keyboard). In practice,
   frontends may display such kernel requests using a special input widget or
   otherwise indicating that the user is to type input for the kernel instead
   of normal commands in the frontend.

2. Shell: this single ROUTER socket allows multiple incoming connections from
   frontends, and this is the socket where requests for code execution, object
   information, prompts, etc. are made to the kernel by any frontend. The
   communication on this socket is a sequence of request/reply actions from
   each frontend and the kernel.

3. IOPub: this socket is the 'broadcast channel' where the kernel publishes all
   side effects (stdout, stderr, etc.) as well as the requests coming from any
   client over the shell socket and its own requests on the stdin socket. There
   are a number of actions in Python which generate side effects: :func:`print`
   writes to ``sys.stdout``, errors generate tracebacks, etc. Additionally, in
   a multi-client scenario, we want all frontends to be able to know what each
   other has sent to the kernel (this can be useful in collaborative scenarios,
   for example). This socket allows both side effects and the information
   about communications taking place with one client over the shell channel
   to be made available to all clients in a uniform manner.

   All messages are tagged with enough information (details below) for clients
   to know which messages come from their own interaction with the kernel and
   which ones are from other clients, so they can display each type
   appropriately.

The actual format of the messages allowed on each of these channels is
specified below. Messages are dicts of dicts with string keys and values that
are reasonably representable in JSON. Our current implementation uses JSON
explicitly as its message format, but this shouldn't be considered a permanent
feature. As we've discovered that JSON has non-trivial performance issues due
to excessive copying, we may in the future move to a pure pickle-based raw
message format. However, it should be possible to easily convert from the raw
objects to JSON, since we may have non-python clients (e.g. a web frontend).
As long as it's easy to make a JSON version of the objects that is a faithful
representation of all the data, we can communicate with such clients.

.. Note::

   Not all of these have yet been fully fleshed out, but the key ones are, see
   kernel and frontend files for actual implementation details.

General Message Format
======================

A message is defined by the following four-dictionary structure::

    {
      # The message header contains a pair of unique identifiers for the
      # originating session and the actual message id, in addition to the
      # username for the process that generated the message. This is useful in
      # collaborative settings where multiple users may be interacting with the
      # same kernel simultaneously, so that frontends can label the various
      # messages in a meaningful way.
      'header' : {
                    'msg_id' : uuid,
                    'username' : str,
                    'session' : uuid
                    # All recognized message type strings are listed below.
                    'msg_type' : str,
         },

      # In a chain of messages, the header from the parent is copied so that
      # clients can track where messages come from.
      'parent_header' : dict,

      # The actual content of the message must be a dict, whose structure
      # depends on the message type.
      'content' : dict,
      
      # Any metadata associated with the message.
      'metadata' : dict,
    }

   
Python functional API
=====================

As messages are dicts, they map naturally to a ``func(**kw)`` call form. We
should develop, at a few key points, functional forms of all the requests that
take arguments in this manner and automatically construct the necessary dict
for sending.

In addition, the Python implementation of the message specification extends
messages upon deserialization to the following form for convenience::

    {
      'header' : dict,
      # The msg's unique identifier and type are always stored in the header,
      # but the Python implementation copies them to the top level.
      'msg_id' : uuid,
      'msg_type' : str,
      'parent_header' : dict,
      'content' : dict,
      'metadata' : dict,
    }

All messages sent to or received by any IPython process should have this
extended structure.


Messages on the shell ROUTER/DEALER sockets
===========================================

.. _execute:

Execute
-------

This message type is used by frontends to ask the kernel to execute code on
behalf of the user, in a namespace reserved to the user's variables (and thus
separate from the kernel's own internal code and variables).

Message type: ``execute_request``::

    content = {
        # Source code to be executed by the kernel, one or more lines.
    'code' : str,

    # A boolean flag which, if True, signals the kernel to execute
    # this code as quietly as possible. This means that the kernel
    # will compile the code with 'exec' instead of 'single' (so
    # sys.displayhook will not fire), forces store_history to be False,
    # and will *not*:
    # - broadcast exceptions on the PUB socket
    # - do any logging
    #
    # The default is False.
    'silent' : bool,

    # A boolean flag which, if True, signals the kernel to populate history
    # The default is True if silent is False. If silent is True, store_history
    # is forced to be False.
    'store_history' : bool,

    # A list of variable names from the user's namespace to be retrieved. What
    # returns is a JSON string of the variable's repr(), not a python object.
    'user_variables' : list,

    # Similarly, a dict mapping names to expressions to be evaluated in the
    # user's dict.
    'user_expressions' : dict,

    # Some frontends (e.g. the Notebook) do not support stdin requests. If
    # raw_input is called from code executed from such a frontend, a
    # StdinNotImplementedError will be raised.
    'allow_stdin' : True,

    }

The ``code`` field contains a single string (possibly multiline). The kernel
is responsible for splitting this into one or more independent execution blocks
and deciding whether to compile these in 'single' or 'exec' mode (see below for
detailed execution semantics).

The ``user_`` fields deserve a detailed explanation. In the past, IPython had
the notion of a prompt string that allowed arbitrary code to be evaluated, and
this was put to good use by many in creating prompts that displayed system
status, path information, and even more esoteric uses like remote instrument
status aqcuired over the network. But now that IPython has a clean separation
between the kernel and the clients, the kernel has no prompt knowledge; prompts
are a frontend-side feature, and it should be even possible for different
frontends to display different prompts while interacting with the same kernel.

The kernel now provides the ability to retrieve data from the user's namespace
after the execution of the main ``code``, thanks to two fields in the
``execute_request`` message:

- ``user_variables``: If only variables from the user's namespace are needed, a
  list of variable names can be passed and a dict with these names as keys and
  their :func:`repr()` as values will be returned.

- ``user_expressions``: For more complex expressions that require function
  evaluations, a dict can be provided with string keys and arbitrary python
  expressions as values. The return message will contain also a dict with the
  same keys and the :func:`repr()` of the evaluated expressions as value.

With this information, frontends can display any status information they wish
in the form that best suits each frontend (a status line, a popup, inline for a
terminal, etc).

.. Note::

   In order to obtain the current execution counter for the purposes of
   displaying input prompts, frontends simply make an execution request with an
   empty code string and ``silent=True``.

Execution semantics
~~~~~~~~~~~~~~~~~~~

When the silent flag is false, the execution of use code consists of the
following phases (in silent mode, only the ``code`` field is executed):

1. Run the ``pre_runcode_hook``.

2. Execute the ``code`` field, see below for details.

3. If #2 succeeds, compute ``user_variables`` and ``user_expressions`` are
   computed. This ensures that any error in the latter don't harm the main
   code execution.

4. Call any method registered with :meth:`register_post_execute`.

.. warning::

   The API for running code before/after the main code block is likely to
   change soon. Both the ``pre_runcode_hook`` and the
   :meth:`register_post_execute` are susceptible to modification, as we find a
   consistent model for both.

To understand how the ``code`` field is executed, one must know that Python
code can be compiled in one of three modes (controlled by the ``mode`` argument
to the :func:`compile` builtin):

*single*
  Valid for a single interactive statement (though the source can contain
  multiple lines, such as a for loop). When compiled in this mode, the
  generated bytecode contains special instructions that trigger the calling of
  :func:`sys.displayhook` for any expression in the block that returns a value.
  This means that a single statement can actually produce multiple calls to
  :func:`sys.displayhook`, if for example it contains a loop where each
  iteration computes an unassigned expression would generate 10 calls::

      for i in range(10):
          i**2

*exec*
  An arbitrary amount of source code, this is how modules are compiled.
  :func:`sys.displayhook` is *never* implicitly called.

*eval*
  A single expression that returns a value. :func:`sys.displayhook` is *never*
  implicitly called.


The ``code`` field is split into individual blocks each of which is valid for
execution in 'single' mode, and then:

- If there is only a single block: it is executed in 'single' mode.

- If there is more than one block:

  * if the last one is a single line long, run all but the last in 'exec' mode
    and the very last one in 'single' mode. This makes it easy to type simple
    expressions at the end to see computed values.

  * if the last one is no more than two lines long, run all but the last in
    'exec' mode and the very last one in 'single' mode. This makes it easy to
    type simple expressions at the end to see computed values. - otherwise
    (last one is also multiline), run all in 'exec' mode

  * otherwise (last one is also multiline), run all in 'exec' mode as a single
    unit.

Any error in retrieving the ``user_variables`` or evaluating the
``user_expressions`` will result in a simple error message in the return fields
of the form::

   [ERROR] ExceptionType: Exception message

The user can simply send the same variable name or expression for evaluation to
see a regular traceback.

Errors in any registered post_execute functions are also reported similarly,
and the failing function is removed from the post_execution set so that it does
not continue triggering failures.

Upon completion of the execution request, the kernel *always* sends a reply,
with a status code indicating what happened and additional data depending on
the outcome. See :ref:`below <execution_results>` for the possible return
codes and associated data.


Execution counter (old prompt number)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The kernel has a single, monotonically increasing counter of all execution
requests that are made with ``store_history=True``. This counter is used to populate
the ``In[n]``, ``Out[n]`` and ``_n`` variables, so clients will likely want to
display it in some form to the user, which will typically (but not necessarily)
be done in the prompts. The value of this counter will be returned as the
``execution_count`` field of all ``execute_reply`` messages.

.. _execution_results:

Execution results
~~~~~~~~~~~~~~~~~
    
Message type: ``execute_reply``::

    content = {
      # One of: 'ok' OR 'error' OR 'abort'
      'status' : str,

      # The global kernel counter that increases by one with each request that
      # stores history. This will typically be used by clients to display
      # prompt numbers to the user. If the request did not store history, this will
      # be the current value of the counter in the kernel.
      'execution_count' : int,
    }

When status is 'ok', the following extra fields are present::

    {
      # 'payload' will be a list of payload dicts.
      # Each execution payload is a dict with string keys that may have been
      # produced by the code being executed. It is retrieved by the kernel at
      # the end of the execution and sent back to the front end, which can take
      # action on it as needed. See main text for further details.
      'payload' : list(dict),

      # Results for the user_variables and user_expressions.
      'user_variables' : dict,
      'user_expressions' : dict,
    }

.. admonition:: Execution payloads
    
   The notion of an 'execution payload' is different from a return value of a
   given set of code, which normally is just displayed on the pyout stream
   through the PUB socket. The idea of a payload is to allow special types of
   code, typically magics, to populate a data container in the IPython kernel
   that will be shipped back to the caller via this channel. The kernel
   has an API for this in the PayloadManager::

       ip.payload_manager.write_payload(payload_dict)

   which appends a dictionary to the list of payloads.

   
When status is 'error', the following extra fields are present::

    {
      'ename' : str, # Exception name, as a string
      'evalue' : str, # Exception value, as a string

      # The traceback will contain a list of frames, represented each as a
      # string. For now we'll stick to the existing design of ultraTB, which
      # controls exception level of detail statefully. But eventually we'll
      # want to grow into a model where more information is collected and
      # packed into the traceback object, with clients deciding how little or
      # how much of it to unpack. But for now, let's start with a simple list
      # of strings, since that requires only minimal changes to ultratb as
      # written.
      'traceback' : list,
    }


When status is 'abort', there are for now no additional data fields. This
happens when the kernel was interrupted by a signal.

Kernel attribute access
-----------------------

.. warning::

   This part of the messaging spec is not actually implemented in the kernel
   yet.
 
While this protocol does not specify full RPC access to arbitrary methods of
the kernel object, the kernel does allow read (and in some cases write) access
to certain attributes.

The policy for which attributes can be read is: any attribute of the kernel, or
its sub-objects, that belongs to a :class:`Configurable` object and has been
declared at the class-level with Traits validation, is in principle accessible
as long as its name does not begin with a leading underscore. The attribute
itself will have metadata indicating whether it allows remote read and/or write
access. The message spec follows for attribute read and write requests.

Message type: ``getattr_request``::

    content = {
        # The (possibly dotted) name of the attribute
'name' : str,
    }

When a ``getattr_request`` fails, there are two possible error types:

- AttributeError: this type of error was raised when trying to access the
  given name by the kernel itself. This means that the attribute likely
  doesn't exist.

- AccessError: the attribute exists but its value is not readable remotely.


Message type: ``getattr_reply``::

    content = {
        # One of ['ok', 'AttributeError', 'AccessError'].
        'status' : str,
# If status is 'ok', a JSON object.
'value' : object,
    }

Message type: ``setattr_request``::

    content = {
        # The (possibly dotted) name of the attribute
'name' : str,

# A JSON-encoded object, that will be validated by the Traits
# information in the kernel
'value' : object,
    }

When a ``setattr_request`` fails, there are also two possible error types with
similar meanings as those of the ``getattr_request`` case, but for writing.
    
Message type: ``setattr_reply``::

    content = {
        # One of ['ok', 'AttributeError', 'AccessError'].
        'status' : str,
    }


    
Object information
------------------

One of IPython's most used capabilities is the introspection of Python objects
in the user's namespace, typically invoked via the ``?`` and ``??`` characters
(which in reality are shorthands for the ``%pinfo`` magic). This is used often
enough that it warrants an explicit message type, especially because frontends
may want to get object information in response to user keystrokes (like Tab or
F1) besides from the user explicitly typing code like ``x??``.

Message type: ``object_info_request``::

    content = {
        # The (possibly dotted) name of the object to be searched in all
# relevant namespaces
        'name' : str,

     # The level of detail desired. The default (0) is equivalent to typing
# 'x?' at the prompt, 1 is equivalent to 'x??'.
'detail_level' : int,
    }

The returned information will be a dictionary with keys very similar to the
field names that IPython prints at the terminal.
    
Message type: ``object_info_reply``::

    content = {
    # The name the object was requested under
    'name' : str,
    
    # Boolean flag indicating whether the named object was found or not. If
    # it's false, all other fields will be empty.
    'found' : bool,
    
    # Flags for magics and system aliases
    'ismagic' : bool,
    'isalias' : bool,

    # The name of the namespace where the object was found ('builtin',
    # 'magics', 'alias', 'interactive', etc.)
    'namespace' : str,

    # The type name will be type.__name__ for normal Python objects, but it
    # can also be a string like 'Magic function' or 'System alias'
    'type_name' : str,

    # The string form of the object, possibly truncated for length if
    # detail_level is 0
    'string_form' : str,

    # For objects with a __class__ attribute this will be set
    'base_class' : str,

    # For objects with a __len__ attribute this will be set
    'length' : int,

    # If the object is a function, class or method whose file we can find,
    # we give its full path
    'file' : str,

    # For pure Python callable objects, we can reconstruct the object
    # definition line which provides its call signature. For convenience this
    # is returned as a single 'definition' field, but below the raw parts that
    # compose it are also returned as the argspec field.
    'definition' : str,

    # The individual parts that together form the definition string. Clients
    # with rich display capabilities may use this to provide a richer and more
    # precise representation of the definition line (e.g. by highlighting
    # arguments based on the user's cursor position). For non-callable
    # objects, this field is empty.
    'argspec' : { # The names of all the arguments
                  args : list,
# The name of the varargs (*args), if any
                  varargs : str,
# The name of the varkw (**kw), if any
varkw : str,
# The values (as strings) of all default arguments. Note
# that these must be matched *in reverse* with the 'args'
# list above, since the first positional args have no default
# value at all.
defaults : list,
},

    # For instances, provide the constructor signature (the definition of
    # the __init__ method):
    'init_definition' : str,
    
    # Docstrings: for any object (function, method, module, package) with a
    # docstring, we show it. But in addition, we may provide additional
    # docstrings. For example, for instances we will show the constructor
    # and class docstrings as well, if available.
    'docstring' : str,

    # For instances, provide the constructor and class docstrings
    'init_docstring' : str,
    'class_docstring' : str,
    
    # If it's a callable object whose call method has a separate docstring and
    # definition line:
    'call_def' : str,
    'call_docstring' : str,
    
    # If detail_level was 1, we also try to find the source code that
    # defines the object, if possible. The string 'None' will indicate
    # that no source was found.
    'source' : str,
    }

    
Complete
--------

Message type: ``complete_request``::

    content = {
        # The text to be completed, such as 'a.is'
    'text' : str,

    # The full line, such as 'print a.is'. This allows completers to
    # make decisions that may require information about more than just the
    # current word.
    'line' : str,

    # The entire block of text where the line is. This may be useful in the
    # case of multiline completions where more context may be needed. Note: if
    # in practice this field proves unnecessary, remove it to lighten the
    # messages.
    
    'block' : str,

    # The position of the cursor where the user hit 'TAB' on the line.
    'cursor_pos' : int,
    }

Message type: ``complete_reply``::

    content = {
        # The list of all matches to the completion request, such as
    # ['a.isalnum', 'a.isalpha'] for the above example.
    'matches' : list
    }

    
History
-------

For clients to explicitly request history from a kernel. The kernel has all
the actual execution history stored in a single location, so clients can
request it from the kernel when needed.

Message type: ``history_request``::

    content = {
    
      # If True, also return output history in the resulting dict.
      'output' : bool,

      # If True, return the raw input history, else the transformed input.
      'raw' : bool,

      # So far, this can be 'range', 'tail' or 'search'.
      'hist_access_type' : str,
      
      # If hist_access_type is 'range', get a range of input cells. session can
      # be a positive session number, or a negative number to count back from
      # the current session.
      'session' : int,
      # start and stop are line numbers within that session.
      'start' : int,
      'stop' : int,
      
      # If hist_access_type is 'tail' or 'search', get the last n cells.
      'n' : int,
      
      # If hist_access_type is 'search', get cells matching the specified glob
      # pattern (with * and ? as wildcards).
      'pattern' : str,
      
    }

Message type: ``history_reply``::

    content = {
      # A list of 3 tuples, either:
      # (session, line_number, input) or
      # (session, line_number, (input, output)),
      # depending on whether output was False or True, respectively.
      'history' : list,
    }


Connect
-------

When a client connects to the request/reply socket of the kernel, it can issue
a connect request to get basic information about the kernel, such as the ports
the other ZeroMQ sockets are listening on. This allows clients to only have
to know about a single port (the shell channel) to connect to a kernel.

Message type: ``connect_request``::

    content = {
    }

Message type: ``connect_reply``::

    content = {
        'shell_port' : int # The port the shell ROUTER socket is listening on.
        'iopub_port' : int # The port the PUB socket is listening on.
        'stdin_port' : int # The port the stdin ROUTER socket is listening on.
        'hb_port' : int # The port the heartbeat socket is listening on.
    }


Kernel info
-----------

If a client needs to know what protocol the kernel supports, it can
ask version number of the messaging protocol supported by the kernel.
This message can be used to fetch other core information of the
kernel, including language (e.g., Python), language version number and
IPython version number.

Message type: ``kernel_info_request``::

    content = {
    }

Message type: ``kernel_info_reply``::

    content = {
        # Version of messaging protocol (mandatory).
        # The first integer indicates major version. It is incremented when
        # there is any backward incompatible change.
        # The second integer indicates minor version. It is incremented when
        # there is any backward compatible change.
        'protocol_version': [int, int],

        # IPython version number (optional).
        # Non-python kernel backend may not have this version number.
        # The last component is an extra field, which may be 'dev' or
        # 'rc1' in development version. It is an empty string for
        # released version.
        'ipython_version': [int, int, int, str],

        # Language version number (mandatory).
        # It is Python version number (e.g., [2, 7, 3]) for the kernel
        # included in IPython.
        'language_version': [int, ...],

        # Programming language in which kernel is implemented (mandatory).
        # Kernel included in IPython returns 'python'.
        'language': str,
    }


Kernel shutdown
---------------

The clients can request the kernel to shut itself down; this is used in
multiple cases:

- when the user chooses to close the client application via a menu or window
  control.
- when the user types 'exit' or 'quit' (or their uppercase magic equivalents).
- when the user chooses a GUI method (like the 'Ctrl-C' shortcut in the
  IPythonQt client) to force a kernel restart to get a clean kernel without
  losing client-side state like history or inlined figures.

The client sends a shutdown request to the kernel, and once it receives the
reply message (which is otherwise empty), it can assume that the kernel has
completed shutdown safely.

Upon their own shutdown, client applications will typically execute a last
minute sanity check and forcefully terminate any kernel that is still alive, to
avoid leaving stray processes in the user's machine.

For both shutdown request and reply, there is no actual content that needs to
be sent, so the content dict is empty.

Message type: ``shutdown_request``::

    content = {
        'restart' : bool # whether the shutdown is final, or precedes a restart
    }

Message type: ``shutdown_reply``::

    content = {
        'restart' : bool # whether the shutdown is final, or precedes a restart
    }

.. Note::

   When the clients detect a dead kernel thanks to inactivity on the heartbeat
   socket, they simply send a forceful process termination signal, since a dead
   process is unlikely to respond in any useful way to messages.
    

Messages on the PUB/SUB socket
==============================

Streams (stdout, stderr, etc)
------------------------------

Message type: ``stream``::

    content = {
        # The name of the stream is one of 'stdin', 'stdout', 'stderr'
        'name' : str,
    
        # The data is an arbitrary string to be written to that stream
        'data' : str,
    }

When a kernel receives a raw_input call, it should also broadcast it on the pub
socket with the names 'stdin' and 'stdin_reply'. This will allow other clients
to monitor/display kernel interactions and possibly replay them to their user
or otherwise expose them.

Display Data
------------

This type of message is used to bring back data that should be diplayed (text,
html, svg, etc.) in the frontends. This data is published to all frontends.
Each message can have multiple representations of the data; it is up to the
frontend to decide which to use and how. A single message should contain all
possible representations of the same information. Each representation should
be a JSON'able data structure, and should be a valid MIME type.

Some questions remain about this design:

* Do we use this message type for pyout/displayhook? Probably not, because
  the displayhook also has to handle the Out prompt display. On the other hand
  we could put that information into the metadata secion.

Message type: ``display_data``::

    content = {

        # Who create the data
        'source' : str,

        # The data dict contains key/value pairs, where the kids are MIME
        # types and the values are the raw data of the representation in that
        # format. The data dict must minimally contain the ``text/plain``
        # MIME type which is used as a backup representation.
        'data' : dict,

        # Any metadata that describes the data
        'metadata' : dict
    }


Raw Data Publication
--------------------

``display_data`` lets you publish *representations* of data, such as images and html.
This ``data_pub`` message lets you publish *actual raw data*, sent via message buffers.

data_pub messages are constructed via the :func:`IPython.lib.datapub.publish_data` function:

.. sourcecode:: python

    from IPython.zmq.datapub import publish_data
    ns = dict(x=my_array)
    publish_data(ns)


Message type: ``data_pub``::

    content = {
        # the keys of the data dict, after it has been unserialized
        keys = ['a', 'b']
    }
    # the namespace dict will be serialized in the message buffers,
    # which will have a length of at least one
    buffers = ['pdict', ...]


The interpretation of a sequence of data_pub messages for a given parent request should be
to update a single namespace with subsequent results.

.. note::

    No frontends directly handle data_pub messages at this time.
    It is currently only used by the client/engines in :mod:`IPython.parallel`,
    where engines may publish *data* to the Client,
    of which the Client can then publish *representations* via ``display_data``
    to various frontends.

Python inputs
-------------

These messages are the re-broadcast of the ``execute_request``.

Message type: ``pyin``::

    content = {
        'code' : str, # Source code to be executed, one or more lines

        # The counter for this execution is also provided so that clients can
        # display it, since IPython automatically creates variables called _iN
        # (for input prompt In[N]).
        'execution_count' : int
    }

Python outputs
--------------

When Python produces output from code that has been compiled in with the
'single' flag to :func:`compile`, any expression that produces a value (such as
``1+1``) is passed to ``sys.displayhook``, which is a callable that can do with
this value whatever it wants. The default behavior of ``sys.displayhook`` in
the Python interactive prompt is to print to ``sys.stdout`` the :func:`repr` of
the value as long as it is not ``None`` (which isn't printed at all). In our
case, the kernel instantiates as ``sys.displayhook`` an object which has
similar behavior, but which instead of printing to stdout, broadcasts these
values as ``pyout`` messages for clients to display appropriately.

IPython's displayhook can handle multiple simultaneous formats depending on its
configuration. The default pretty-printed repr text is always given with the
``data`` entry in this message. Any other formats are provided in the
``extra_formats`` list. Frontends are free to display any or all of these
according to its capabilities. ``extra_formats`` list contains 3-tuples of an ID
string, a type string, and the data. The ID is unique to the formatter
implementation that created the data. Frontends will typically ignore the ID
unless if it has requested a particular formatter. The type string tells the
frontend how to interpret the data. It is often, but not always a MIME type.
Frontends should ignore types that it does not understand. The data itself is
any JSON object and depends on the format. It is often, but not always a string.

Message type: ``pyout``::

    content = {

        # The counter for this execution is also provided so that clients can
        # display it, since IPython automatically creates variables called _N
        # (for prompt N).
        'execution_count' : int,
        
        # The data dict contains key/value pairs, where the kids are MIME
        # types and the values are the raw data of the representation in that
        # format. The data dict must minimally contain the ``text/plain``
        # MIME type which is used as a backup representation.
        'data' : dict,

    }
    
Python errors
-------------

When an error occurs during code execution

Message type: ``pyerr``::

    content = {
       # Similar content to the execute_reply messages for the 'error' case,
       # except the 'status' field is omitted.
    }

Kernel status
-------------

This message type is used by frontends to monitor the status of the kernel.

Message type: ``status``::

    content = {
        # When the kernel starts to execute code, it will enter the 'busy'
        # state and when it finishes, it will enter the 'idle' state.
        execution_state : ('busy', 'idle')
    }

Kernel crashes
--------------

When the kernel has an unexpected exception, caught by the last-resort
sys.excepthook, we should broadcast the crash handler's output before exiting.
This will allow clients to notice that a kernel died, inform the user and
propose further actions.

Message type: ``crash``::

    content = {
       # Similarly to the 'error' case for execute_reply messages, this will
       # contain ename, etype and traceback fields.

       # An additional field with supplementary information such as where to
       # send the crash message
       'info' : str,
    }


Future ideas
------------
    
Other potential message types, currently unimplemented, listed below as ideas.
    
Message type: ``file``::

    content = {
    'path' : 'cool.jpg',
    'mimetype' : str,
    'data' : str,
    }


Messages on the stdin ROUTER/DEALER sockets
===========================================

This is a socket where the request/reply pattern goes in the opposite direction:
from the kernel to a *single* frontend, and its purpose is to allow
``raw_input`` and similar operations that read from ``sys.stdin`` on the kernel
to be fulfilled by the client. The request should be made to the frontend that
made the execution request that prompted ``raw_input`` to be called. For now we
will keep these messages as simple as possible, since they only mean to convey
the ``raw_input(prompt)`` call.

Message type: ``input_request``::

    content = { 'prompt' : str }

Message type: ``input_reply``::

    content = { 'value' : str }
    
.. Note::

   We do not explicitly try to forward the raw ``sys.stdin`` object, because in
   practice the kernel should behave like an interactive program. When a
   program is opened on the console, the keyboard effectively takes over the
   ``stdin`` file descriptor, and it can't be used for raw reading anymore.
   Since the IPython kernel effectively behaves like a console program (albeit
   one whose "keyboard" is actually living in a separate process and
   transported over the zmq connection), raw ``stdin`` isn't expected to be
   available.

   
Heartbeat for kernels
=====================

Initially we had considered using messages like those above over ZMQ for a
kernel 'heartbeat' (a way to detect quickly and reliably whether a kernel is
alive at all, even if it may be busy executing user code). But this has the
problem that if the kernel is locked inside extension code, it wouldn't execute
the python heartbeat code. But it turns out that we can implement a basic
heartbeat with pure ZMQ, without using any Python messaging at all.

The monitor sends out a single zmq message (right now, it is a str of the
monitor's lifetime in seconds), and gets the same message right back, prefixed
with the zmq identity of the DEALER socket in the heartbeat process. This can be
a uuid, or even a full message, but there doesn't seem to be a need for packing
up a message when the sender and receiver are the exact same Python object.

The model is this::

    monitor.send(str(self.lifetime)) # '1.2345678910'

and the monitor receives some number of messages of the form::

    ['uuid-abcd-dead-beef', '1.2345678910']

where the first part is the zmq.IDENTITY of the heart's DEALER on the engine, and
the rest is the message sent by the monitor. No Python code ever has any
access to the message between the monitor's send, and the monitor's recv.


ToDo
====

Missing things include:

* Important: finish thinking through the payload concept and API.

* Important: ensure that we have a good solution for magics like %edit. It's
  likely that with the payload concept we can build a full solution, but not
  100% clear yet.

* Finishing the details of the heartbeat protocol.

* Signal handling: specify what kind of information kernel should broadcast (or
  not) when it receives signals.

.. include:: ../links.rst
Something went wrong with that request. Please try again.