jupyfmt

The uncompromising Jupyter notebook formatter.

jupyfmt allows you to format notebooks in-place from the commandline as well as assert properly formatted Jupyter notebook cells in your CI. Inspired by snakefmt.

The following formatters are included for each language:

• Python: black
• R: styler

Installation

Install the latest release from PyPI:

$ pip install jupyfmt

Usage

jupyfmt can be used to format notebooks in-place or report diffs and summary statistics.

Overview of commandline parameters:

$ jupyfmt --help
Usage: jupyfmt [OPTIONS] [PATH_LIST]...

  The uncompromising Jupyter notebook formatter.

  PATH_LIST specifies notebooks and directories to search for notebooks in. By
  default, all notebooks will be formatted in-place. Use `--check`, `--diff`
  (or `--compact-diff`) to print summary reports instead.

Options:
  -l, --line-length INT           How many characters per line to allow.
  -S, --skip-string-normalization
                                  Don't normalize string quotes or prefixes.
  --check                         Don't write files back, just return status
                                  and print summary.
  -d, --diff                      Don't write files back, just output a diff
                                  for each file to stdout.
  --compact-diff                  Same as --diff but only show lines that
                                  would change plus a few lines of context.
  --assert-consistent-execution   Assert that all cells have been executed in
                                  correct order.
  --exclude PATTERN               Regular expression to match paths which
                                  should be exluded when searching
                                  directories.  [default: (/.git/|/.ipynb_chec
                                  kpoints/|/build/|/dist/)]
  --accepted-languages PATTERN    Only format Jupyter notebooks in these
                                  languages.  [default: python]
  --exclude-nonkernel-languages   Only format code cells in language of
                                  notebook kernel.
  --version                       Show the version and exit.
  --help                          Show this message and exit.

Report formatting suggestions for a given notebook (this is particularly useful for CI workflows):

$ jupyfmt --check --compact-diff Notebook.ipynb
--- Notebook.ipynb - Cell 1 (original)
+++ Notebook.ipynb - Cell 1 (formatted)
@@ -1,2 +1,2 @@
-def foo (*args):
+def foo(*args):
     return sum(args)

--- Notebook.ipynb - Cell 2 (original)
+++ Notebook.ipynb - Cell 2 (formatted)
@@ -1 +1 @@
-foo(1, 2,3)
+foo(1, 2, 3)

2 cell(s) would be changed 😬
1 cell(s) would be left unchanged 🎉

1 file(s) would be changed 😬

Mega-Linter Integration

jupyfmt can be run as part of Mega-Linter by adding the following to .mega-linter.yml:

PLUGINS:
  - https://raw.githubusercontent.com/kpj/jupyfmt/master/mega-linter-plugin-jupyfmt/jupyfmt.megalinter-descriptor.yml

ENABLE_LINTERS:
  - JUPYTER_JUPYFMT