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): For a given value from the parser, normalize it and find its matching normalized value in the list of choices. Then return the matched “original” choice.

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.