colablinter 0.3.0

Linting and formatting Python code in Google Colab.

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 with simple commands.

Magic cell Commands

Command	Description
%clautoformat	Activates or deactivates automatic import sorting, formatting, and execution time display before every cell.
%%clcheck	Displays a linting report for the current cell.

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

Installation

Just run it in colab:

!uv pip install colablinter

The extension must be explicitly loaded in the notebook session before use.

%load_ext colablinter

Once loaded, %clautoformat is activated by default to keep your code clean from the start.

Usage

1. Activate/Deactivate Auto Fix (%clautoformat)

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

   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)
   

   To deactivate auto fixing:

   %clautoformat off # %clautoformat on when you want to activate
   

2. Check cell quality (%%clcheck)

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

   %%clcheck
   
   def invalid_code(x):
       return x + y
   

   Output:

   [ColabLinter:INFO] F821 Undefined name `y`
   --> tmp.py:2:16
     |
   1 | def invalid_code(x):
   2 |     return x + y
     |                ^
     |
   Found 1 error.
   [ColabLinter:INFO] ✔ Done | 0.015s
   

   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.

Known Caveats & Troubleshooting

Magic Command Execution: When using magic or terminal commands while %clautoformat 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 %clautoformat off