Sequencer Command Line Tools¶

The seqtool meta command¶

The seqtool provides the following subcommands:

run Allows to execute a sequencer script.

draw Generates DAG images of Sequencer scripts.

shell
Starts an interactive CLI which allows to load and run sequencer scripts.

gui
Starts the sequencer GUI

server
Starts the sequencer server

Common command-line options¶

Every seqtool sub-commands supports the following options:

–help
Shows command’s syntax and usage options.

–log-level
Sets the process’ logging level.

The seqtool shell sub command¶

Starts an interactive CLI where the user can submit commands to the sequencer library in order to execute Sequencer scripts.

Supported commands are:

help
Provides a list of commands supported by the CLI. With a parameter, displays the documentation of the given command. e.g.:
 (seq)>> help load

Will display `load`'s command documentation
quit
Stops the shell process.

load
Loads a python module that implements a sequencer script. The module has to be specified as Python would import it. e.g.:
(seq)>> load seq.samples.a
modules
Lists the modules loaded by the Sequencer core.

run
Executes all the Sequencer scripts loaded.

tree
Shows the Sequencer tree, from the modules loaded. Along with the tree structure it displays the node’s serial number needed by some commands.

pause <node_sn>
Allows to mark a node to pause execution. Receives the node serial number as parameter.

resume <node_sn>
A paused script can be resumed with this command. One has to give the node serial number to resume from (the PAUSED node).

skip <node_sn>
Allows to mark a node to skip from execution. Receives the node serial number as parameter.

retry
Allows to retry the execution of a failed node.

continue
When the execution of a script is cancelled, due to an error. One can resume execution from the next available node with the continue command.

flip <skip|pause> <node_sn>
Flips the pause or skip flag of a node. Must give the flag to flip and the node’s serial number:
(seq)>> flip pause 3
(seq)>> flip skip 4

Upon start, a session directory is created, below the /tmp directory as seq_session_<pid>. The following log files can be found there:

seq_user.log
User’s logging and very basic script execution info.

seq.log
Internal shell’s logging. Useful for debugging the sequencer itself.

kernel.log
Internal sequencer logging, state changes, execution chain, etc. Useful for debugging the sequencer itself.

Basic Usage¶

Command line options¶

The seqtool server command accepts the following command line options:

–address (as [HOST:]PORT) where to listen for connections

–redis (as [HOST:]PORT) where is the REDIS server

Loading sequences¶

At the prompt one can send commands to the shell. The following will load a sequence module (if found):

$ seqtool shell                                                                                                              1 ↵
MAIN ...
INFO:(seqsh.__init__): shell started: /tmp/seq_session_13369/seq.log
(seq)>> INFO:(seqsh.do_init): initialize shell- False
INFO:(seqsh.do_init): dummy redis connection
INFO:(seqsh.start_seq_core): Starting seq kernel
INFO:(seqsh.start_seq_core): connected to child process

(seq)>> load seq.samples.a

One can examine the structure and state of the loaded script with the nodes command:

(seq)>> nodes
(seq)>> (Core)> A-- (5) begin NOT_STARTED
A-- (8) end NOT_STARTED
S+- (2) Sequence NOT_STARTED
    A-- (6) begin NOT_STARTED
    A-- (3) a NOT_STARTED
    A-- (4) b NOT_STARTED
    A-- (7) end NOT_STARTED

To decipher the above ouput, every line is formatted as:

Lines are indented according to its level in the DAG. Every node in the DAG is prefixed by its type, as follows:

A
This for Actions.

S
Refers to a Sequence.

P
Inidicates a Parallel sequence.

L
To indicate a Loop.

The number in parenthesis are the node’s serial number which some commands needs as a parameter.

Sequencer scripts are executed with the run command.

Executing Sequences¶

The run command executes the loaded sequences:

seq)>> run
(seq)>> INFO:seq.samples.a:a
INFO:seq.samples.a:B

The state of the script can be observed at any time with the nodes command:

A-- (5) begin FINISHED
A-- (8) end FINISHED
S+- (2) Sequence FINISHED
    A-- (6) begin FINISHED
    A-- (3) a FINISHED
    A-- (4) b FINISHED
    A-- (7) end FINISHED

Skipping Nodes¶

A node can be skipped from execution with the skip command and indicating the node number one desires ti skip

(seq)>> skip 3
(seq)>> run
INFO:seq.samples.a:B

The nodes command after running the sequence looks as follows:

seq)>> nodes
(Core)> A-- (5) begin FINISHED
A-- (8) end FINISHED
S+- (2) Sequence FINISHED
    A-- (6) begin FINISHED
    A-- (3) a FINISHED|SKIP|RT.SKIP
    A-- (4) b FINISHED
    A-- (7) end FINISHED

Node (3) is marked as FINISHED and SKIP (was skipped). The RT.SKIP text indicates the runtime flag SKIP is active.

In the example above all nodes are FINISHED, no error was detected.

Pause a script¶

The pause commands requires the node number where to pause. Pausing on node (4) on the script we are working on activates the pause runtime flag on said node:

(seq)>> pause 4
(seq)>> nodes
(Core)> A-- (5) begin FINISHED
A-- (8) end FINISHED
S+- (2) Sequence FINISHED
    A-- (6) begin FINISHED
    A-- (3) a FINISHED|SKIP|RT.SKIP
    A-- (4) b FINISHED|RT.PAUSE
    A-- (7) end FINISHED

Executing the script will pause on node (4). It will look as follows (nodes command ouput redacted)

A-- (4) b PAUSED|RT.PAUSE

In order to resume execution just issue the resume command, with the node number:

(seq)>> resume 4
INFO:seq.samples.a:B
(seq)>> nodes
(Core)> A-- (5) begin FINISHED
A-- (8) end FINISHED
S+- (2) Sequence FINISHED
    A-- (6) begin FINISHED
    A-- (3) a FINISHED|SKIP|RT.SKIP
    A-- (4) b FINISHED|RT.PAUSE
    A-- (7) end FINISHED
(seq)>>

To clean the runtime flags use flip command, in the example nodes (3) and (4) are back to normal:

(seq)>> flip skip 3
(seq)>> flip pause 4

Error Handling¶

When a Sequencer Item generates an error, i.e. raises a Python exception, then the whole sequence is CANCELLED, and the offending node is marked as FINISHED|ERROR. The following example shows such a sequence:

(seq)>>
(seq)>> load seq.samples.test_err
(seq)>> (Core)> NODES: ['begin___seq_ROOT___qVJL9XVXR3', 'Sequence_3j7VG0YWmM', 'end___seq_ROOT___qVJL9XVXR3']
NODES: ['begin_Sequence_3j7VG0YWmM', 'Tpl.a_3jxvx', 'b', 'Tpl.c_1wWmj', 'end_Sequence_3j7VG0YWmM']

(seq)>> run
(seq)>> SEQRUN!, catch exception: Sequence

    ........

File "/home/eeltdev/introot/lib/python3.7/site-packages/seq/samples/test_err.py", line 28, in b
    x = 1 / 0
ZeroDivisionError: division by zero

The exception stacktrace is shown clearly indicating the offending method and line where the exception occurrs (division by zero). The output of nodes command:

(seq)>> nodes
(seq)>> (Core)> A-- (7) begin FINISHED
A-- (10) end CANCELLED
S+- (6) Sequence CANCELLED|ERROR
    A-- (8) begin FINISHED
    A-- (3) Tpl.a FINISHED
    A-- (4) Tpl.b FINISHED|ERROR
    A-- (5) Tpl.c CANCELLED
    A-- (9) end CANCELLED

Where the node b has state FINISHED|ERROR.

One the can retry the failed node or continue from the next unfinished: node.

seqtool run¶

Executes the Sequencer scripts given in the command line. Usage:

$ seqtool run --help
Usage: seqtool run [OPTIONS] [MODULES]...

Options:
  --log-level TEXT
  --help            Show this message and exit.

It is non-interactive so it breaks at the slightest provocation. An example:

# specify two modules to execute in sequence
$ seqtool run seq.samples.a seq.samples.b

log files¶

The seqtool run commands creates the following log files at user’s current directory.

seq_user.log
User’s logging and very basic script execution info.

seqrun_<pid>.log
Internal sequencer logging, state changes, execution chain, etc. Useful for debugging the sequencer itself.

seqtool draw¶

Draws the graph representation of the Sequencer scripts given in the command line. Usage:

$ seqtool draw --help
Usage: seqtool draw [OPTIONS] OUTPUT [MODULES]...

The OUTPUT argument is the generated diagram. It will
automatically generate PNG, GIF, JPG or .dot files depending on
the filename given.


Options:
  --log-level TEXT
  --help            Show this message and exit.

It is non-interactive so it breaks at the slightes provocation. An example:

# generates a .dot diagram of the given module
$ seqtool draw a.dot seq.samples.a

Create a .dot file from seq.samples.a python module. The following example generates a JPEG image from seq.samples.b module:

# generates a .jpg image of the given module
$ seqtool draw a.png seq.samples.b