##// END OF EJS Templates
Expand docs on how cells are executed
anatoly techtonik -
Show More
@@ -1,65 +1,72 b''
1 .. _execution_semantics:
1 .. _execution_semantics:
2
2
3 Execution semantics in the IPython kernel
3 Execution of cells in the IPython kernel
4 =========================================
4 ========================================
5
5
6 The execution of user code consists of the following phases:
6 When IPython kernel receives `execute_request <https://jupyter-client.readthedocs.io/en/latest/messaging.html#execute>`_
7 with user code, it processes the message in the following phases:
7
8
8 1. Fire the ``pre_execute`` event.
9 1. Fire the ``pre_execute`` event.
9 2. Fire the ``pre_run_cell`` event unless silent is ``True``.
10 2. Fire the ``pre_run_cell`` event unless silent is ``True``.
10 3. Execute the ``code`` field, see below for details.
11 3. Execute ``run_cell`` method to preprocess ``code``, compile and run it, see below for details.
11 4. If execution succeeds, expressions in ``user_expressions`` are computed.
12 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 This ensures that any error in the expressions don't affect the main code execution.
13 5. Fire the ``post_execute`` event.
14 5. Fire the ``post_execute`` event.
14 6. Fire the ``post_run_cell`` event unless silent is ``True``.
15 6. Fire the ``post_run_cell`` event unless silent is ``True``.
15
16
16 .. seealso::
17 .. seealso::
17
18
18 :doc:`/config/callbacks`
19 :doc:`/config/callbacks`
19
20
20
21
21 To understand how the ``code`` field is executed, one must know that Python
22 Running user ``code``
22 code can be compiled in one of three modes (controlled by the ``mode`` argument
23 =====================
23 to the :func:`compile` builtin):
24
25 First, the ``code`` cell is transformed to expand ``%magic`` and ``!system``
26 by ``IPython.core.inputtransformer2``. Then is being compiled using standard
27 Python :func:`compile` function and executed.
28
29 Not specific to IPython, all Python code can be compiled in one of three modes
30 (see ``mode`` argument to the standard :func:`compile` function):
24
31
25 *single*
32 *single*
26 Valid for a single interactive statement (though the source can contain
33 Valid for a single interactive statement (though the source can contain
27 multiple lines, such as a for loop). When compiled in this mode, the
34 multiple lines, such as a for loop). When compiled in this mode, the
28 generated bytecode contains special instructions that trigger the calling of
35 generated bytecode contains special instructions that trigger the calling of
29 :func:`sys.displayhook` for any expression in the block that returns a value.
36 :func:`sys.displayhook` for any expression in the block that returns a value.
30 This means that a single statement can actually produce multiple calls to
37 This means that a single statement can actually produce multiple calls to
31 :func:`sys.displayhook`, if for example it contains a loop where each
38 :func:`sys.displayhook`, if for example it contains a loop where each
32 iteration computes an unassigned expression would generate 10 calls::
39 iteration computes an unassigned expression would generate 10 calls::
33
40
34 for i in range(10):
41 for i in range(10):
35 i**2
42 i**2
36
43
37 *exec*
44 *exec*
38 An arbitrary amount of source code, this is how modules are compiled.
45 An arbitrary amount of source code, this is how modules are compiled.
39 :func:`sys.displayhook` is *never* implicitly called.
46 :func:`sys.displayhook` is *never* implicitly called.
40
47
41 *eval*
48 *eval*
42 A single expression that returns a value. :func:`sys.displayhook` is *never*
49 A single expression that returns a value. :func:`sys.displayhook` is *never*
43 implicitly called.
50 implicitly called.
44
51
45
52
46 The ``code`` field is split into individual blocks each of which is valid for
53 The ``code`` field is split into individual blocks each of which is valid for
47 execution in 'single' mode, and then:
54 execution in 'single' mode, and then:
48
55
49 - If there is only a single block: it is executed in 'single' mode.
56 - If there is only a single block: it is executed in 'single' mode.
50
57
51 - If there is more than one block:
58 - If there is more than one block:
52
59
53 * if the last one is a single line long, run all but the last in 'exec' mode
60 * if the last block is a single line long, run all but the last in 'exec' mode
54 and the very last one in 'single' mode. This makes it easy to type simple
61 and the very last one in 'single' mode. This makes it easy to type simple
55 expressions at the end to see computed values.
62 expressions at the end to see computed values.
56
63
57 * if the last one is no more than two lines long, run all but the last in
64 * if the last block is no more than two lines long, run all but the last in
58 'exec' mode and the very last one in 'single' mode. This makes it easy to
65 'exec' mode and the very last one in 'single' mode. This makes it easy to
59 type simple expressions at the end to see computed values. - otherwise
66 type simple expressions at the end to see computed values. - otherwise
60 (last one is also multiline), run all in 'exec' mode
67 (last one is also multiline), run all in 'exec' mode
61
68
62 * otherwise (last one is also multiline), run all in 'exec' mode as a single
69 * otherwise (last block is also multiline), run all in 'exec' mode as a single
63 unit.
70 unit.
64
71
65
72
General Comments 0
You need to be logged in to leave comments. Login now