Usage

Since flake8_nb is basically a hacked version of flake8 its usage is identically. The only key difference is the appended _nb is the commands and configurations name.

Command line usage

The basic usage is to call flake8_nb with the files/paths, which should be checked as arguments (see flake8 invocation).

$ flake8_nb path-to-notebooks-or-folder

To customize the behavior you can use the many options provided by flake8’s CLI. To see all the provided option just call:

$ flake8_nb --help

Additional flags/options provided by flake8_nb:

  • --keep-parsed-notebooks

    If this flag is activated the the parsed notebooks will be kept and the path they were saved in will be displayed, for further debugging or trouble shooting.

  • --notebook-cell-format

    Template string used to format the filename and cell part of error report. Possible variables which will be replaced are nb_path, exec_count, code_cell_count and total_cell_count.

Project wide configuration

Configuration of a project can be saved in one of the following files setup.cfg, tox.ini or .flake8_nb, on the top level of your project (see flake8 configuration).

[flake8_nb]
; Default values
keep_parsed_notebooks = False
notebook_cell_format = {nb_path}#In[{exec_count}]

For a detailed explanation on how to use and configure it, you can consult the official flake8 documentation

Per cell/line configuration

There are multiple ways to fine grade configure flake8_nb on a line or cell basis.

flake8 noqa comments

The most intuitive way for experienced flake8 users is to utilize the known flake8 noqa comment on a line, to ignore specific or all errors, flake8 would report on that given line.

Note

If a normal flake8 noqa comment ends with a string, which doesn’t match the error code patter (\w+\d+), this comment will be ignored.

Cell tags

Cell tags are meta information, which can be added to cells, to augment their behavior (for jupyterlab<2.0, you will need to install jupyterlab-celltags ). Depending on the editor you use for the notebook, they aren’t directly visible, which is a nice way to hide certain internals which aren’t important for the user/reader. For example if write a book like notebook and want to demonstrate some bad code examples an still pass your flake8_nb tests you can use flake8-noqa-tags. Or if you want to demonstrate a raised exception and still want then whole notebook to be executed when you run all cells, you can use the raises-exception tag.

The patterns for flake8-noqa-tags are the following:

  • flake8-noqa-cell

    ignores all reports from a cell

  • flake8-noqa-cell-<rule1>-<rule2>

    ignores given rules for the cell i.e. flake8-noqa-cell-F401-F811

  • flake8-noqa-line-<line_nr>

    ignores all reports from a given line in a cell, i.e. flake8-noqa-line-1

  • flake8-noqa-line-<line_nr>-<rule1>-<rule2>

    ignores given rules from a given line for the cell i.e. flake8-noqa-line-1-F401-F811

Inline cell tags

If you want your users/reader to directly see which flake8 rules are ignored, you can also use the flake8-noqa-tag pattern as comment in a cell.

Note

If you use jupyter magic to run code other than Python (i.e. %%bash) you should ignore the whole cell with flake8-noqa-cell.

As pre-commit hook

Add the following to your .pre-commit-config.yaml file:

- repo: https://github.com/s-weigand/flake8-nb
  rev: 0.4.0 # specify version here
  hooks:
  - id: flake8-nb

See pre-commit docs for more on pre-commit.