Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 39 ยท Projects and Practice

Project: A Notebook Linter

Build a small linter that reads .ipynb JSON and reports hidden state, missing titles, leaked secrets, long cells and uncleared outputs, then wire it into pre-commit and CI.

In this project you build a tool that reads a notebook and reports problems before a human reviewer has to: out-of-order execution, missing title, secrets in outputs, giant cells, leftover %pip install lines. It pulls together many earlier lessons (hidden state, structure, security) and shows that a notebook is just data you can analyze.

Everything runs in the Pyodide sandbox here. The notebook is a Python dictionary, exactly what json.load returns for a real .ipynb file. Step 6 shows how to turn the pieces into a command-line script you can run on your machine.

Plan

flowchart LR
  A["Read .ipynb JSON"] --> B["Rules: each returns findings"]
  B --> C["Collect and sort findings"]
  C --> D["Print report, exit code"]

Each rule is a small function from notebook to a list of findings. New rules do not change the rest of the program.

A finding is a tuple: severity, cell number, rule id, message. The rules we implement:

Id Checks
NB001 execution counts are sequential from top to bottom
NB002 first cell is a Markdown title
NB003 a code cell is longer than 40 lines
NB004 likely secret in source or output
NB005 %pip or !pip install inside the notebook
NB006 code cell has an error output (a stored traceback)

Step 1: a sample notebook with problems

Python Step 1: sample data

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Step 2: helpers

A real notebook stores source as a list of lines or one string, so the helper normalizes it. Rules also need to look at output text.

Python Step 2: helpers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Step 3: the rules

Each rule is a function that takes the notebook and yields findings (severity, cell_number, rule_id, message). Cell numbers start at 1 for human readers.

Python Step 3 and 4: rules plus runner

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The sample notebook trips every rule. Execution counts 3, 1, 2, 5 are out of order, the first cell is not a title, one cell has 45 lines, a token sits in the source, an install line is present and one cell stores a traceback. The exit code is 1 because there is an error-level finding, which is what a CI step needs.

Notice the design: rules are independent generator functions in a list. Adding NB007 means writing one function and appending it.

Step 4: make rules configurable

Teams disagree about line limits and which rules matter. Add a small config dictionary: which rules are enabled, thresholds and severities. In a real tool this lives in a pyproject.toml section such as [tool.nblint].

Python Step 4: configuration

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Step 5: the command-line script (read-only)

On your machine, save the rules in nblint.py and add this entry point. It reads files given on the command line, prints findings in a format editors understand (file:cell:severity) and sets the exit code.

Python
import json, sys

def main(paths):
    worst = 0
    for path in paths:
        with open(path, encoding="utf-8") as fh:
            nb = json.load(fh)
        for sev, cell, rule, msg in lint(nb):
            print(f"{path}:{cell}: {sev}: {rule} {msg}")
            if sev == "error":
                worst = 1
    return worst

if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))
Terminal
python nblint.py notebooks/*.ipynb

Step 6: automate it

Run the linter on every commit with pre-commit:

YAML
# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: nblint
        name: notebook lint
        entry: python nblint.py
        language: system
        files: \.ipynb$

and in CI next to the tests (see testing notebook code). Developers then see findings before the pull request exists.

Extensions to try

  • NB007: imports not at the top of the notebook.
  • NB008: variables like df2, final_v3, or names that are never used.
  • NB009: absolute paths such as C:\Users\me\data.csv, which break on other machines.
  • NB010: outputs larger than 1 MB (embedded images or huge tables).
  • An --fix mode that clears outputs and counts.
  • Output as JSON for a dashboard that tracks quality across a repository.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is a notebook easy to lint?

    The .ipynb format is plain JSON, so any language can load it and inspect it.
  2. 2. Why design each check as a separate function in a list?

    Independent rules are easy to test, enable, disable and extend.
  3. 3. What should a linter do so that CI can fail the build?

    Pipelines treat a non-zero exit status as failure.
  4. 4. Execution counts 3, 1, 2 mean what?

    Sequential counts indicate a clean top-to-bottom run; anything else needs a restart and run all.

Summary

  • A notebook is JSON, so lint rules are small functions over its cells and outputs.
  • Findings carry severity, cell number, rule id and message; the exit code reflects errors.
  • Make rules configurable, then run the linter in pre-commit and CI.
  • Extend it with rules for your team's own standards.

Next: Project: A Parameterized Sales Report Pipeline