Run any standard Python code quality tool on a Jupyter Notebook

Table of contents

• Table of contents
  • 🎉 Installation
  • 🚀 Examples
    • Command-line
    • Pre-commit
  • 🥳 Used by
  • 💬 Testimonials
  • 👥 Contributing

🎉 Installation

In your virtual environment, run one of the following:

• python -m pip install -U nbqa (minimal installation)
• python -m pip install -U nbqa[toolchain] (install supported code quality tools as well)
• conda install -c conda-forge nbqa (if you use conda)

🚀 Examples

Command-line

Reformat your notebooks with black:

$ nbqa black my_notebook.ipynb --nbqa-mutate
reformatted my_notebook.ipynb
All done! ✨ 🍰 ✨
1 files reformatted.

Sort your imports with isort:

$ nbqa isort my_notebook.ipynb --nbqa-mutate
Fixing my_notebook.ipynb

Upgrade your syntax with pyupgrade:

$ nbqa pyupgrade my_notebook.ipynb --py36-plus --nbqa-mutate
Rewriting my_notebook.ipynb

See command-line examples for examples involving pylint, flake8, doctest, and mypy.

Pre-commit

Here's an example of how to set up some pre-commit hooks:

1. Put this in your pyproject.toml file (see configuration for details)

   [tool.nbqa.mutate]
   isort = 1
   black = 1
   pyupgrade = 1
   
   [tool.nbqa.addopts]
   pyupgrade = ["--py36-plus"]

2. Put this in your .pre-commit-config.yaml file (see usage as pre-commit hook)

   - repo: https://github.com/nbQA-dev/nbQA
     rev: 0.4.1
     hooks:
       - id: nbqa-black
         additional_dependencies: [black==20.8b1]
       - id: nbqa-pyupgrade
         additional_dependencies: [pyupgrade==2.7.3]
       - id: nbqa-isort
         additional_dependencies: [isort==5.6.4]

🥳 Used by

Take some inspiration from their config files 😉

• alibi .pre-commit-config.yaml
• iminuit pyproject.toml .pre-commit-config.yaml
• LiuAlgoTrader: requirements/dev.txt
• NLP Profiler: pyproject.toml .pre-commit-config.yaml
• pandas-profiling .pre-commit-config.yaml
• pyhf pyproject.toml .pre-commit-config.yaml
• PyMC3: pyproject.toml .pre-commit-config.yaml
• PyMC Resources: pyproject.toml .pre-commit-config.yaml
• Python compiled microcourse: .pre-commit-config.yaml
• sktime: .pre-commit-config.yaml

💬 Testimonials

Michael Kennedy & Brian Okken, hosts of the Python Bytes podcast:

This is really cool. I think it brings so much of the code formatting and code analysis, clean up to notebooks, which I think had been really lacking

Nikita Sobolev, CTO at wemake.services:

It is amazing!

Alex Andorra, Data Scientist, ArviZ & PyMC Dev, Host of 'Learning Bayesian Statistics' Podcast:

well done on nbqa @MarcoGorelli ! Will be super useful in CI

Matthew Feickert Postdoc at University of Illinois working on LHC physics:

nbqa in your pre-commit hooks along with @codewithanthony 's pre-commit CI service is amazing! Everyone using Jupyter notebooks should be doing this.

Girish Pasupathy, Software engineer and now core-contributor:

thanks a lot for your effort to create such a useful tool

👥 Contributing

I will give write-access to anyone who makes a useful pull request - see the contributing guide for details on how to do so.

Thanks goes to these wonderful people (emoji key):

Marco Gorelli 💻 🚧 👀 ⚠️ 🤔	Sebastian Weigand 🔧 👀 📖 🤔	Girish Pasupathy 💻 🚇 🐛 👀 🤔	fcatus 🚇	HD23me 🐛	mani 🤔 🚇	Daniel Mietchen 🤔
Michał Gacka 🐛	Happy 📖	Nat Taylor 🤔 💻 🔧 🐛	Caio Ariede 📖	Nikita Sobolev 🤔 🐛 📖	Amichay Oren 🤔	pylang 🤔
Henry Schreiner 🐛

This project follows the all-contributors specification. Contributions of any kind welcome!