colablinter

Overview

colablinter is an IPython magic command extension designed for Jupyter and Google Colab notebooks. It integrates the high-speed linter ruff to perform code quality checks and formatting directly within Jupyter/Colab cells. It allows developers to lint code on a cell-by-cell basis or the entire notebook with simple commands.

Magic cell Commands

Command	Description
%%cformat	Sorts imports and Formats the current cell's code.
%%ccheck	Displays a linting report for the current cell.
%lautoformat	Activates or deactivates automatic import sorting, formatting, and execution time display before every cell.
%lcheck	Displays a linting report for the entire saved notebook (requires Google Drive mount).

After executing a cell magic command, the checked/formatted code is immediately executed (if applicable), maintaining the notebook workflow.

Installation

Requires Python 3.10 or newer.

pip install colablinter

Usage

The extension must be explicitly loaded in the notebook session before use. Once the extension is loaded, %lautoformat is activated by default.

%load_ext colablinter

1. Sorts imports and Formats cell (%%cformat)

   %%cformat corrects code and runs the formatter. The cell executes after cell is formatted.

   %%cformat
   import math, sys;
   
   class Example(   object ):
       def __init__    ( self, bar ):
         if bar : bar+=1;  bar=bar* bar   ; return bar
         else:
                       some_string = "foo"
                       return (sys.path, some_string)

   Fixed Cell:

   import math
   import sys
   
   
   class Example(object):
       def __init__(self, bar):
           if bar:
               bar += 1
               bar = bar * bar
               return bar
           else:
               some_string = "foo"
               return (sys.path, some_string)

2. Check cell quality (%%ccheck)

   Use %%ccheck to see linting reports for the code below the command. After the report is displayed, the code in the cell executes as normal.

   %%ccheck
   
   def invalid_code(x):
       return x + y # 'y' is not defined

   Output:

   [ColabLinter:INFO] F821 Undefined name `y`
   --> notebook_cell.py:2:16
   |
   1 | def invalid_code(x):
   2 |     return x + y # 'y' is not defined
   |                  ^
   |
   
   Found 1 error.

   Note on F401: The linter is explicitly configured to ignore F401 errors (unused imports). This is to ensure compatibility with the stateful nature of Jupyter/Colab notebooks, where imports in one cell may be necessary for code execution in subsequent cells, preventing unintended breakage of the notebook's execution flow.

3. Activate/Deactivate Auto Fix (%lautoformat)

   The %lautoformat line magic allows you to automatically fix code before every code cell is executed.

   To Activate Auto Fixing:

   %lautoformat on # %lautoformat off when you want to deactivate

4. Check entire notebook (%lcheck)

   Use line magic %lcheck to check across the entire saved notebook file (requires the notebook to be saved to Google Drive and mounted).

   %lcheck /content/drive/MyDrive/Colab Notebooks/path/to/notebook.ipynb

Known Caveats & Troubleshooting

Magic Command Execution: When using magic or terminal commands while %lautoformat is active, the auto-format mechanism is temporarily suppressed during the final execution step to prevent infinite loops or dual checks. If you want to disable auto-formatting, use %lautoformat off