jpyexec

Documentation

Overview

Package jpyexec handles the execution of programs piping the output to Jupyter.

Presumably Go programs compiled from the notebook's cells contents, but could be anything.

It optionally supports creating two named pipes (one in each direction) that allows:

* Display of rich content: HTML, image, SVG, markdown, etc. * Widgets communication back-and-forth with the front-end.

Index

• Constants
• Variables
• type CommsHandler
• type Executor
  • func New(msg kernel.Message, command string, args ...string) *Executor
  • func (exec *Executor) Exec() error
  • func (exec *Executor) ExecutionCount(c int) *Executor
  • func (exec *Executor) InDir(dir string) *Executor
  • func (exec *Executor) UseNamedPipes(commsHandler CommsHandler) *Executor
  • func (exec *Executor) WithInputs(millisecondsWait int) *Executor
  • func (exec *Executor) WithPassword(millisecondsWait int) *Executor
  • func (exec *Executor) WithStaticInput(stdinContent []byte) *Executor
  • func (exec *Executor) WithStderr(stderrWriter io.Writer) *Executor
  • func (exec *Executor) WithStdout(stdoutWriter io.Writer) *Executor

Constants

const PipeWriterFifoBufferSize = 128

PipeWriterFifoBufferSize is the number of CommValue messages that can be buffered when writing to the named pipe before dropping.

Variables

var WaitToKill = 5 * time.Second

WaitToKill is the to wait after an interrupt signal, before killing the process.

Types

type CommsHandler

type CommsHandler interface {
	// ProgramStart is called when the program execution is about to start.
	// If program start failed (e.g.: during creation of pipes), ProgramStart may not be called,
	// and yet ProgramFinished is called.
	ProgramStart(exec *Executor)

	// ProgramFinished is called when the program execution finishes.
	// Notice this may be called even if ProgramStart has not been called, if the execution
	// failed during the creation of the various pipes.
	ProgramFinished()

	// ProgramSendValueRequest is called when the program requests a value to be sent to an address.
	ProgramSendValueRequest(address string, value any)

	// ProgramReadValueRequest handler.
	ProgramReadValueRequest(address string)

	// ProgramSubscribeRequest handler.
	ProgramSubscribeRequest(address string)

	// ProgramUnsubscribeRequest handler.
	ProgramUnsubscribeRequest(address string)
}

CommsHandler interface is used if Executor.UseNamedPipes is called, and a CommsHandler is provided.

It is assumed there is at most one program being executed at a time. GoNB will never execute two cells simultaneously.

type Executor

type Executor struct {
	// Configuration, before execution
	Msg kernel.Message

	// PipeWriterFifo is the channel used to send message updates to pipeWriter.
	// It has a fixed buffer size: if the buffer is full, messages are dropped -- this can only
	// happen if, for instance, the program doesn't interact/open the pipe.
	//
	// Currently, it is assumed that it will be used by the CommsHandler.
	PipeWriterFifo chan *protocol.CommValue
	// contains filtered or unexported fields
}

Executor holds the configuration and state when executing a command that is piped to Jupyter. Use New to create it.

func New

func New(msg kernel.Message, command string, args ...string) *Executor

New creates an executor for the given command plus arguments, and pipe the output to Jupyter stdout and stderr streams connected to Msg.

It returns a configuration/state Executor object, that can be further configured. Call ProgramExecutor when the configuration is isDone to actually execute the command.

See `UseNamedPipes` to add support for rich data (HTML, PNG, SVG, Markdown, etc.) and widgets. See `gonb/gonbui` and `gonb/gonbui/widgets`.

func (*Executor) Exec

func (exec *Executor) Exec() error

Exec executes the configured New configuration.

It returns an error if it failed to execute or created the pipes -- but not if the executed program returns an error for any reason.

func (*Executor) ExecutionCount

func (exec *Executor) ExecutionCount(c int) *Executor

ExecutionCount sets the "execution_count" updated field when replying to an "execute_request" message. If set it publishes data as "execute_result" messages, as opposed to "display_data".

For the most practical purposes, they work the same. But since the protocol seems to distinguish them, there is an option to set it.

func (*Executor) InDir

func (exec *Executor) InDir(dir string) *Executor

InDir configures the Executor to execute within the given directory. Returns the modified builder.

func (*Executor) UseNamedPipes

func (exec *Executor) UseNamedPipes(commsHandler CommsHandler) *Executor

UseNamedPipes enables the creation of the side named pipes that add support for rich data (HTML, PNG, SVG, Markdown, etc.) and widgets.

commsHandler is called to handle Comms request from the program. If left as nil, comms requests are simply ignored.

See `gonb/gonbui` and `gonb/gonbui/widgets`.

func (*Executor) WithInputs

func (exec *Executor) WithInputs(millisecondsWait int) *Executor

WithInputs configures the Executor to also plumb the input from Jupyter input prompt.

The prompt is displayed after millisecondsWait: so if the program exits quickly, nothing is displayed.

If running Go programs, it's better to use widgets for input. Jupyter input mechanism is cumbersome.

func (*Executor) WithPassword

func (exec *Executor) WithPassword(millisecondsWait int) *Executor

WithPassword configures the Executor to also plumb the input from Jupyter password input (hidden).

The prompt is displayed after millisecondsWait: so if the program exits quickly, nothing is displayed.

If running Go programs, it's better to use widgets for input. Jupyter input mechanism is cumbersome.

func (*Executor) WithStaticInput

func (exec *Executor) WithStaticInput(stdinContent []byte) *Executor

WithStaticInput configures the executor to run withe given fixed input.

This conflicts with Executor.WithInputs and Executor.WithPassword.

func (*Executor) WithStderr

func (exec *Executor) WithStderr(stderrWriter io.Writer) *Executor

WithStderr configures piping of stderr to the given `io.Writer`.

func (*Executor) WithStdout

func (exec *Executor) WithStdout(stdoutWriter io.Writer) *Executor

WithStdout configures piping of stderr to the given `io.Writer`.