Notebook Execution ================== ``run`` executes all codes cells in the notebook, from first to last, comparable to ``Kernel > Restart & Run All`` in the *Jupyter Notebook Editor*. Each cell is executed separately, in the context of the global state, which is empty at the start and updated as cells execute. Unless in quiet mode, ``run`` will report some execution statistics on ``stdout``: * number of code cells * number of executed code cells * number of executions that resulted in an error Result File Name ---------------- The result of running notebook ``nb.ipynb`` is written to ``nb-run.ipynb``, unless the option ``--inplace`` is applied. The result name addition can be adjusted in the configuration file by setting ``run_result_name``; see :doc:`configuration`. Options ------- The following options are supported by ``run``: .. code-block:: none -e, --allow-errors, -E, --no-allow-errors continue on errors (default: True) -b, --clean-before, -B, --no-clean-before clean code output before running (default: True -a, --clean-after, -A, --no-clean-after clean code metadata after running (default: True) -k KERNEL_NAME, --kernel-name KERNEL_NAME name of kernel to use, e.g. python3; for kernel specified in notebook; default: '') -p RUN_PATH, --run-path RUN_PATH working directory for execution ;"" for current working directory (default: '') -t TIMEOUT, --timeout TIMEOUT timeout time in seconds per cell; -1 for unlimited (default: -1) -i, --interrupt-on-timeout, -I, --no-interrupt-on-timeout interrupt execution on timeout (default: False) -r, --record-timing, -R, --no-record-timing record execution times (default: True) -w, --append-cell, -W, --no-append-cell append special code cell (default: '# Automatically added code cell: lists all global names defined by this notebook.\n%whos') before executing notebooks (default: False) --streams-head STREAMS_HEAD limit output streams to a maximum number of lines per cell; -1 for unlimited (default: 1000) Dry Run ^^^^^^^ By default, the result of executing notebook ``nb.ipynb`` is written to ``nb-run.ipynb``, unless the ``dry-run`` option is in effect. The ``dry-run`` option suppresses writing of the resulting notebook. It does not suppress execution. Allow Errors ^^^^^^^^^^^^ By default, ``run`` executes *all* code cells, even when errors occur. Such errors typically give rise to an ``error`` element among the cell outputs in the notebook (which the *Jupyter Notebook Editor* shows on a red background). The ``no-allow-errors`` option makes ``run`` abort execution at the first error. Error details are then reported on ``stderr``. Timeout ^^^^^^^ By default, ``run`` does not limit the execution time. The ``timeout`` option sets a limit in seconds on the execution time *per cell*. Use ``-1`` as value to remove the limit. Interrupt on Timeout ^^^^^^^^^^^^^^^^^^^^ By default, ``run`` interrupts the kernel with a ``KeyboardInterrupt`` when a timeout occurs (which does *not* stop further execution when allowing errors). When *not* interrupting on timeout, ``run`` aborts execution with a ``CellTimeoutError`` when a timeout occurs (which stops further execution even when allowing errors). Record Timing ^^^^^^^^^^^^^ By default, ``run`` records cell execution times in the resulting cell metadata under the key ``execution``. See `nbformat, Cell metadata `__ for details. Kernel Name ^^^^^^^^^^^ By default, ``run`` uses the kernel associated with the notebook (as specified in its ``metadata > kernel`` attribute). The ``kernel_name`` option overrides this default behavior and sets a specific kernel. Typical choices are * ``python2`` * ``python3`` Run Path ^^^^^^^^ By default, the notebook is executed in the current working directory where the tool was invoked. The ``run-path`` option sets a specific path to be the working directory. Clean Before ^^^^^^^^^^^^ By default, ``run`` cleans the notebook before execution: * the outputs of all code cells are removed, * their execution counts are cleared, and * ``ExecuteTime`` and ``execution`` metadata is removed. This ensures that the the notebook is run in a clean environment. In particular, when executing until the first error, no spurious outputs and metadata from a previous run will be left in the notebook. The ``not-before`` option suppresses this pre-cleaning step. Clean After ^^^^^^^^^^^ By default, ``run`` cleans the notebook after execution: * the ``collapased`` and ``scrolled`` metadata are removed from all code cells Currently, it appears that execution through ``nbconvert`` will make all output cells collapsed and scrolled. When such a notebook is subsequently opened in the *Jupyter Notebook Editor*, no outputs will be visible, until they are actively opened by the user (either by clicking to the left of the output area of a cell, or through the ``Cell`` menu to *toggle* the output cell state. The ``not-after`` option suppresses this post-cleaning step. Append Cell ^^^^^^^^^^^ The ``append-cell`` option appends to the notebook (before execution) a code cell containing: .. code-block:: python # Automatically added code cell: lists all global names defined by this notebook. %whos This will show an overview of all names defined a the global level of the notebook, their types, and some data/info. Also see the example below. The content of the appended code cell can be changed in a configuration file. Using the ``cat`` tool, you can prepend and append entire notebooks. Streams Head ^^^^^^^^^^^^ The ``streams-head`` option will limit the amount of data in output streams (both `stdout` and `stderr`) that is written to the resulting notebook, by showing only the *head*. The number of lines to show is a parameter to this option (use -1 for unlimited output). It applies per cell. This option serves as a protection to generate excessively large notebooks, when the input notebook contains 'overzealous' code. An example of 'overzealous' code is an infinite loop that contains a call to `print`. JSON Output ----------- See :ref:`output-json` for general information about JSON output. ``run`` produces the following members in the JSON output: +-------------------+----------------------------------------------------+ | Name | Value | +===================+====================================================+ | ``"code cells"`` | count of code cells | +-------------------+----------------------------------------------------+ | ``"executed"`` | count of executed code cells | +-------------------+----------------------------------------------------+ | ``"with errors"`` | count of executed code cells with errors | +-------------------+----------------------------------------------------+ Note that members are absent when count is zero. Examples -------- Example output when running a single notebook without options: .. code-block:: bash $ nbtb run test.ipynb Execution statistics: 12 code cells 12 executed 2 with errors The execution result is written to ``test-run.ipynb``. Example output when running to first error in verbose mode without writing the result: .. code-block:: bash $ nbtb run -E tool-faq.ipynb test.ipynb -v -n Dry run (no files written) Options for nbrun: Cleaning code output and ['ExecuteTime', 'execution'] metadata before running Timeout: unlimited Kernel name: from notebook Working dir: current directory Stopping at first error Cell execution does not time out Recording execution times Not appending code cell with %whos Cleaning ['collapsed', 'scrolled'] code metadata after running Not limiting output streams :::::::::::::: short.ipynb :::::::::::::: Execution statistics: 1 code cells 0 code cells with empty source 1 executed 0 with errors No file written :::::::::::::: test.ipynb :::::::::::::: Notebooks processed: 1 Processing of "test.ipynb" failed (CellExecutionError): An error occurred while executing the following cell: ------------------ # NameError undefined ------------------ NameError: name 'undefined' is not defined Tool 'run' aborted. Here is an example with the ``append-cell`` (``-w``) option. The execution result is written to ``test-run.ipynb``. Next, we use ``nbshow`` to inspect the output of the last cell (Note that ``nbshow`` is part of the ``nbdime`` package; see `documentation `__ of ``nbdime``.) .. code-block:: bash $ nbtb run -w test.ipynb Execution statistics: 13 code cells 0 code cells with empty source 13 executed 2 with errors $ nbshow test-run.ipynb | tail -n -16 code cell 19: execution_count: 13 source: # Automatically added code cell: lists all global names defined by this notebook. %whos outputs: output 0: output_type: stream name: stdout text: Variable Type Data/Info --------------------------------- df DataFrame 0\n0 3\n1 1\n2 4\n3 1\n4 5\n5 9 i int 99 pd module ages/pandas/__init__.py'> sys module