ruff-jupyter-jetbrains 1.0.0

Add your description here

ruff-jupyter-jetbrains

ruff-jupyter-jetbrains is a python package that is designed to be run as a file watcher tool in JetBrains IDEs to display ruff linting inspections in Jupyter notebooks.

Usage

1. Install the package in your environment, using your package manager of choice. E.g:

   uv add --dev ruff-jupyter-jetbrains
   

2. Ensure you have the JetBrains File Watchers plugin enabled.

3. Under Settings > Tools > File Watchers, configure a new file watcher with the following settings:

   • File type: Jupyter Notebook
   • Program: uv (or your tool of choice)
   • Arguments: run ruff-jupyter-jetbrains $FilePath$
   • Show console: Never (unless you need to debug)
   • Output Filters: $FILE_PATH$:$LINE$:$COLUMN$: $MESSAGE$

4. Set your desired severity level and color scheme under Settings > Editor > Inspections > File watcher problems

Alternative Usage

If you want to keep your project dependencies minimal, you could also use an isolated runner like uvx, without installing the package in your environment. In that case ignore step 1 above and use the following settings instead:

• Program: uvx
• Arguments: ruff-jupyter-jetbrains $FilePath$

---

How it works

JetBrains maintains an intermediary notebook representation that differs from the raw notebook JSON content: each cell source appears as is in order and is marked up with a comment line that specifies its type (# %% for code and # %%m for markdown).

In addition, custom JetBrains file watchers can show inspection messages when their output can be parsed into a file path, line, column and message.

With that knowledge the ruff linting output can be used and converted to a format compatible with JetBrains file watchers.

[!WARNING]

This little tool, while functional, is only meant as a workaround. Ideally, this functionality should live in a proper plugin that makes use of the language server protocol. This was motivated by a standing issue in the Ruff plugin and my lack of Kotlin knowledge to fix it at the root.

---

Development

Setup

Clone the repo:

git clone https://github.com/OliverSieweke/ruff-jupyter-jetbrains.git

This project uses uv as a project manager. To set up the environment, ensure uv is installed and run:

uv sync

To ensure code follows the project’s guidelines, install pre-commit hooks with:

pre-commit install

Code Standards

ruff is used as a formatter and can be run with:

ruff format

ruff is used as a linter and code can be checked with:

ruff check

ty is used as a type checker and code can be checked with:

ty check

Tests are handled by pytest and can be run with:

pytest