Run any Python code quality tool on a Jupyter Notebook!
Project description
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.
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.17
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 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 ===============================
Format your notebooks using black
:
$ nbqa black . --line-length=96 --nbqa-mutate
reformatted tweet-sentiment-roberta-pytorch.ipynb
All done! ✨ 🍰 ✨
1 files reformatted.
Note that if, as in this last example, you expect your notebooks to be modified, you will need to
pass the --nbqa-mutate
flag (alternatively, you could set mutate=1
in your .nbqa.ini
file, see “Configuration”).
Empty __init__.py
files
Some tools, such as mypy
, require (possibly empty) __init__.py
files to be in each subdirectory you wish to analyse. To make nbQA
aware of this,
you need to pass the --nbqa-preserve-init
flag, e.g.
nbqa mypy my_dir/my_subdir/my_notebook.ipynb --nbqa-preserve-init
Alternatively, you could set preserve_init=1
in your .nbqa.ini
file (see “Configuration”).
Configuration
You can tell nbQA which config file to use either by using the --nbqa-config
flag, or by
specifying it in a .nbqa.ini
file.
So for example, if you wanted to run mypy
in such a way that it respects your .mypy.ini
file _and_ with the --pretty
flag, then you could either run
nbqa mypy my_notebook.ipynb --pretty --nbqa-config .mypy.ini --nbqa-preserve-init
or, you could put the following in your .nbqa.ini
file
[mypy]
addopts = --pretty
config = .mypy.ini
preserve_init = 1
and then simply run
nbqa mypy my_notebook.ipynb
You can also tell nbQA
to allow mutations, e.g.
[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.17
hooks:
- id: nbqa
args: ['flake8']
name: nbqa-flake8
additional_dependencies: ['flake8']
- id: nbqa
args: ['isort', '--nbqa-mutate']
name: nbqa-isort
additional_dependencies: ['isort']
- id: nbqa
args: ['mypy']
name: 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:
See Also
Here are some specialised code quality tools for Jupyter Notebooks:
Project template from cookiecutter.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.