nbqa 0.1.27

Run any Python code quality tool on a Jupyter Notebook!

nbQA

Adapter to run any code-quality tool on a Jupyter notebook. This is intended to be run as a pre-commit hook and/or during continuous integration.

Documentation is hosted here.

Installation

Install nbqa with pip:

$ pip install nbqa

Quickstart

The general syntax is

nbqa <command> <notebook or directory> <args>

where command is any standard Python code quality tool.

Examples

Check static type annotations:

$ nbqa mypy tweet-sentiment-roberta-pytorch.ipynb --ignore-missing-imports
tweet-sentiment-roberta-pytorch.ipynb:cell_10:5: error: Argument "batch_size" to "get_test_loader" has incompatible type "str"; expected "int"

Check the examples in your docstrings are correct:

$ nbqa doctest tweet-sentiment-roberta-pytorch.ipynb

Format your notebooks using black:

$ nbqa black . --line-length=96 --nbqa-mutate
reformatted tweet-sentiment-roberta-pytorch.ipynb
All done! ✨ 🍰 ✨
1 files reformatted.

Configuration

You can configure nbQA either at the command line, or by using a .nbqa.ini file. We’ll see some examples below.

Extra flags

If you wish to pass extra flags (e.g. --ignore W503 to flake8) you can either run

nbqa flake8 my_notebook.ipynb --ignore W503

or you can put the following in your .nbqa.ini file

[flake8]
addopts = --ignore W503

Config file

If you already have a config file for your third-party tool (e.g. .mypy.ini for mypy), you can run

nbqa mypy my_notebook.ipynb --nbqa-config .mypy.ini

or you can put the following in your .nbqa.ini file

[mypy]
config = .mypy.ini

Allow mutations

By default, nbQA won’t modify your notebooks. If you wish to let your third-party tool modify your notebooks, you can either pass the --nbqa-mutate flag at the command-line, e.g.

nbqa black my_notebook.ipynb --nbqa-mutate

or you can put the following in your .nbqa.ini file

[black]
mutate = 1

Usage as pre-commit hook

If you want to use nbqa with pre-commit, here’s an example of what you could add to your .pre-commit-config.yaml file:

- repo: https://github.com/nbQA-dev/nbQA
  rev: 0.1.27
  hooks:
    - id: nbqa
      args: ['flake8']
      name: nbqa-flake8
      alias: nbqa-flake8
      additional_dependencies: ['flake8']
    - id: nbqa
      args: ['isort', '--nbqa-mutate']
      name: nbqa-isort
      alias: nbqa-isort
      additional_dependencies: ['isort']
    - id: nbqa
      args: ['mypy']
      name: nbqa-mypy
      alias: nbqa-mypy
      additional_dependencies: ['mypy']

Supported third party packages

In theory, nbqa can adapt any Python code-quality tool to a Jupyter Notebook.

In practice, here are the tools it’s been tested with:

• flake8

• black

• isort

• mypy

• doctest

Contributing

I will give write-access to anyone who contributes anything useful (e.g. pull request / bug report) - see the contributing guide for details on how to do so.

See Also

Here are some other code quality tools for Jupyter Notebooks:

• flake8-nb (apply flake8 to notebook);

• nb_black and black-nb (apply black to notebook);

• nbstripout (clear notebook cells’ outputs);

• jupyterlab_code_formatter (Jupyter Lab plugin);