Nbtutor
Visualize Python code execution (line-by-line) in Jupyter Notebook cells. Inspired by Online Python Tutor.
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 <#develop>
__ below.
pip
.. code:: shell
pip install nbtutor
jupyter nbextension install --overwrite --py nbtutor
jupyter nbextension enable --py nbtutor
``conda``
.. code:: shell
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
:
.. code:: python
%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:
.. code:: python
%%nbtutor
Optional arguments
There are also optional arguments that can be used with the cell magic:
- Reset the IPython user namespace
.. code:: python
%%nbtutor -r/--reset
- Suppress the confirmation message from ``-r/--reset``
.. code:: python
%%nbtutor -r/--reset -f/--force
- Render primitive objects inline
.. code:: python
%%nbtutor -i/--inline
- Specify the maximum frame depth to visualize (default: 1)
.. code:: python
%%nbtutor -d/--depth N
- Specify the number of significant digits for floats (default: 3)
.. code:: python
%%nbtutor --digits D
- Specify the maximum number of elements to visualize for "sequence"
type objects (default: 5)
.. code:: python
%%nbtutor --max_size S
- Step through all frames (including frames from other cells and other
global scopes altogether)
.. code:: python
%%nbtutor --step_all
- Expand ``numpy`` arrays to show underlying data
.. code:: python
%%nbtutor --expand_arrays
- No inlined keys, attributes, or primitive objects
.. code:: python
%%nbtutor --nolies
Notes
-----
- Visualizing ``numpy`` arrays is somewhat experimental. Simple
``ndarray``\ s and simple slicing should work, but anything beyond
that is un-tested.
- If you find a problem please feel free to submit an
`issue <https://github.com/lgpage/nbtutor/issues>`__
Develop
-------
This assumes you have cloned this repository locally:
.. code:: shell
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 <https://www.continuum.io/downloads>`__ or
`miniconda <http://conda.pydata.org/miniconda.html>`__. You can create a
Python development environment named ``nbtutor`` from
``./environment.yml``.
.. code:: shell
conda create -n nbtutor python=YOUR_FAVORITE_PYTHON
conda env update
source activate nbtutor
We use ``npm`` for ``node.js`` dependencies, so then run:
.. code:: shell
npm install
Finally, you are ready to build the assets with:
.. code:: shell
npm run build
Installing the nbextension
To ensure that you always get the right assets (for development),
install the nbextension with the symlink
options:
.. code:: shell
python setup.py develop
jupyter nbextension install --overwrite --symlink --sys-prefix --py nbtutor
jupyter nbextension enable --sys-prefix --py nbtutor