Standard Tools

STOO (Standard Tools) provides a small set of Python client-side tools for the application life-cycle management of CII/MAL based ELT components. It comprises the asynchronous shell (acli), the service-registry lookup tools (geturi, getstatus) and the supporting stooUtils library.

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. ifw.fcf.clib.devmgr_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 ifw.fcf.clib.devmgr_commands
        --class_name FcfCommands
        --class_args zpb.rr://127.0.0.1:59201
        --prompt "fcfSh> "

$ acli  --module ifw.core.acli.std_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 ifw.fcf.clib.devmgr_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.

Service URI Lookup - geturi

The geturi tool resolves the MAL request/response URI of a registered service from the service registry (Consul or Nomad). It is the command-line front-end to the stooUtils registry clients.

Usage

Usage: geturi [OPTIONS] SERVICE_NAME

    Get URI for a service

Options:
  --namespace TEXT           Namespace for the service (default: the
                             NOMAD_NAMESPACE environment variable, else
                             "default").
  --registry-id [consul|nomad]
                             Registry to query. Defaults to the
                             NOMAD_SERVICE_REGISTRATION environment
                             variable, else "consul".
  --help                     Show this message and exit.

The resolved URI is printed to stdout, e.g.:

$ geturi myDeviceServer
zpb.rr://127.0.0.1:59201/

Application Status - getstatus

The getstatus tool looks up a service via Consul and queries its standard state through the CII/MAL StdCmds interface, printing the resulting state.

Usage

Usage: getstatus [OPTIONS]

    Options:
      --name TEXT      Registered name in Consul.
      --timeout INTEGER  Timeout for CII MAL requests in seconds (default 3).
      --help           Show this message and exit.

Example:

$ getstatus --name myDeviceServer
zpb.rr://127.0.0.1:59201/StdCmds
Operational

Registry Utilities - stooUtils

Python import statement: “import ifw.core.stooUtils”.

The stooUtils package provides thin client wrappers used by geturi and getstatus to resolve service URIs from a service registry:

“ifw.core.stooUtils.consul”: ConsulClient - resolve service URIs from Consul (honours the CONSUL_ADDR environment variable).
“ifw.core.stooUtils.nomad”: NomadClient - resolve service URIs from the Nomad service registry.