Standard Tools¶

Asynchronous Shell¶

Description¶

The acli utility is a simple shell based on the Prompt Toolkit whose purpose is to simplify the implementation of interactive CLI for ELT components based on CII. It uses the asyncio event loop to take advantage of concurrency model.

As it is based on the Prompt Toolkit, it provides built-in shell completion and history capabilities.

The shell itself does not have any dependency on ELT libraries so it could also be used for general purposes tasks.

Despite the fact that it uses the asyncio event loop, commands which are not implementing coroutines can also be used but they may block the shell.

Usage¶

Usage: acli [OPTIONS]

    Asynchronous shell for interactive communication with servers

Options:
  --module TEXT                   python module implementing the commands
                                  e.g.fcfclib.fcf_commands
  --class_name TEXT               python class implementing the commands e.g.
                                  FcfCommands
  --class_args TEXT               class arguments separated by commas
  --prompt TEXT                   prompt shell
  --history_file TEXT             shell history file
  --log_level [ERROR|INFO|DEBUG]  debugging level
  --help                          Show this message and exit.

Example:

$ acli  --module fcfclib.fcf_commands
        --class_name FcfCommands
        --class_args zpb.rr://127.0.0.1:59201
        --prompt "fcfSh> "

$ acli  --module acli.std_sync_commands
    --class_name StdSyncCommands
    --class_args zpb.rr://127.0.0.1:59201
    --prompt "Sh> "

Shell Interactions¶

The acli falls under the category of a REPL application (Read-Evaluate-Print-Loop back) but with the caveat that is asynchronous so the printing of the results could be after the loop back.

The input from the shell is passed to the Command class. The fist input from the command line is interpreted as method of the class to be invoked, and the subsequent strings as its arguments. Multiple arguments shall be separated by commas.

For instance, for the following input:

sh> setloglevel ERROR,mylogger

The acli shell will interpret a command “setloglevel” with two arguments: ERROR and mylogger. The shell will try to invoke, when feasible, asynchronously this command (method) of the command class. The result of the execution will be printed in the stdout when available.

Methods Metadata¶

The shell obtains the information about the class methods at run-time to be able to provide the help information and the command completion. This includes the method signature and the online help which is obtained with the python library inspect and docstring_parser.

Examples¶

The following examples assume using the shell for the FCF Command class.

$ acli --module fcfclib.fcf_commands
        --class_name FcfCommands
        --class_args zpb.rr://127.0.0.1:59201
        --prompt "fcfSh> "

Invoke a help method for a commad¶

fcfSh> help move
Short description: Move a motor to a target position.

Command usage: move  name, pos, type='abs', unit='uu', aux_motor=''

where:
        <name(str)>:    Name of the device (supported types: motors, drots and ADCs)
        <pos(float)>:   Target position where to move
        [type(str)]:    Type of movement - absolute(abs) or relative(rel))
        [unit(str)]:    User units(uu) or encoders(enc)
        [aux_motor(str)]:       Auxiliar motor name, only valid for ADCs
reply> = None

Sequence of commands¶

Commands can be executed in sequence using character ‘;’. This is similar to the way Linux commands can be executed.

fcfSh> init;enable
reply> = OK init completed.

reply> = OK enable completed.

fcfSh>

fcfSh> switch_on lamp1,50;devstatus lamp1
reply> = OK setup completed.

reply> = ['lamp1.simulated = true', 'lamp1.lcs.state = Operational','lamp1.lcs.substate = On', 'lamp1.lcs.intensity = 10.000000', '', 'OK']

fcfSh>

Stopping the Shell¶

The shell can be stopped by pressing Ctrl-D.