Visualize Python code execution (line-by-line) in Jupyter Notebook cells.
JavaScript Python CSS
Latest commit 07798a0 Dec 23, 2016 @lgpage committed on GitHub Merge pull request #28 from lgpage/1.0.x
1.0.x

README.rst

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