nbqa 0.1.9

Run any Python code quality tool on a Jupyter Notebook!

nbQA

Adapter to run any code-quality tool on a Jupyter notebook. Documentation is hosted here.

Prerequisites

If you don’t have pip installed, this Python installation guide can guide you through the process.

Installation

Install nbqa with

$ pip install nbqa

There are no dependencies for nbqa so installation should be lightning-fast. Check your installation with

$ nbqa --version
nbqa 0.1.9

Quickstart

The general syntax is

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

, where command is any Python code quality tool. For example, you could run:

$ nbqa flake8 my_notebook.ipynb
$ nbqa black my_notebook.ipynb --check
$ nbqa mypy my_notebook.ipynb --ignore-missing-imports
$ nbqa pytest my_notebook.ipynb --doctest-modules

You can also pass an entire directory instead of a single file, e.g. nbqa flake8 my_notebooks.

Examples

Format your notebooks using black:

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

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 any examples in your docstrings are correct:

$ nbqa pytest tweet-sentiment-roberta-pytorch.ipynb --doctest-modules
============================= test session starts ==============================
platform linux -- Python 3.8.2, pytest-5.4.3, py-1.9.0, pluggy-0.13.1
rootdir: /home/marco/tweet-sentiment-extraction
plugins: cov-2.10.0
collected 3 items

tweet-sentiment-roberta-pytorch.ipynb .                                  [100%]

============================== 1 passed in 0.03s ===============================

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

• pytest

• isort

• mypy (you will need to have __init__ files in each subdirectory)

• doctest (as long as you run it via pytest with the –doctest-modules flag)

Configuration

You can pass extra configurations to your tools either via the command line (as in the examples above), or in a .nbqa.ini file, which could look something like this:

[black]
line-length=96

[flake8]
max-line-length=88
ignore=E203,W503,W504

Flags from this .ini will be passed to nbqa as they’re written.

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/MarcoGorelli/nbQA-mirror-0
  rev: 0.1.9
  hooks:
    - id: nbqa
      args: ['flake8']
      name: nbqa-flake8
- repo: https://github.com/MarcoGorelli/nbQA-mirror-1
  rev: 0.1.9
  hooks:
    - id: nbqa
      args: ['isort']
      name: nbqa-isort
- repo: https://github.com/MarcoGorelli/nbQA-mirror-2
  rev: 0.1.9
  hooks:
    - id: nbqa
      args: ['mypy']
      name: nbqa-mypy

It’s entirely optional which tool to use with which mirror, the purpose of having these mirrors is to avoid duplicate keys in the .pre-commit.yaml file, but they’re all the same. I’m keeping 10 mirrors up-to-date with this repository, so currently that’s the maximum number of pre-commit hooks you can have for nbqa tools.

See Also

Here are some other code quality tools for Jupyter Notebooks:

• flake8-nb;

• black-nb.

Project template from cookiecutter.