Add ruff tool (#773)

* add ruff tool to pre-commit hooks

* added missing field language

* added test

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* added example

* added link

* added ruff to toolchain requirements

* Update tests/tools/test_ruff_works.py

Co-authored-by: Marco Edward Gorelli <[email protected]>

* [pre-commit-hook] ruff invoked with --quiet

* no quiet

* fixup

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Marco Edward Gorelli <[email protected]>
Co-authored-by: MarcoGorelli <>

.pre-commit-hooks.yaml

@@ -86,3 +86,11 @@
   require_serial: true
   types_or: [jupyter, markdown]
   additional_dependencies: [pydocstyle]
+- id: nbqa-ruff
+  name: nbqa-ruff
+  description: Run 'ruff' on a Jupyter Notebook
+  entry: nbqa ruff
+  language: python
+  additional_dependencies: [ruff]
+  require_serial: true
+  types_or: [jupyter, markdown]

README.md

@@ -132,7 +132,7 @@ All done! ✨ 🍰 ✨
 1 files reformatted.
 ```
 
-See [command-line examples](https://nbqa.readthedocs.io/en/latest/examples.html) for examples involving [doctest](https://docs.python.org/3/library/doctest.html), [flake8](https://flake8.pycqa.org/en/latest/), [mypy](http://mypy-lang.org/), [pylint](https://github.com/PyCQA/pylint), [autopep8](https://github.com/hhatto/autopep8), [pydocstyle](http://www.pydocstyle.org/en/stable/), and [yapf](https://github.com/google/yapf).
+See [command-line examples](https://nbqa.readthedocs.io/en/latest/examples.html) for examples involving [doctest](https://docs.python.org/3/library/doctest.html), [flake8](https://flake8.pycqa.org/en/latest/), [mypy](http://mypy-lang.org/), [pylint](https://github.com/PyCQA/pylint), [autopep8](https://github.com/hhatto/autopep8), [pydocstyle](http://www.pydocstyle.org/en/stable/), [yapf](https://github.com/google/yapf), and [ruff](https://github.com/charliermarsh/ruff/).
 
 ### Pre-commit
 
@@ -150,7 +150,7 @@ Here's an example of how to set up some pre-commit hooks: put this in your `.pre
       args: ["--float-to-top"]
 ```
 
-If you need to select specific versions of any of these linters/formatters,
+If you need to select specific versions of these linters/formatters,
 add them to [`additional_dependencies`](http://pre-commit.com/#pre-commit-configyaml---hooks).
 
 ## 🥳 Used by

docs/examples.rst

@@ -97,6 +97,18 @@ Format ``.md`` file saved via `Jupytext`_ (note: requires ``jupytext`` to be ins
 
    $ nbqa black my_notebook.md
 
+Perform linting on a notebook with `ruff`_:
+
+.. code:: console
+
+   $ nbqa ruff my_notebook.ipynb
+
+you can also try to auto-fix reported issues via
+
+.. code:: console
+
+   $ nbqa ruff --fix my_notebook.ipynb
+
 .. _black: https://black.readthedocs.io/en/stable/
 .. _doctest: https://docs.python.org/3/library/doctest.html
 .. _flake8: https://flake8.pycqa.org/en/latest/
@@ -109,3 +121,4 @@ Format ``.md`` file saved via `Jupytext`_ (note: requires ``jupytext`` to be ins
 .. _autopep8: https://github.com/hhatto/autopep8
 .. _pydocstyle: http://www.pydocstyle.org/en/stable/
 .. _blacken-docs: https://github.com/asottile/blacken-docs
+.. _ruff: https://github.com/charliermarsh/ruff

requirements-dev.txt

@@ -15,4 +15,5 @@ pytest
 pytest-cov
 pytest-randomly
 pyupgrade
+ruff
 yapf

setup.cfg

@@ -52,6 +52,7 @@ toolchain =
     mypy
     pylint
     pyupgrade
+    ruff
 
 [flake8]
 extend-ignore = E203,E503

tests/tools/test_ruff_works.py

@@ -0,0 +1,93 @@
+"""Check :code:`ruff` works as intended."""
+
+import os
+from typing import TYPE_CHECKING
+
+import pytest
+
+from nbqa.__main__ import main
+
+if TYPE_CHECKING:
+    from _pytest.capture import CaptureFixture
+
+
+@pytest.mark.parametrize(
+    "path_0, path_1, path_2",
+    (
+        (
+            os.path.abspath(
+                os.path.join("tests", "data", "notebook_for_testing.ipynb")
+            ),
+            os.path.abspath(
+                os.path.join("tests", "data", "notebook_for_testing_copy.ipynb")
+            ),
+            os.path.abspath(
+                os.path.join("tests", "data", "notebook_starting_with_md.ipynb")
+            ),
+        ),
+        (
+            os.path.join("tests", "data", "notebook_for_testing.ipynb"),
+            os.path.join("tests", "data", "notebook_for_testing_copy.ipynb"),
+            os.path.join("tests", "data", "notebook_starting_with_md.ipynb"),
+        ),
+    ),
+)
+def test_ruff_works(
+    path_0: str, path_1: str, path_2: str, capsys: "CaptureFixture"
+) -> None:
+    """
+    Check flake8 works. Shouldn't alter the notebook content.
+
+    Parameters
+    ----------
+    capsys
+        Pytest fixture to capture stdout and stderr.
+    """
+    # check passing both absolute and relative paths
+
+    main(["ruff", path_0, path_1, path_2])
+
+    expected_path_0 = os.path.join("tests", "data", "notebook_for_testing.ipynb")
+    expected_path_1 = os.path.join("tests", "data", "notebook_for_testing_copy.ipynb")
+    expected_path_2 = os.path.join("tests", "data", "notebook_starting_with_md.ipynb")
+
+    out, err = capsys.readouterr()
+    expected_out = (
+        "Found 13 error(s).\n"
+        f"{expected_path_1}:cell_1:1:8: F401 `os` imported but unused\n"
+        f"{expected_path_1}:cell_1:3:8: F401 `glob` imported but unused\n"
+        f"{expected_path_1}:cell_1:5:8: F401 `nbqa` imported but unused\n"
+        f"{expected_path_0}:cell_1:1:8: F401 `os` imported but unused\n"
+        f"{expected_path_0}:cell_1:3:8: F401 `glob` imported but unused\n"
+        f"{expected_path_0}:cell_1:5:8: F401 `nbqa` imported but unused\n"
+        f"{expected_path_0}:cell_4:1:1: E402 Module level import not at top of file\n"
+        f"{expected_path_0}:cell_4:1:20: F401 `random.randint` imported but unused\n"
+        f"{expected_path_0}:cell_5:1:1: E402 Module level import not at top of file\n"
+        f"{expected_path_0}:cell_5:2:1: E402 Module level import not at top of file\n"
+        f"{expected_path_2}:cell_1:1:8: F401 `os` imported but unused\n"
+        f"{expected_path_2}:cell_1:3:8: F401 `glob` imported but unused\n"
+        f"{expected_path_2}:cell_1:5:8: F401 `nbqa` imported but unused\n"
+        "10 potentially fixable with the --fix option.\n"
+    )
+    assert "\n".join(sorted(out.replace("\r\n", "\n").splitlines())) == "\n".join(
+        sorted(expected_out.splitlines())
+    )
+    assert err == ""
+
+
+def test_cell_with_all_magics(capsys: "CaptureFixture") -> None:
+    """
+    Should ignore cell with all magics.
+
+    Parameters
+    ----------
+    capsys
+        Pytest fixture to capture stdout and stderr.
+    """
+
+    path = os.path.join("tests", "data", "all_magic_cell.ipynb")
+    main(["ruff", path])
+
+    out, err = capsys.readouterr()
+    assert out == ""
+    assert err == ""