Nbtutor

Visualize Python code execution (line-by-line) in Jupyter Notebook cells. Inspired by Online Python Tutor.

Usage

Install

Note: installing directly off this repo won't work, as we don't ship the built JavaScript and CSS assets. See more about developing below.

pip

pip install nbtutor
jupyter nbextension install --overwrite --py nbtutor
jupyter nbextension enable --py nbtutor

conda

conda install -c conda-forge nbtutor

Usage (Jupyter Notebook)

First load the nbtutor IPython kernel extension at top of the Notebook by executing the following magic in a CodeCell:

%load_ext nbtutor

Then to visualize the execute of code in a CodeCell add the following magic to the top of the CodeCell and execute it again:

%%nbtutor

Optional arguments

There are also optional arguments that can be used with the cell magic:

• Reset the IPython user namespace

  %%nbtutor -r/--reset

• Suppress the confirmation message from -r/--reset

  %%nbtutor -r/--reset -f/--force

• Render primitive objects inline

  %%nbtutor -i/--inline

• Specify the maximum frame depth to visualize (default: 1)

  %%nbtutor -d/--depth N

• Specify the number of significant digits for floats (default: 3)

  %%nbtutor --digits D

• Specify the maximum number of elements to visualize for "sequence" type objects (default: 5)

  %%nbtutor --max_size S

• Step through all frames (including frames from other cells and other global scopes altogether)

  %%nbtutor --step_all

• Expand numpy arrays to show underlying data

  %%nbtutor --expand_arrays

• No inlined keys, attributes, or primitive objects

  %%nbtutor --nolies

Notes

• Visualizing numpy arrays is somewhat experimental. Simple ndarrays and simple slicing should work, but anything beyond that is un-tested.
• If you find a problem please feel free to submit an issue

Develop

This assumes you have cloned this repository locally:

git clone https://github.com/lgpage/nbtutor.git
cd nbtutor

Repo architecture

The nbtutor nbextension is built from ./src into ./nbtutor/static/nbtutor with: - less for style - es6 (via babel) for javascript - browserify for packaging

The nbtutor ipython kernel extension (magics) is stored in the ./nbtutor/ipython folder

Build tools are stored in the ./tools folder.

Getting started

You'll need conda installed, either from Anaconda or miniconda. You can create a Python development environment named nbtutor from ./environment.yml.

conda create -n nbtutor python=YOUR_FAVORITE_PYTHON
conda env update
source activate nbtutor

We use npm for node.js dependencies, so then run:

npm install

Finally, you are ready to build the assets with:

npm run build

Installing the nbextension

To ensure that you always get the right assets (for development), install the nbextension with the symlink options:

python setup.py develop
jupyter nbextension install --overwrite --symlink --sys-prefix --py nbtutor
jupyter nbextension enable --sys-prefix --py nbtutor