cli_utils

Utility decorators and functions to used with Click library to generate instrument CLIs.

Contains @with_instrument and @print_output decorators, as well as verbosity conversion function and MonitoringLogger broadcaster class.

Functions

`print_output`(function[, pretty_dict])	Decorator for CLI function which prints return value of function after completion.
`verbosity`(level)	Convert numerical verbosity level to logging level.
`with_instrument`(function)	Wraps decorated function in with <instrument>: ... statement.

Classes

`InContextObjectField`(choices, field[, ...])
`MonitoringLogger`(*writers)	Multiple output logging interface.

print_output

icicle.cli_utils.print_output(function, pretty_dict=True)

Decorator for CLI function which prints return value of function after completion.

Also wraps function in try: … except SCPIInstrument.ValidationError, Instrument.ChannelError, NotImplementedError statement to catch errors of these types and suppress traceback in these cases.

Note

DECORATOR

verbosity

icicle.cli_utils.verbosity(level)

Convert numerical verbosity level to logging level.

0 => WARNING 1 => INFO 2 => DEBUG

with_instrument

icicle.cli_utils.with_instrument(function)

Wraps decorated function in with <instrument>: … statement.

Decorator for CLI function which wraps function in with <instrument>: … statement to enter and exit instrument context before and after function is executed, respectively.

Note

DECORATOR

InContextObjectField

class icicle.cli_utils.InContextObjectField(choices, field, case_sensitive=True)

Bases: Choice

__init__(choices, field, case_sensitive=True)

convert(value, param, ctx)

Convert the value to the correct type. This is not called if the value is None (the missing value).

This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.

The param and ctx arguments may be None in certain situations, such as when converting prompt input.

If the value cannot be converted, call fail() with a descriptive message.

Parameters:

value – The value to convert.
param – The parameter that is using this type to convert its value. May be None.
ctx – The current context that arrived at this value. May be None.

shell_complete(ctx, param, incomplete)

Complete choices that start with the incomplete value.

Parameters:

ctx – Invocation context for this command.
param – The parameter that is requesting completion.
incomplete – Value being completed. May be empty.

Added in version 8.0.

MonitoringLogger

class icicle.cli_utils.MonitoringLogger(*writers)

Bases: object

Multiple output logging interface.

Multilogger that allows configurable writers (i.e. functions) to be registered, as well as flushers (also functions). On a write to a MonitoringLogger, all registered writers are called, then all flushers.

__init__(*writers)

Initialise multilogger and immediately register writers if provided.

Parameters:: writers – List of functions to register that should be called by logger on write().

register_flusher(flusher)

Register flusher.

Parameters:: flusher – Functions to register that should be called by logger after write().

register_writer(writer)

Register writer.

Parameters:: writer – Functions to register that should be called by logger on write().

write(*args, **kwargs)

Write to all registered writers, then flush all registered flushers.

Parameters:: args... – arguments to be passed to writers. :param *kwargs: keyword arguments to be passed to writers.