Jupyter Notebook Tips

Pay Notebook Creator: Roy Hyunjin Han0
Set Container: Numerical CPU with TINY Memory for 10 Minutes 0

Test Notebooks

Once you have created a lot of notebooks, you will want to make sure they still work as expected.

Test Notebooks by Running Them

If you don't want to install additional packages, you can use the nbconvert package that is installed by default when you install Jupyter Notebook.

The following command will run the notebook x.ipynb and save the executed notebook in /tmp/x.ipynb as though you had run each cell one by one.

jupyter nbconvert --to notebook --execute \
    --output /tmp/x.ipynb \

You can also use this command to convert a notebook into a module. The following command will extract the code from x.ipynb and save it in /tmp/x.py.

jupyter nbconvert --to python \
    --output /tmp/x.py \

Test Notebooks Automatically

The nbval package is a py.test extension that treats each notebook cell as a test.

If a cell raises an exception or if its new output does not match its old output, then the cell fails.

pip install nbval
py.test --nbval

The nblint package checks syntax errors and warnings for each cell of the notebook.

pip install nblint
nblint x.ipynb
nblint --linter pyflakes x.ipynb

Compare Notebooks

The nbdime package provides scripts for highlighting and merging changes between different versions of the same notebook.

pip install nbdime
nbdiff old.ipynb new.ipynb
nbdiff-web old.ipynb new.ipynb
nbmerge-web older.ipynb old.ipynb new.ipynb

Alternatively, you can use the ipymd package to create notebooks in markdown format, which is easier to diff.

pip install ipymd
jupyter notebook --generate-config
echo c.NotebookApp.contents_manager_class = \
    'ipymd.IPymdContentsManager' \
    >> ~/.jupyter/jupyter_notebook_config.py

After installing the package, opening a file with the extension md will open the notebook editor instead of the text editor. The notebook will save in markdown format instead of the standard JSON.

>>> x = 1
>>> y = 2
>>> x + y

Define Tests Inside Notebooks

The ipython-unittest package adds magic commands that make it easier to define tests directly inside a notebook using the standard unittest framework. You can use this to create exercises where students have to define a function or class that passes certain tests.

pip install ipython-unittest
In [ ]:
%load_ext ipython_unittest
In [ ]:

class ATest(unittest.TestCase):
    def test_a(self):
        self.assertEqual('a' + 'b', 'ab')

    def test_b(self):
        self.assertEqual(1 + 2, 3)

Define Tests using Notebooks

The pytest-ipynb package lets you write tests in notebook format. This means that instead of writing test_module.py, you can write test_module.ipynb. Each cell of the notebook counts as a separate test.

pip install pytest-ipynb