gonb

README

GoNB - A Go Notebook Kernel for Jupyter

For a quick start, see the very simple tutorial!

Go is a compiled language, but with very fast compilation, that allows one to use it in a REPL (Read-Eval-Print-Loop) fashion, by inserting a "Compile" step in the middle of the loop -- so it's a Read-Compile-Run-Print-Loop -- while still feeling very interactive.

GoNB leverages that compilation speed to implement a full-featured (at least it's getting there) Jupyter notebook kernel.

It already includes many goodies: contextual help and auto-complete (with gopls), compilation error context (by mousing over), bash command execution, images, html, etc. See the tutorial.

It's been heavily (and successfully) used by the author, but should still be seen as experimental -- if we hear success stories from others we can change this. Reports of issues as well as fixes are always welcome.

There is also a live version in Google's Colab that one can interact with (make a copy first) -- if link doesn't work (Google Drive sharing publicly is odd), download it from github and upload it to Google's Colab.

It also works in VSCode and Github's Codespaces. Just follow the installation below.

Installation

The tutorial explains, but in short:

$ go install github.com/janpfeifer/gonb@latest
$ go install golang.org/x/tools/cmd/goimports@latest
$ go install golang.org/x/tools/gopls@latest
$ gonb --install

Or all in one line that can be copy&pasted:

go install github.com/janpfeifer/gonb@latest && go install golang.org/x/tools/cmd/goimports@latest && go install golang.org/x/tools/gopls@latest && gonb --install

And then (re-)start Jupyter.

In Github's Codespace, if Jupyter is already started, restarting the docker is an easy way to restart Jupyter.

Rich display: HTML, Images, SVG, Videos, manipulating javascript, etc.

GoNB opens a named pipe (set in environment variable GONB_PIPE) that a program can use to directly display any type of HTML content.

For the most cases, one can simply import github.com/janpfeifer/gonb/gonbui: the library offers a convenient API to everything available. Examples of use in the tutorial.

If implementing some new mime type (or some other form of interaction), see kernel/display.go for the protocol details.

TODOs

Contributions are welcome!

• Mac and Windows:
  • Installation.
  • Named-pipe implementation in kernel/pipeexec.go.
• Tracking of lines on generated Go files back to cell, so reported errors are easy to follow. In the meantime the errors can be moused over and will display the lines surrounding them.
• Controllable (per package or file) logging in GoNB code.
• Library to easily store/retrieve calculated content. When doing data analysis so one doesn't need to re-generate some result at a next cell execution. Something like func Save[T any](id string, fn func() (T, error)) T, error that calls fn, and if successful, saves the result before returning it. And the accompanying func Load[T any](id string) T, error and func LoadOrRun[T any](id string, fn func() (T, error)) T, error which will load the result if available or run fn to regenerate it (and then save it).

Implementation

The Jupyter kernel started from gophernotes implementation, but was heavily modified and very little is left. Also, the execution loop and mechanisms are completely different and new: GoNB compiles and executes on-the-fly, instead of using a REPL engine.