Show More
@@ -103,6 +103,8 b' A message is defined by the following four-dictionary structure::' | |||||
103 | 'session' : uuid, |
|
103 | 'session' : uuid, | |
104 | # All recognized message type strings are listed below. |
|
104 | # All recognized message type strings are listed below. | |
105 | 'msg_type' : str, |
|
105 | 'msg_type' : str, | |
|
106 | # the message protocol version | |||
|
107 | 'version' : '5.0.0', | |||
106 | }, |
|
108 | }, | |
107 |
|
109 | |||
108 | # In a chain of messages, the header from the parent is copied so that |
|
110 | # In a chain of messages, the header from the parent is copied so that | |
@@ -151,14 +153,14 b' The front of the message is the ZeroMQ routing prefix,' | |||||
151 | which can be zero or more socket identities. |
|
153 | which can be zero or more socket identities. | |
152 | This is every piece of the message prior to the delimiter key ``<IDS|MSG>``. |
|
154 | This is every piece of the message prior to the delimiter key ``<IDS|MSG>``. | |
153 | In the case of IOPub, there should be just one prefix component, |
|
155 | In the case of IOPub, there should be just one prefix component, | |
154 |
which is the topic for IOPub subscribers, e.g. `` |
|
156 | which is the topic for IOPub subscribers, e.g. ``execute_result``, ``display_data``. | |
155 |
|
157 | |||
156 | .. note:: |
|
158 | .. note:: | |
157 |
|
159 | |||
158 | In most cases, the IOPub topics are irrelevant and completely ignored, |
|
160 | In most cases, the IOPub topics are irrelevant and completely ignored, | |
159 | because frontends just subscribe to all topics. |
|
161 | because frontends just subscribe to all topics. | |
160 | The convention used in the IPython kernel is to use the msg_type as the topic, |
|
162 | The convention used in the IPython kernel is to use the msg_type as the topic, | |
161 |
and possibly extra information about the message, e.g. `` |
|
163 | and possibly extra information about the message, e.g. ``execute_result`` or ``stream.stdout`` | |
162 |
|
164 | |||
163 | After the delimiter is the `HMAC`_ signature of the message, used for authentication. |
|
165 | After the delimiter is the `HMAC`_ signature of the message, used for authentication. | |
164 | If authentication is disabled, this should be an empty string. |
|
166 | If authentication is disabled, this should be an empty string. | |
@@ -263,20 +265,15 b' Message type: ``execute_request``::' | |||||
263 | # is forced to be False. |
|
265 | # is forced to be False. | |
264 | 'store_history' : bool, |
|
266 | 'store_history' : bool, | |
265 |
|
267 | |||
266 | # A list of variable names from the user's namespace to be retrieved. |
|
|||
267 | # What returns is a rich representation of each variable (dict keyed by name). |
|
|||
268 | # See the display_data content for the structure of the representation data. |
|
|||
269 | 'user_variables' : list, |
|
|||
270 |
|
||||
271 | # Similarly, a dict mapping names to expressions to be evaluated in the |
|
268 | # Similarly, a dict mapping names to expressions to be evaluated in the | |
272 | # user's dict. |
|
269 | # 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. | |||
273 | 'user_expressions' : dict, |
|
271 | 'user_expressions' : dict, | |
274 |
|
272 | |||
275 |
# Some frontends |
|
273 | # Some frontends do not support stdin requests. | |
276 |
# raw_input is called from code executed from such a frontend, |
|
274 | # If raw_input is called from code executed from such a frontend, | |
277 | # StdinNotImplementedError will be raised. |
|
275 | # a StdinNotImplementedError will be raised. | |
278 | 'allow_stdin' : True, |
|
276 | 'allow_stdin' : True, | |
279 |
|
||||
280 | } |
|
277 | } | |
281 |
|
278 | |||
282 | The ``code`` field contains a single string (possibly multiline). The kernel |
|
279 | The ``code`` field contains a single string (possibly multiline). The kernel | |
@@ -284,27 +281,23 b' is responsible for splitting this into one or more independent execution blocks' | |||||
284 | and deciding whether to compile these in 'single' or 'exec' mode (see below for |
|
281 | and deciding whether to compile these in 'single' or 'exec' mode (see below for | |
285 | detailed execution semantics). |
|
282 | detailed execution semantics). | |
286 |
|
283 | |||
287 | The ``user_`` fields deserve a detailed explanation. In the past, IPython had |
|
284 | The ``user_expressions`` fields deserve a detailed explanation. In the past, IPython had | |
288 | the notion of a prompt string that allowed arbitrary code to be evaluated, and |
|
285 | the notion of a prompt string that allowed arbitrary code to be evaluated, and | |
289 | this was put to good use by many in creating prompts that displayed system |
|
286 | this was put to good use by many in creating prompts that displayed system | |
290 | status, path information, and even more esoteric uses like remote instrument |
|
287 | status, path information, and even more esoteric uses like remote instrument | |
291 | status acquired over the network. But now that IPython has a clean separation |
|
288 | status acquired over the network. But now that IPython has a clean separation | |
292 | between the kernel and the clients, the kernel has no prompt knowledge; prompts |
|
289 | between the kernel and the clients, the kernel has no prompt knowledge; prompts | |
293 |
are a frontend |
|
290 | are a frontend feature, and it should be even possible for different | |
294 | frontends to display different prompts while interacting with the same kernel. |
|
291 | frontends to display different prompts while interacting with the same kernel. | |
295 |
|
292 | |||
296 |
The kernel |
|
293 | The kernel provides the ability to retrieve data from the user's namespace | |
297 | after the execution of the main ``code``, thanks to two fields in the |
|
294 | after the execution of the main ``code``, thanks to two fields in the | |
298 | ``execute_request`` message: |
|
295 | ``execute_request`` message: | |
299 |
|
296 | |||
300 | - ``user_variables``: If only variables from the user's namespace are needed, a |
|
|||
301 | list of variable names can be passed and a dict with these names as keys and |
|
|||
302 | their :func:`repr()` as values will be returned. |
|
|||
303 |
|
||||
304 | - ``user_expressions``: For more complex expressions that require function |
|
297 | - ``user_expressions``: For more complex expressions that require function | |
305 | evaluations, a dict can be provided with string keys and arbitrary python |
|
298 | evaluations, a dict can be provided with string keys and arbitrary python | |
306 | expressions as values. The return message will contain also a dict with the |
|
299 | expressions as values. The return message will contain also a dict with the | |
307 |
same keys and the |
|
300 | same keys and the rich representations of the evaluated expressions as value. | |
308 |
|
301 | |||
309 | With this information, frontends can display any status information they wish |
|
302 | With this information, frontends can display any status information they wish | |
310 | in the form that best suits each frontend (a status line, a popup, inline for a |
|
303 | in the form that best suits each frontend (a status line, a popup, inline for a | |
@@ -326,9 +319,8 b' following phases (in silent mode, only the ``code`` field is executed):' | |||||
326 |
|
319 | |||
327 | 2. Execute the ``code`` field, see below for details. |
|
320 | 2. Execute the ``code`` field, see below for details. | |
328 |
|
321 | |||
329 |
3. If #2 succeeds, |
|
322 | 3. If #2 succeeds, expressions in ``user_expressions`` are computed. | |
330 |
|
|
323 | This ensures that any error in the expressions don't affect the main code execution. | |
331 | code execution. |
|
|||
332 |
|
324 | |||
333 | 4. Call any method registered with :meth:`register_post_execute`. |
|
325 | 4. Call any method registered with :meth:`register_post_execute`. | |
334 |
|
326 | |||
@@ -383,16 +375,17 b" execution in 'single' mode, and then:" | |||||
383 | * otherwise (last one is also multiline), run all in 'exec' mode as a single |
|
375 | * otherwise (last one is also multiline), run all in 'exec' mode as a single | |
384 | unit. |
|
376 | unit. | |
385 |
|
377 | |||
386 | Any error in retrieving the ``user_variables`` or evaluating the |
|
378 | Any error in evaluating any expression in ``user_expressions`` will result in | |
387 | ``user_expressions`` will result in a simple error message in the return fields |
|
379 | only that key containing a standard error message, of the form:: | |
388 | of the form:: |
|
|||
389 |
|
||||
390 | [ERROR] ExceptionType: Exception message |
|
|||
391 |
|
|
380 | ||
392 | The user can simply send the same variable name or expression for evaluation to |
|
381 | { | |
393 | see a regular traceback. |
|
382 | 'status' : 'error', | |
|
383 | 'ename' : 'NameError', | |||
|
384 | 'evalue' : 'foo', | |||
|
385 | 'traceback' : ... | |||
|
386 | } | |||
394 |
|
|
387 | ||
395 |
Errors in any registered post_execute functions are also reported |
|
388 | Errors in any registered post_execute functions are also reported, | |
396 | and the failing function is removed from the post_execution set so that it does |
|
389 | and the failing function is removed from the post_execution set so that it does | |
397 | not continue triggering failures. |
|
390 | not continue triggering failures. | |
398 |
|
391 | |||
@@ -404,8 +397,8 b' codes and associated data.' | |||||
404 |
|
397 | |||
405 | .. _execution_counter: |
|
398 | .. _execution_counter: | |
406 |
|
399 | |||
407 |
Execution counter ( |
|
400 | Execution counter (prompt number) | |
408 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
401 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
409 |
|
402 | |||
410 | The kernel has a single, monotonically increasing counter of all execution |
|
403 | The kernel has a single, monotonically increasing counter of all execution | |
411 | requests that are made with ``store_history=True``. This counter is used to populate |
|
404 | requests that are made with ``store_history=True``. This counter is used to populate | |
@@ -444,15 +437,14 b" When status is 'ok', the following extra fields are present::" | |||||
444 | # which is a string classifying the payload (e.g. 'pager'). |
|
437 | # which is a string classifying the payload (e.g. 'pager'). | |
445 | 'payload' : list(dict), |
|
438 | 'payload' : list(dict), | |
446 |
|
439 | |||
447 |
# Results for the user_ |
|
440 | # Results for the user_expressions. | |
448 | 'user_variables' : dict, |
|
|||
449 | 'user_expressions' : dict, |
|
441 | 'user_expressions' : dict, | |
450 | } |
|
442 | } | |
451 |
|
443 | |||
452 | .. admonition:: Execution payloads |
|
444 | .. admonition:: Execution payloads | |
453 |
|
445 | |||
454 | The notion of an 'execution payload' is different from a return value of a |
|
446 | The notion of an 'execution payload' is different from a return value of a | |
455 |
given set of code, which normally is just displayed on the |
|
447 | given set of code, which normally is just displayed on the execute_result stream | |
456 | through the PUB socket. The idea of a payload is to allow special types of |
|
448 | through the PUB socket. The idea of a payload is to allow special types of | |
457 | code, typically magics, to populate a data container in the IPython kernel |
|
449 | code, typically magics, to populate a data container in the IPython kernel | |
458 | that will be shipped back to the caller via this channel. The kernel |
|
450 | that will be shipped back to the caller via this channel. The kernel | |
@@ -748,25 +740,28 b' Message type: ``kernel_info_reply``::' | |||||
748 | # there is any backward incompatible change. |
|
740 | # there is any backward incompatible change. | |
749 | # The second integer indicates minor version. It is incremented when |
|
741 | # The second integer indicates minor version. It is incremented when | |
750 | # there is any backward compatible change. |
|
742 | # there is any backward compatible change. | |
751 |
'protocol_version': |
|
743 | 'protocol_version': 'X.Y.Z', | |
752 |
|
744 | |||
753 | # IPython version number (optional). |
|
745 | # IPython version number (optional). | |
754 | # Non-python kernel backend may not have this version number. |
|
746 | # Non-python kernel backend may not have this version number. | |
755 | # The last component is an extra field, which may be 'dev' or |
|
747 | # could be '2.0.0-dev' for development version | |
756 | # 'rc1' in development version. It is an empty string for |
|
748 | 'ipython_version': 'X.Y.Z', | |
757 | # released version. |
|
|||
758 | 'ipython_version': [int, int, int, str], |
|
|||
759 |
|
749 | |||
760 | # Language version number (mandatory). |
|
750 | # Language version number (mandatory). | |
761 |
# It is Python version number (e.g., |
|
751 | # It is Python version number (e.g., '2.7.3') for the kernel | |
762 | # included in IPython. |
|
752 | # included in IPython. | |
763 |
'language_version': |
|
753 | 'language_version': 'X.Y.Z', | |
764 |
|
754 | |||
765 | # Programming language in which kernel is implemented (mandatory). |
|
755 | # Programming language in which kernel is implemented (mandatory). | |
766 | # Kernel included in IPython returns 'python'. |
|
756 | # Kernel included in IPython returns 'python'. | |
767 | 'language': str, |
|
757 | 'language': str, | |
768 | } |
|
758 | } | |
769 |
|
759 | |||
|
760 | .. versionchanged:: 5.0 | |||
|
761 | ||||
|
762 | In protocol version 4.0, versions were given as lists of numbers, | |||
|
763 | not version strings. | |||
|
764 | ||||
770 |
|
765 | |||
771 | Kernel shutdown |
|
766 | Kernel shutdown | |
772 | --------------- |
|
767 | --------------- | |
@@ -834,6 +829,12 b' frontend to decide which to use and how. A single message should contain all' | |||||
834 | possible representations of the same information. Each representation should |
|
829 | possible representations of the same information. Each representation should | |
835 | be a JSON'able data structure, and should be a valid MIME type. |
|
830 | be a JSON'able data structure, and should be a valid MIME type. | |
836 |
|
831 | |||
|
832 | Some questions remain about this design: | |||
|
833 | ||||
|
834 | * 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 | |||
|
836 | we could put that information into the metadata secion. | |||
|
837 | ||||
837 | Message type: ``display_data``:: |
|
838 | Message type: ``display_data``:: | |
838 |
|
839 | |||
839 | content = { |
|
840 | content = { | |
@@ -936,7 +937,7 b' the Python interactive prompt is to print to ``sys.stdout`` the :func:`repr` of' | |||||
936 | the value as long as it is not ``None`` (which isn't printed at all). In our |
|
937 | the value as long as it is not ``None`` (which isn't printed at all). In our | |
937 | case, the kernel instantiates as ``sys.displayhook`` an object which has |
|
938 | case, the kernel instantiates as ``sys.displayhook`` an object which has | |
938 | similar behavior, but which instead of printing to stdout, broadcasts these |
|
939 | similar behavior, but which instead of printing to stdout, broadcasts these | |
939 |
values as `` |
|
940 | values as ``execute_result`` messages for clients to display appropriately. | |
940 |
|
941 | |||
941 | IPython's displayhook can handle multiple simultaneous formats depending on its |
|
942 | IPython's displayhook can handle multiple simultaneous formats depending on its | |
942 | configuration. The default pretty-printed repr text is always given with the |
|
943 | configuration. The default pretty-printed repr text is always given with the | |
@@ -950,7 +951,7 b' frontend how to interpret the data. It is often, but not always a MIME type.' | |||||
950 | Frontends should ignore types that it does not understand. The data itself is |
|
951 | Frontends should ignore types that it does not understand. The data itself is | |
951 | any JSON object and depends on the format. It is often, but not always a string. |
|
952 | any JSON object and depends on the format. It is often, but not always a string. | |
952 |
|
953 | |||
953 |
Message type: `` |
|
954 | Message type: ``execute_result``:: | |
954 |
|
955 | |||
955 | content = { |
|
956 | content = { | |
956 |
|
957 | |||
@@ -971,7 +972,7 b' Python errors' | |||||
971 |
|
972 | |||
972 | When an error occurs during code execution |
|
973 | When an error occurs during code execution | |
973 |
|
974 | |||
974 |
Message type: `` |
|
975 | Message type: ``error``:: | |
975 |
|
976 | |||
976 | content = { |
|
977 | content = { | |
977 | # Similar content to the execute_reply messages for the 'error' case, |
|
978 | # Similar content to the execute_reply messages for the 'error' case, |
General Comments 0
You need to be logged in to leave comments.
Login now