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 (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.
Functions ¶
This section is empty.
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶ added in v0.10.0
WithStaticInput configures the executor to run withe given fixed input.
This conflicts with Executor.WithInputs and Executor.WithPassword.
func (*Executor) WithStderr ¶
WithStderr configures piping of stderr to the given `io.Writer`.