Overviewο
Run ruff, isort, pyupgrade, mypy, pylint, flake8, black, blacken-docs, and more on Jupyter Notebooks
β handles IPython magics robustly
β respects your config files
β preserves βquiet modeβ trailing semicolons
β lints both code and markdown cells
Table of contentsο
π Installationο
In your virtual environment, run (note: the $
is not part of the command):
$ python -m pip install -U nbqa
To also install all supported linters/formatters:
$ python -m pip install -U "nbqa[toolchain]"
π Examplesο
Command-lineο
Reformat your notebooks with black:
$ nbqa black my_notebook.ipynb
reformatted my_notebook.ipynb
All done! β¨ π° β¨
1 files reformatted.
Sort your imports with isort:
$ nbqa isort my_notebook.ipynb --float-to-top
Fixing my_notebook.ipynb
Upgrade your syntax with pyupgrade:
$ nbqa pyupgrade my_notebook.ipynb --py37-plus
Rewriting my_notebook.ipynb
Format your markdown cells with blacken-docs:
$ nbqa blacken-docs my_notebook.ipynb --nbqa-md --nbqa-diff
Cell 2
------
--- my_notebook.ipynb
+++ my_notebook.ipynb
@@ -1,2 +1 @@
-First level heading
-===
+# First level heading
To apply these changes, remove the `--nbqa-diff` flag
Format .md
files saved via Jupytext (requires jupytext
to be installed):
$ nbqa black my_notebook.md
reformatted my_notebook.md
All done! β¨ π° β¨
1 files reformatted.
See command-line examples for examples involving doctest, flake8, mypy, pylint, autopep8, pydocstyle, yapf, and ruff.
Pre-commitο
Hereβs an example of how to set up some pre-commit hooks: put this in your .pre-commit-config.yaml
file (see usage as pre-commit hook)
- repo: https://github.com/nbQA-dev/nbQA
rev: 1.8.5
hooks:
- id: nbqa-black
additional_dependencies: [jupytext] # optional, only if you're using Jupytext
- id: nbqa-pyupgrade
args: ["--py37-plus"]
- id: nbqa-isort
args: ["--float-to-top"]
If you need to select specific versions of these linters/formatters,
add them to additional_dependencies
.
π₯³ Used byο
Click here for (non-exhaustive) list of repos
https://github.com/ComPWA/ampform
https://github.com/ComPWA/tensorwaves
https://github.com/DataS-DHSC/os-maps-example
https://github.com/Eazhi/World-Happiness-Analysis
https://github.com/GoogleCloudPlatform/ai-platform-samples
https://github.com/MRCIEU/epigraphdb
https://github.com/OpenMined/PyDP
https://github.com/PlasmaPy/PlasmaPy
https://github.com/ProjectPythia/pythia-foundations
https://github.com/SeldonIO/alibi
https://github.com/TeoZosa/deep-learning-v2-pytorch
https://github.com/WM-SEMERU/mlproj_template
https://github.com/alan-turing-institute/sktime
https://github.com/amor71/LiuAlgoTrader
https://github.com/bbernst/base_envs
https://github.com/cheginit/HyRiver-examples
https://github.com/cheginit/pygeohydro
https://github.com/cheginit/pynhd
https://github.com/covid-19-impact-lab/sid-germany
https://github.com/covid-19-impact-lab/sid
https://github.com/dapperfu/Python-Simulink
https://github.com/deepcharles/ruptures
https://github.com/dhassault/cyclegan_pytorch
https://github.com/gboeing/osmnx
https://github.com/glotzerlab/freud-examples
https://github.com/glotzerlab/hoomd-examples
https://github.com/glotzerlab/signac-docs
https://github.com/glotzerlab/signac-examples
https://github.com/grapl-security/grapl
https://github.com/hainegroup/oceanspy
https://github.com/henryiii/python-compiled-minicourse
https://github.com/intake/intake-esm
https://github.com/jameslamb/lightgbm-dask-testing
https://github.com/jdb78/pytorch-forecasting
https://github.com/jhrcook/advent-of-code_2020
https://github.com/julian-west/asset_price_correlations
https://github.com/kratsg/drstorage
https://github.com/madebr/pyOpt
https://github.com/matthewfeickert/heputils
https://github.com/matyama/deep-rl-hands-on
https://github.com/mayou36/raredecay
https://github.com/neomatrix369/nlp_profiler
https://github.com/openforcefield/openff-system
https://github.com/pandas-profiling/pandas-profiling
https://github.com/paw-lu/dotfiles
https://github.com/pawamoy/wps-light
https://github.com/phinate/clarinet
https://github.com/pik-primap/climate_categories
https://github.com/pik-primap/primap2
https://github.com/pik-primap/unfccc_di_api
https://github.com/pymc-devs/pymc-examples
https://github.com/pymc-devs/resources
https://github.com/saturncloud/examples
https://github.com/scikit-hep/boost-histogram
https://github.com/scikit-hep/iminuit
https://github.com/scikit-hep/mplhep
https://github.com/scikit-hep/pyhf
https://github.com/scikit-hep/pylhe
https://github.com/v-goncharenko/data-science-template
https://github.com/wemake-services/wemake-python-styleguide
https://github.com/zfit/phasespace
https://github.com/zfit/zfit
https://github.com/zfit/zfit-physics
https://github.com/zfit/zfit-tutorials
Is your project missing? Let us know, or open a pull request!
π¬ 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
Simon Brugman, Data scientist & pandas-profiling dev:
nbQA helps us to keep notebooks to the same standards as the rest of the code. If youβre serious about your code standards, you should keep them consistent across both notebooks and python scripts. Great addition to the ecosystem, thanks!
Bradley Dice, PhD Candidate in Physics & Scientific Computing:
nbqa is a clean, easy to use, and effective tool for notebook code style. Formatting and readability makes a huge difference when rendering notebooks in a projectβs documentation!
James Lamb, engineer @saturn_cloud, LightGBM maintainer
today I learned about
nbqa
, a command-line tool to run linters likeflake8
over #Python code in @ProjectJupyter notebooks. Thanks to @jayyqi for pointing me to it. So far, I really really like it.
Lars Yencken, Tech Lead @ Our World In Data
Super useful! I only wish it was built-in to Jupyterlab.
Vincent D. Warmerdam, maintainer @ calmcode.io
Nice. nbQA looks like a great way to prevent the Untitled12.ipynb-phenomenon. I like!
Mani Sarkar, Kaggle 3x expert, contributor
nbQA is an inspiring project, and the team behind it are very knowledgeable and think of things outside the box with ideas and solutions
π₯ 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):
This project follows the all-contributors specification. Contributions of any kind welcome!