notebook_autorun

Auto run certain cells upon notebook start - if trusted


Keywords
python, display, javascript
License
MIT
Install
pip install notebook_autorun==0.1.7

Documentation

notebook-autorun

This is a Python package to allow auto-run of certains cells in a Jupyter notebook at kernel start.
For security reasons it only works in trusted notebooks.

1 - Install

From terminal:

pip install notebook_autorun

2 - User Guide

In a notebook cell:

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

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 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:

    # 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:

    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:

    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:

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:

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:

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 section of the official Jupyter Notebook documentation 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:

# 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:

from notebook_autorun import Autorun
Autorun.info()