.. _execution_semantics:

Execution of cells in the IPython kernel

When IPython kernel receives execute_request <https://jupyter-client.readthedocs.io/en/latest/messaging.html#execute>_ with user code, it processes the message in the following phases:

1. Fire the pre_execute event.
2. Fire the pre_run_cell event unless silent is True.
3. Execute run_cell method to preprocess code, compile and run it, see below for details.
4. If execution succeeds, expressions in user_expressions are computed. This ensures that any error in the expressions don't affect the main code execution.
5. Fire the post_execute event.
6. Fire the post_run_cell event unless silent is True.

.. seealso::

:doc:`/config/callbacks`

Running user code

First, the code cell is transformed to expand %magic and !system commands by IPython.core.inputtransformer2. Then expanded cell is compiled using standard Python :func:compile function and executed.

Python :func:compile function provides mode argument to select one of three ways of compiling code:

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 transformed code is parsed into a single abstract syntax tree, and its top-level nodes are executed one after the other. Which nodes get to display their value is controlled by the InteractiveShell.ast_node_interactivity option (default: last_expr): nodes selected for display (by default, the last node, if it is an expression) are compiled in 'single' mode so that :func:sys.displayhook is triggered, while all other nodes are compiled in 'exec' mode. This makes it easy to type simple expressions at the end of a cell to see computed values. Other accepted values for ast_node_interactivity are all, last, none and last_expr_or_assign.