Skip to content

feat(notebooks): add shared environment-bootstrap module and drift-check tooling - #65

Merged
petercorke merged 1 commit into
mainfrom
feat/notebook-bootstrap-module
Aug 11, 2026
Merged

petercorke merged 1 commit into
mainfrom
feat/notebook-bootstrap-module

Conversation

@petercorke

Copy link
Copy Markdown
Owner

Summary

  • Adds docs/notebooks/_mvtb_nb_bootstrap.py, a single source of truth for installing the toolbox across local Jupyter, Google Colab, and JupyterLite/Pyodide, replacing the pattern of 13+ notebooks each hand-pasting their own slightly-drifted Colab-install snippet.
  • Adds sync_bootstrap.py (regenerates each notebook's marked bootstrap cell from the template) and clear_outputs.py (pure-stdlib output clearing) — both support --check for CI and explicit file args for the commit hook.
  • Adds .githooks/pre-commit, a plain git hook (not the pre-commit framework — see docs/notebooks/README.md for why) that applies both fixes silently at commit time and re-stages the result.
  • Adds a docs.yml CI step running both scripts in --check mode as the backstop for machines without the hook installed.
  • Adds tests/test_notebook_bootstrap.py covering the generator/clearer logic directly (marker detection, fix vs. check mode, idempotency).

This was prompted by machinevision-toolbox-python 2.2.0 shipping a broken JupyterLite "Try it Now" demo — tqdm was added as a real dependency but never added to the one notebook's hand-maintained micropip install list, and nothing tested it before release.

Not included, deliberately: no notebooks are migrated to use the marker cell yet — that's a follow-up change, so this PR is reviewable as tooling-only.

Test plan

  • pytest tests/test_notebook_bootstrap.py — 10/10 pass
  • ruff check clean on all new files
  • Ran sync_bootstrap.py --check / clear_outputs.py --check against the real docs/notebooks/ — correctly report nothing to do (no notebooks migrated yet)
  • Ran .githooks/pre-commit directly against a real staged commit — confirmed it doesn't touch the 16 existing notebooks it shouldn't
  • Confirmed the generated bootstrap cell compiles under ast.PyCF_ALLOW_TOP_LEVEL_AWAIT (matches how a real Jupyter/IPython kernel executes top-level await in a cell)

🤖 Generated with Claude Code

…eck tooling

machinevision-toolbox-python 2.2.0 shipped a broken JupyterLite "Try it Now"
demo: tqdm was added as a real dependency but never added to the one
notebook's hand-maintained micropip install list, and nothing tested it
before release. More generally, 13 of 16 notebooks each carried their own
slightly-drifted, hand-pasted copy of the Colab-install snippet.

Introduces a single source of truth (_mvtb_nb_bootstrap.py) for installing
the toolbox across local Jupyter, Google Colab, and JupyterLite/Pyodide, a
generator (sync_bootstrap.py) that regenerates each notebook's marked
bootstrap cell from it, and a pure-stdlib output-clearer (clear_outputs.py).
A plain git hook (.githooks/pre-commit, not the pre-commit framework -- see
docs/notebooks/README.md for why) applies both silently at commit time; a
docs.yml CI step is the backstop for machines without the hook installed.

No notebooks are migrated to the marker cell yet -- that's a follow-up
change. This lands the tooling and its tests only.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@codacy-production

Copy link
Copy Markdown

Not up to standards ⛔

🔴 Issues 1 critical · 17 high · 1 medium · 1 minor

Alerts:
⚠ 20 issues (≤ 0 issues of at least minor severity)

Results:
20 new issues

Category Results
Security 1 minor
17 high
1 critical
1 medium

View in Codacy

🟢 Metrics 57 complexity · 4 duplication

Metric Results
Complexity 57
Duplication 4

View in Codacy

NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.

@petercorke
petercorke merged commit 5d562d7 into main Aug 11, 2026
18 of 19 checks passed
@petercorke
petercorke deleted the feat/notebook-bootstrap-module branch October 3, 2026 14:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant