13 Command Line Tools

Not extensions as such, several command line tools are also available that may support notebook related publishing and quality workflows.

13.1 flake8-nb

The flake8-nb command line utility allows you to run flake8 (and its installed extensions) over one or more notebooks.

One useful feature is the ability to ignore specifically tagged code cells.

13.2 nbdime

The nbdime package provides a notebook differencer service that you can use find differences between two versions of the same notebook at a cell level, including cell outputs.

Calling nbdime from the command line with paths to two notebooks will launch a simple web service and render a simple web page showing differences between any notebook cells in a web browser.

If notebooks are checked into a local git repository, the nbdime notebook extension allows you to compare the current version of the notebook with the previous version.

13.3 nbQA

The nbQA package allows you to run a range of linters and formatters including flake8, black, isort and pyupgrade over one or more notebooks.

The nbqa-inject-flake8-report command line utility can take nbqa flake8 reports and inject them as code cell outputs into the appropriate code cells in checked notebooks. By default, code cells with injected flake8 reports are annotated with a generic flake8-error tag as well as a flake8-error-CODE tag for each distinct flake8 error code reported for that cell

13.4 nb_quality_profile

The nb_quality_profile package provides a range of utilities for generating quality reports over one or more notebooks, including word counts, single line of code counts, reading and code complexity measures, reading time estimates, over one or more notebooks.

The package can also generate simple visualisation showing the relative length and markdown vs. code cell distribution over one or more notebooks.

13.5 nb_spellchecker

The nb_spellchecker command line utility allows you to spell check markdown cells and comments in code cells in one or more Jupyter notebooks.

13.6 nbval

The nbval package is an extension to py.test that allows you to test the execution of an already run notebook against itself.

Running nbval executes each code cell in one or more notebooks and raises an error message if the output from running the cell differs from the pre-run output.

Adding a particular comment at the start of a cell, or tagging the cell in a particular way, allows it to be exclude for testing purposes, or its output ignored. Cells can also be labeled for where we expect a particular exception to be raised and want to check that error was raised rather than raising an error because the error was raised.

13.7 testbook

The testbook package allows you to write a simple tests file that references particular functions in particular notebooks and run tests against them using a standard Python test framework (handy usage docs).

Code cells in tested notebooks can be referenced by code cell number or cell tag.