gonbui

README

GoNBUI

GoNB is a Jupyter notebook kernel able to run Go code.

gonbui package allows any go code ran in GoNB to easily display various type of rich content in the notebook. Currently supported:

• HTML: An arbitrary HTML block, and it also allows updates to a block (e.g.: updates to some ongoing processing).
• Images: Any given Go image (automatically rendered as PNG); a PNG file content; SVG.
• Javascript: To be run in the Notebook.
• Input request from the notebook.

More (sound, video, etc.) can be quite easily added as well, expect the list to grow.

Documentation

Overview

Package gonbui provides tools to interact with the front-end (the notebook) using HTML and other rich-data.

In its simplest form, simply use `DisplayHtml` to display HTML content. But there is much more nuance and powerful types of interactions (including support for widgets, see the `widget` sup-package). Check out the [tutorial]() for details.

If using the rich data content, consider adding the following to your `main()` function:

defer gonbui.Sync()

This guarantees that no in-transit display content get left behind when a program exits.

Error Handling in Gonbui:

Gonbui involves communication between several components: the code execution environment, the Jupyter kernel, the Jupyter server, and the browser. This communication is asynchronous and errors may occur at various points.

Gonbui employs a simplified error handling approach:

• Global Error State: A single global error state is maintained. While not recoverable, errors are rare. You can check this state using the `Error` function.
• Logging: All errors are logged. However, if communication is broken, logs might not reach the browser. Check the Jupyter (and potentially Gonbui) logs in such cases.

This approach prioritizes simplicity over transactional error handling, acknowledging the challenges of maintaining consistency across asynchronous components.

Index

• Variables
• func DisplayHTML(html string)
• func DisplayHTMLF(htmlFormat string, args ...any)
• func DisplayHtml(html string)
• func DisplayHtmlf(htmlFormat string, args ...any)
• func DisplayImage(image image.Image) error
• func DisplayMarkdown(markdown string)
• func DisplayPNG(png []byte)
• func DisplayPng(png []byte)
• func DisplaySVG(svg string)
• func DisplaySvg(svg string)
• func EmbedImageAsPNGSrc(img image.Image) (string, error)
• func Error() error
• func Logf(format string, args ...any)
• func Open() error
• func RequestInput(prompt string, password bool)
• func ScriptJavascript(js string)
• func SendData(data *protocol.DisplayData)
• func Sync()
• func UniqueID() string
• func UniqueId() string
• func UpdateHTML(id, html string)
• func UpdateHtml(id, html string)
• func UpdateMarkdown(id, markdown string)

Variables

var Debug bool

var (
	// IsNotebook indicates whether the execution was started by a GoNB kernel.
	IsNotebook bool
)

var OnCommValueUpdate func(valueMsg *protocol.CommValue)

OnCommValueUpdate handler and dispatcher of value updates.

Internal use only -- used by `gonb/gonbui/comms`.

Functions

func DisplayHTML

func DisplayHTML(html string)

DisplayHTML will display the given HTML in the notebook, as the output of the cell being executed.

func DisplayHTMLF

func DisplayHTMLF(htmlFormat string, args ...any)

DisplayHTMLF is similar to DisplayHTML, but it takes a format string and its args which are passed to fmt.Sprintf.

func DisplayHtml

func DisplayHtml(html string)

DisplayHtml is an alias to DisplayHTML.

func DisplayHtmlf

func DisplayHtmlf(htmlFormat string, args ...any)

DisplayHtmlf is an alias to DisplayHTMLF.

func DisplayImage

func DisplayImage(image image.Image) error

DisplayImage displays the given image, by converting it to PNG first. It returns an error if it fails to encode to the image to PNG.

func DisplayMarkdown

func DisplayMarkdown(markdown string)

DisplayMarkdown will display the given markdown content in the notebook, as the output of the cell being executed. This also renders math formulas using latex, use `$x^2$` for formulas inlined in text, or double "$" for formulas in a separate line -- e.g.: `$$f(x) = \int_{-\infty}^{\infty} e^{-x^2} dx$$`.

func DisplayPNG

func DisplayPNG(png []byte)

DisplayPNG is an alias for DisplayPng. Deprecated: use DisplayPng instead.

func DisplayPng

func DisplayPng(png []byte)

DisplayPng displays the given PNG, given as raw bytes.

func DisplaySVG

func DisplaySVG(svg string)

DisplaySVG is an alias for DisplaySvg. Deprecated: use DisplaySvg instead.

func DisplaySvg

func DisplaySvg(svg string)

func EmbedImageAsPNGSrc

func EmbedImageAsPNGSrc(img image.Image) (string, error)

EmbedImageAsPNGSrc returns a string that can be used as in an HTML <img> tag, as its source (it's `src` field). This simplifies embedding an image in HTML without requiring separate files. It embeds it as a PNG file base64 encoded.

func Error

func Error() error

Error returns the error that triggered failure on the communication with GoNB. It returns nil if there were no errors.

It can be tested as a health check.

Error Handling in Gonbui:

Gonbui involves communication between several components: the code execution environment, the Jupyter kernel, the Jupyter server, and the browser. This communication is asynchronous and errors may occur at various points.

Gonbui employs a simplified error handling approach:

• Global Error State: A single global error state is maintained. While not recoverable, errors are rare. You can check this state using the `Error` function.
• Logging: All errors are logged. However, if communication is broken, logs might not reach the browser. Check the Jupyter (and potentially Gonbui) logs in such cases.

This approach prioritizes simplicity over transactional error handling, acknowledging the challenges of maintaining consistency across asynchronous components.

func Logf

func Logf(format string, args ...any)

Logf is used to log debugging messages for the gonbui library. It is enabled by setting the global Debug to true.

Usually only useful for those developing new widgets and the like.

func Open

func Open() error

Open pipes used to communicate to GoNB (and through it, to the front-end). This can be called every time, if connections are already opened, it does nothing.

Users don't need to use this directly, since this is called every time by all other functions.

Returns nil if succeeded (or if connections were already opened).

func RequestInput

func RequestInput(prompt string, password bool)

RequestInput from the Jupyter notebook. It triggers the opening of a small text field in the cell output area where the user can type something. Whatever the user writes is written to the stdin of cell program -- and can be read, for instance, with `fmt.Scanf`.

Args:

• prompt: string displayed in front of the field to be entered. Leave empty ("") if not needed.
• password: if whatever the user is typing is not to be displayed.

func ScriptJavascript

func ScriptJavascript(js string)

ScriptJavascript executes the given Javascript script in the Notebook.

Errors in javascript parsing are sent by Jupyter Server to the stderr -- as opposed to showing to the browser console, which may be harder to debug.

Also, like with DisplayHtml, each execution creates a new `<div>` block in the output area. Even if empty, it uses up a bit of vertical space (Jupyter Notebook thing).

If these are an issue, consider using TransientJavascript, which uses a transient area to execute the Javascript, which is re-used for every execution.

Note: `text/javascript` mime-type (protocol.MIMETextJavascript) is not supported by VSCode, it's displayed as text. So using this won't work in VSCode. Consider instead using DisplayHtml, and wrapping the `js` string with `("<scrip>%s</script>", js)`.

func SendData

func SendData(data *protocol.DisplayData)

SendData to be displayed in the connected Notebook.

This is a lower level function, that most end users won't need to use, instead look for the other functions DisplayHtml, DisplayMarkdown, etc.

But if you are testing new types of MIME types, this is the way to result messages ("execute_result" message type) directly to the front-end.

func Sync

func Sync()

Sync synchronizes with GoNB, and can be used to make sure all pending output has been sent.

This can be used at the end of a program to make sure that everything that is in the pipe to be displayed is fully displayed (flushed) before a program exits.

func UniqueID

func UniqueID() string

UniqueID returns a newly created unique id. UniqueID is an alias for UniqueId.

Deprecated: Use UniqueId instead.

func UniqueId

func UniqueId() string

UniqueId returns newly created unique id. It can be used for instance with UpdateHtml.

func UpdateHTML

func UpdateHTML(id, html string)

UpdateHTML displays the given HTML in the notebook on an output block with the given `id`: the block identified by 'id' is created automatically the first time this function is called, and simply updated thereafter.

The contents of these output blocks are considered transient, and intended to live only during a kernel session.

Usage example:

counterDisplayId := "counter_"+gonbui.UniqueId()
for ii := 0; ii < 10; ii++ {
	gonbui.UpdateHtml(counterDisplayId, fmt.Sprintf("Count: <b>%d</b>\n", ii))
}
gonbui.UpdateHtml(counterDisplayId, "")  // Erase transient block.
gonbui.DisplayHtml(fmt.Sprintf("Count: <b>%d</b>\n", ii))  // Show on final block.

Notice that the value of `counterDisplayId` is not a DOM element id -- unfortunately. If you want a `<div>` that you can manipulate with the [dom] package, create an empty `<div id=%q></div>` with another unique id (see gonbui.UniqueID) and use that instead.

func UpdateHtml

func UpdateHtml(id, html string)

UpdateHtml is an alias for UpdateHTML. Deprecated: use UpdateHTML instead, it's the same.

func UpdateMarkdown

func UpdateMarkdown(id, markdown string)

UpdateMarkdown updates the contents of the output identified by id: the block identified by 'id' is created automatically the first time this function is called, and simply updated thereafter.

The contents of these output blocks are considered transient, and intended to live only during a kernel session.

See example in UpdateHtml, just instead this used Markdown content.