gonb

README

GoNB, A Modern Go Kernel for Jupyter 📓Notebooks📓

For a quick start, see the tutorial 🧭

✨ Highlights:

• Auto-complete and contextual help while coding.
• Rich content display: HTML, markdown (with latex), images, javascript, svg, videos, etc.
  • Widgets (sliders, buttons) support: interact using HTML elements. Create your own widgets!
  • Plotly integration using go-plotly (see example in tutorial)
  • Apache ECharts integration using gonb-echarts and go-echarts: see examples
• Uses standard Go compiler: 100% compatibility with projects, even those using CGO. It also supports arbitrary Go compilation flags to be used when executing the cells.
• Faster execution than interpreted Go, used in other similar kernels -- at the cost of imperceptible increased start up, since each cell is compiled.
• Supported by Jupytext: it allows one to write the notebook as a normal. Go file, and use Jupytext to convert to a notebook (with markdown support, etc). See example.
• Run cell's Test* and Benchmark* functions with go test, simply adding %test to cell.
• Support for go.mod and go.work, to allow local development. Including importing specific versions of libraries.
• Debug using gdlv, a GUI for the delve debugger (see %help).
• Shell command executions with ! -- handy at times, for instance to install packages.
• Reported to work with Github Codespace, VSCode, Binder, Google's Colab, etc.
• Very well documented and supported.
• Great for data-science, testing, writing reports, live demos, etc.
• Includes a pre-built docker, that includes JupyterLab and GoNB, that can be used to easily try it out. Alternatively, there is a Google's Colab, that bootstraps GoNB and can be used online.
• Online help and much more, see %help.
• Compile and execute the Go code as WASM: allows one to do interactive widgets in notebooks. See %wasm (EXPERIMENTAL).

👁️‍🗨️ Examples:

Auto-complete and Contextual Help

Flowers Diffusion Model Demo

https://github.com/janpfeifer/gonb/assets/7460115/f1187dad-4c10-4d21-a73e-9090019680ae

Sine Plot Connected to Slider

(See full code in the tutorial)

Example Screenshotting Wikipedia

🌱 Introduction

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. As a side benefit it works with packages that use CGO — although it won't parse C code in the cells, so it can't be used as a C kernel.

It already includes many goodies: cache between cell of results, 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 used by the author (in developing GoMLX, a machine learning framework for Go), 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 the link doesn't work (Google Drive sharing publicly is odd), download it from GitHub and upload it to Google's Colab.

Finally, because it's compiled and not interpreted, it has a slightly different "semantic" than the Python kernels. It's highly recommended quickly browsing through the tutorial.

📦 Installation

Only for Linux and macOS. In Windows, it works in WSL or inside a Docker

🐳 Docker

GoNB offers a pre-built docker, that includes JupyterLab and GoNB. To use it, go to a directory that you want to make available to the Jupyter notebook (your home directory, or a directory where to store the notebook files). It will be mounted on the host/ subdirectory in JupyterLab.

To start it:

docker pull janpfeifer/gonb_jupyterlab:latest
docker run -it --rm -p 8888:8888 -v "${PWD}":/notebooks janpfeifer/gonb_jupyterlab:latest

Then copy&paste the URL that it outputs in your browser.

Note: The docker allows for customization by running an arbitrary script at start up as root, which allows one to install any planned dependencies. See docker.md for details.

Linux and macOS Installation Using Standard Go Tools

The official tutorial on how to install go programs here -- it is pretty simple, go maintains a GOBIN directory (that you can set) and go install will compile programs and put it there. You should add the GOBIN directory to your PATH (the default list of directories to search for executables).

You need to install (if not yet there), GoNB, goimports and gopls (for auto-complete), and then run gonb --install. To install them in your GOBIN directory:

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

And if GOBIN is in your PATH, run the following to install GoNB as a kernel in the Jupyter configuration (works for both JupyterLab and Jupyter Notebook).

gonb --install

And then (re-)start Jupyter (if it is already running).

In GitHub's Codespace, if Jupyter is already started, restart the docker — it will also restart Jupyter.

Note: for go.work to be parsed correctly for auto-complete, you need gopls version greater or equal to v0.12.4 (or at least v0.12.0?). You can check it with gopls version.

Windows

The recommendation is to use WSL (Windows Subsystem for Linux) or WSL2, and run Jupyter and the GoNB kernel in the Linux/WSL environment. Install there as if it were in a linux machine.

A pure Windows installation is not supported at this time — but contributions to add support for it would be welcome :)

🤔 FAQ

• Is there are reference documentation ?
  • There is a help (run %help in a cell) and a tutorial, which is kept up-to-date and is comprehensive -- it includes every GoNB feature.
  • The libraries that are used or UI, Widgets and manipulating the DOM in the notebook's browser, are all under the package gonbui. They are described in the tutorial, but also documented in pkg.go.dev.
• What is the %% symbol seen everywhere?
  • It is a special commands for GoNB that means "insert a func main {...} here".
• Go error handling is verbose and annoying for things interactive as a notebook. Can we do something ?
  • Yes! Error handling for small scripts in a notebook can get in the way at times. There are various solutions to this. Often folks create a series of Must() functions, or simply use this trivial must package.

📝 TODOs

Contributions are welcome!

• Windows version:
  • Installation.
  • Named-pipe implementation in kernel/pipeexec.go.

💖 Thanks

• Go
• Jupyter, what an awesome project.
• gophernotes, from which this is a highly modified fork, little from the original code exists.
• The Go gopher logo (internal/kernel) used in the installation of the Jupyter kernel was designed by Renee French (http://reneefrench.blogspot.com/), see Creative Commons 3.0 Attributions license in Wikimedia.

🤝 Contributing

Contributions are very welcome. The code is generally well documented -- not always, but mostly. There are a also a couple of guides worth reading if contributing in the docs/ subdirectory.

There are two parts of the project:

1. The kernel itself: that builds the binary package. Most subpackages are under internal/.
2. The UI library in the packages under github.com/janpfeifer/gonb/gonbui.

🌟 Star History