Notebook Tidy

CLI to clean Jupyter notebooks and extract reusable code into modules. Built with Typer, nbformat, and YAML-configurable rules.

Install (editable)

python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
pre-commit install

Usage

notebook-tidy path/to/notebook.ipynb --output tidy.ipynb --config notebook-tidy.yaml
# plan only
notebook-tidy path/to/notebook.ipynb --dry-run --json
# write plan to file alongside output
notebook-tidy path/to/notebook.ipynb --plan
# preserve outputs/execution counts
notebook-tidy path/to/notebook.ipynb --keep-outputs
# strip only (skip reorder & extract)
notebook-tidy path/to/notebook.ipynb --strip-only
# emit starter config template
notebook-tidy config-template > notebook-tidy.yaml
# show version
notebook-tidy --version

• Strips execution counts and outputs.
• Reorders cells based on tags you define.
• Extracts tagged code cells into Python modules under src/.
• Optional: remove extracted cells (optionally scoped to tags) and run Black on generated modules.
• Optional: write a JSON plan/result file for CI or inspection.
• Optional: insert markdown placeholders when code cells are extracted.

Development quick commands

make fmt       # ruff format + black
make lint      # ruff check + black --check
make test      # pytest quick run
make cov       # pytest with coverage
make precommit # run all pre-commit hooks locally

See notebook-tidy.yaml for a starter configuration.