.. _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``.