Sequencer Command Line Tools¶

The seq meta command¶

The seq 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

The seq 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

seq run¶

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

$ seq run -h
Usage: seq run [OPTIONS] [MODULES]...

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

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

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

seq draw¶

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

$ seq run -h
Usage: seq 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
$ seq draw a.dot seq.samples.a

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

Basic Usage¶

Command line options¶

The seq 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 server. The following will load a sequence module (if found):

seq)>>
(seq)>> load seq.samples.a
(seq)>> (Core)> NODES: ['begin___seq_ROOT___gx13qA8w3Y', 'Sequence_YQoKAP6j2p', 'end___seq_ROOT___gx13qA8w3Y']
NODES: ['begin_Sequence_YQoKAP6j2p', 'a_681PO', 'b_WjBDo', 'end_Sequence_YQoKAP6j2p']

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 window 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.