nbqa

library1.9.1pypypiunverified

nbqa is a command-line tool that allows you to run any standard Python code quality tool on Jupyter Notebooks. It robustly handles IPython magics, respects your existing configuration files (like `pyproject.toml`), and can lint both code and markdown cells. The current version is 1.9.1, with frequent minor point releases.

testing

pip install nbqa

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · NBQA

nbqa

testingpythonv1.9.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

This quickstart demonstrates how to install `nbqa` and `black`, then use `nbqa` to format a Jupyter Notebook. Remember to install the specific code quality tools (like `black`, `flake8`, `isort`) you wish to use alongside `nbqa`.

# Install nbqa and a code quality tool (e.g., black) pip install -U nbqa black # Create a dummy notebook (e.g., my_notebook.ipynb) echo '{ "cells": [ { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": ["import os\n\nx = 1 + 2"] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.9.0" } }, "nbformat": 4, "nbformat_minor": 4 }' > my_notebook.ipynb # Run black on the notebook using nbqa nbqa black my_notebook.ipynb # Expected output will show reformatting, e.g.: # reformatted my_notebook.ipynb # All done! ✨ 🍰 ✨ 1 file reformatted. # To verify changes (if you open the notebook, it should be formatted) # cat my_notebook.ipynb

nbqa --version

Debug

Known issues

gotchanbqa converts code cells to temporary Python files for linting. This conversion process can cause certain tool-specific flags, such as `flake8`'s `--per-file-ignores`, to behave unexpectedly or not work perfectly.

fix

Review `nbqa`'s documentation on known limitations and how specific tool configurations interact with its conversion process. Consider alternative configuration methods via `pyproject.toml` or `nbqa`'s own `--nbqa-files` and `--nbqa-exclude` flags.

affects: All versions

gotchaBy default, nbqa skips cells with invalid syntax. While this can be overridden with the `--nbqa-dont-skip-bad-cells` flag, cells containing multi-line IPython magics or automagics (e.g., `%timeit`) will still not be processed.

fix

Use `--nbqa-dont-skip-bad-cells` cautiously for syntax errors. Be aware that magics like `%%time` or `%matplotlib inline` are generally ignored or cannot be processed by underlying tools.

affects: All versions

gotchaWhen configuring `nbqa` via both `pyproject.toml` and command-line arguments, command-line arguments take precedence for `nbqa`'s own flags. For flags passed through to the underlying code quality tools, both sets of flags might be used, with `pyproject.toml` flags applied first. This can lead to tool-dependent or unexpected behavior.

fix

Carefully manage your configuration sources. Prefer `pyproject.toml` for consistent project-wide settings and use command-line arguments only for temporary overrides or specific runs. Consult the documentation of the specific code quality tool for how it handles duplicate or conflicting arguments.

affects: All versions

gotchanbqa is designed primarily for command-line execution or integration into pre-commit hooks and CI/CD pipelines. It is not intended for real-time, interactive code quality checks directly within a running Jupyter Notebook or JupyterLab interface.

fix

For interactive in-notebook formatting, consider JupyterLab extensions like `jupyterlab_code_formatter`. `nbqa` is best utilized as a pre-commit check or a batch process.

affects: All versions

gotchaWhen using `nbqa` as a `pre-commit` hook, particularly with `additional_dependencies`, running `pre-commit autoupdate` will update the `nbqa` hook itself, but *not* the versions of the code quality tools (e.g., `black`, `isort`) specified in `additional_dependencies`. These must be updated manually for reproducibility.

fix

Manually review and update the versions of your `additional_dependencies` in your `.pre-commit-config.yaml` to ensure you are using the desired versions of code quality tools. Pinning versions is recommended for reproducibility.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'black'

The underlying code quality tool (e.g., 'black', 'flake8', 'isort', 'mypy') that nbqa is trying to run has not been installed in the environment where nbqa is executed.

fix

Install the missing tool using pip; for example, `pip install black` or `pip install "nbqa[toolchain]"` to install all supported tools.

nbqa: command not found

The nbqa command-line tool is either not installed, or its installation directory is not included in your system's PATH environment variable.

fix

Ensure nbqa is installed (`pip install nbqa`) and that your Python scripts directory (e.g., `~/.local/bin` on Linux/macOS or `Scripts` in your Python installation on Windows) is correctly added to your system's PATH. Restart your terminal after making changes.

ERROR: cannot format <notebook_path>: Cannot parse: <line>:<col>: <error_message>

The 'black' formatter, when invoked via nbqa, encountered a syntax error, an unparsable construct, or a specific IPython magic in the notebook cell at the reported line and column, preventing successful formatting.

fix

Inspect the code in the specified notebook cell for syntax errors or problematic IPython magics. You might need to adjust the code, or for certain magics, consider using `nbqa`'s `--nbqa-process-cells` flag. Upgrading both `nbqa` and `black` to their latest versions may also resolve compatibility issues.

E302 expected 2 blank lines, found 1

Linter errors like E302 (expected blank lines) and E305 (expected blank lines after class/function definition) from tools like `flake8` are commonly triggered because nbqa converts notebook cells to temporary Python files, which can alter the contextual spacing and lead to false positives based on typical Python file conventions.

fix

Configure the linter to ignore these specific errors for notebooks. You can add `ignore = E302,E305` to your `pyproject.toml` or `.flake8` configuration file under the `[flake8]` section, or pass `--extend-ignore=E302,E305` directly to the `nbqa flake8` command.

Upgrade

Version history

1.9.1latest on PyPI · released Nov 10, 2024

Audit

Dependencies

pythonrequirednbqa requires Python 3.9 or higher.

autopep8requiredCore dependency for functionality.

ipythonrequiredCore dependency for functionality.

tokenize-rtrequiredCore dependency for functionality.

tomlirequiredCore dependency for configuration parsing.

Agent activity

16 hits · last 30 days

node

Resources

githubhttps://github.com/nbQA-dev/nbQA ↗

packagehttps://pypi.org/project/nbqa/ ↗

docshttps://nbQA.readthedocs.io/en/latest/ ↗