notebook_autorun 0.1.4
Auto run certain cells upon notebook start - if trusted
License: MIT
Keywords: python

notebook-autorun
================

| This is a Python package to allow auto-run of certains cells in a
  `Jupyter
  notebook <http://jupyter-notebook-beginner-guide.readthedocs.io/en/latest/what_is_jupyter.html>`__
  at kernel start.
| For security reasons it only works in `**trusted**
  notebooks <http://jupyter-notebook.readthedocs.io/en/stable/security.html#security-in-notebook-documents>`__.

1 - Install
-----------

From terminal:

.. code:: bash

    pip install notebook_autorun

2 - User Guide
--------------

In a notebook cell:

.. code:: python

    from notebook_autorun import Autorun
    # example
    cells = [2, 3]
    Autorun(cells=cells).add_js()
    # (0-indexed) cells 2, 3 will be run at notebook start 

| This will inject javascript code (in the output cell) which will react
  on the next ``kernel_ready.Kernel`` event (i.e. at notebook start or
  kernel restart) to execute the selected cells.
| This event is described in `Jupyter Javascript Events documentation
  page <http://jupyter.readthedocs.io/en/latest/development_guide/js_events.html>`__.
  While this page is outdated in some respects, it appears still valid
  about the ``kernel_ready.Kernel`` event.

To rid the notebook of the autorun features just clear the output cell.

For more complete examples, see the + `sample notebook -
trusted <http://nbviewer.jupyter.org/github/oscar6echo/notebook-autorun/blob/master/demo_autorun_trusted.ipynb>`__
+ `sample notebook -
untrusted <http://nbviewer.jupyter.org/github/oscar6echo/notebook-autorun/blob/master/demo_autorun_untrusted.ipynb>`__

Also, to get a better understanding of what's going on under the hood,
open the console and examine the log.

2.1 - How to select cells for autorun
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

| The cells to autorun can be determined by one of the 3 args below.
| Only one of them must be specified:
| + ``cells``: List of 0-indexed cells or String representing a list of
  cells. `Python list
  slices <https://docs.python.org/2.3/whatsnew/section-slices.html>`__
  are allowed. Default is ``None``. ``cells`` is stringified to
  ``str_cells`` before passing to javascript. Invalid cell numbers (e.g.
  greater than the notebook number of cells) are ignored.

::

    Examples: 
    ```Python
    # Assuming a notebook of 10 cells

    cells = [5, 7, 8]
    Autorun(cells=cells).add_js()
    # cells 5, 7, 8 will be run  

    cells = '2, 25 , 26, -1'
    Autorun(cells=cells).add_js()
    # cells 2 and 9 will be run  

    cells = '2:'
    Autorun(cells=cells).add_js()
    # all cells from 2 to 9 included will be run  

    cells = ':-3'
    Autorun(cells=cells).add_js()
    # cells 7, 8, 9 will be run  

    cells = '4:8'
    Autorun(cells=cells).add_js()
    # cells 4, 5, 6, 7 will be run  

    cells = '4:8:2'
    Autorun(cells=cells).add_js()
    # cells 4, 6 will be run  

    cells = '::-1'
    Autorun(cells=cells).add_js()
    # all cells will be run in reverse order  

    cells = '-2:-6:-2'
    Autorun(cells=cells).add_js()
    # cells 8, 7, 6, 5 will be run  
    ```

-  ``metadata``: Boolean (default is ``False``). If ``True``, all cells
   with medatada ``"autorun": true`` are concerned.

   Example:

   .. code:: python

       Autorun(metadata=True).add_js()
       # all cells with metadata "autorun: true" will be run  

-  ``comment``: Boolean (default is ``False``). If ``True``, all cells
   containing a string ``comment_flag`` in a comment line (default is
   ``AUTORUN``) are concerned.

   Example:

   .. code:: python

       Autorun(comment=True).add_js()
       # all cells including string "AUTORUN" in a comment line will be run  

       Autorun(comment=True, comment_flag='MYCUSTOMFLAG').add_js()
       # all cells including string "MYCUSTOMFLAG" in a comment line will be run  

2.2 - Focus on Cell
~~~~~~~~~~~~~~~~~~~

| If you want to focus on a specific cell after autorun, you can use arg
  ``focus``.
| By default ``focus=None``.

Examples:

.. code:: python

    Autorun(metadata=True, focus=5).add_js()
    # cell 5 will focus after autorun

    Autorun(metadata=True, focus=-2).add_js()
    # cell 6 will focus after autorun

    Autorun(metadata=True).add_js()
    # cell 0 will focus after autorun

2.3 - Status message
~~~~~~~~~~~~~~~~~~~~

| By default ``verbose=True``.
| It displays a warnnig message then status info:

.. code:: python

    Autorun(metadata=True).add_js()

    # will display the following warning:
    If you see <IPython.core.display.Javascript object> below, this notebook is not trusted.
    As a consequence Autorun cannot work.
    Run "from notebook_autorun import Autorun; Autorun.info()" for more info.

    # then status info
    This output cell contains notebook-autorun settings:
       {"str_cells": null, "metadata": true, "comment": false, "comment_flag": "# AUTORUN"}

You can remove these messages:

.. code:: python

    Autorun(metadata=True).add_js()
    # no visible output - but the js code is injected

2.4 - Security
~~~~~~~~~~~~~~

Because a notebook is designed to allow the user to write arbitrary
code, it has full access to many resources.

| The typical risks are the following: + A notebook has access to your
  file system and can therefore potentially read/modify/delete any of
  your files or send them to an attacker, or write a new file (virus).
| + A notebook may contain javascript in output cells which can read you
  cookies and local storage and potentially send them to an attacker.

See the `Security in notebook
documents <https://jupyter-notebook.readthedocs.io/en/stable/security.html#security-in-notebook-documents>`__
section of the official `Jupyter Notebook
documentation <https://jupyter-notebook.readthedocs.io/en/stable/index.html>`__
for more info.

Therefore you **should review** and **must trust** the notebook before
you can use **notebook-autorun**.

Example in the case of an untrusted notebook:

.. code:: python

    # notebook is not trusted
    Autorun(metadata=True).add_js()

    # will display the following warning:
    If you see <IPython.core.display.Javascript object> below, this notebook is not trusted.
    As a consequence Autorun cannot work.
    Run "from notebook_autorun import Autorun; Autorun.info()" for more info.

    # then the Javascript object - un-executed
    <IPython.core.display.Javascript object>

    # then the Markdown object - un-executed
    <IPython.core.display.Markdown object>

As the warning message indicates you can get this section info with:

.. code:: python

    from notebook_autorun import Autorun
    Autorun.info()

.. raw:: html

   <!-- pandoc --from=markdown --to=rst --output=README.rst README.md -->