command - Wrap complex commands in Python objects

Tools to wrap a Python API around interactive and non-interactive programs.

The command.Command and interpreter.Interpreter classes handle batch and interactive commands respectively. They can be provided with option.Config instances which describe the options available to the programs being wrapped. The option.Parser class can then be used to validate option sets and construct the corresponding command lines. See the svn.svn module for a concrete example.

command - Drive batch commands with function calls

Non interactive command driver.

class Command(cmd, debug=False)

Represents the command to be executed. Typically you would derive from this class and provide a different method for each alternative way of invoking the program. If the program you want to execute has many sub-commands you might provide a different method for each sub-command. You can use the option.Config class to declare the options supported by your command and then use the option.Parser class to validate your methods’ arguments and generate the resulting command line. A debug mode is available in which commands are echoed rather than run. This can be enabled globally or separately for each invocation.

__init__(cmd, debug=False)

Takes as arguments the command name and a boolean value indicating whether debug mode should be activated for all executions of this command.

run(parser, debug=False)

Executes the command. Takes as arguments a command line parser (see the option module) and a boolean indicating whether debug mode should be used for this execution.

exception Error(cmd, returncode, err)

Raised when command execution fails.

__init__(cmd, returncode, err)

Takes the command line, the error code and the contents of the error stream.

error - The command package exception hierarchy

Exception classes for the nxpy.command package.

exception BadLogFormat

Raised if the requested formatting option is unknown.

exception Error

Package exceptions’ base class.

exception ExpectError

Raised on invalid input from stdout or stderr.

exception TimeoutError

Raised when expect didn’t satisfy a timing constraint.

exception TimerError

Raised on misuse of the Timer class.

interpreter - Wrap interactive programs in Python classes

Interactive program driver.

exception BadCommand(cmd, err)

Raised on a command execution failure

__init__(cmd, err)

Takes the failed command and the contents of the error stream.

class BaseInterpreter(popen)

Controls the execution of an interactive program in a sub-process. Provides means to send input to the controlled process and to check different conditions on its output and error streams.

__init__(popen)

Creates an interpreter instance. popen is a Popen-like object which must support non-blocking I/O.

expect(cond=None, timeout=0, retries=0, interval=0.01, quantum=0.01, raise_on_error=True, log=None)

Express expectations on the outcome of a command.

cond is a two argument callable which will be passed the command’s standard output and standard error, and which should return True if the expectation is satisfied. For the other arguments see the documentation for the Timer class.

expect_any(**kwargs)

Expect any output.

expect_lines(count=1, **kwargs)

Expect count lines of output.

expect_regexp(regexp, where=0, **kwargs)

Expect to find a match for the regexp regular expression within the where stream.

expect_string(string, where=0, **kwargs)

Expect a string in the where stream.

run(cmd, log=None, **kwargs)

Executes the command and waits for the expected outcome or an error.

send_cmd(cmd, log=None)

Write cmd to the interpreter’s input, optianally logging it. If log is not None, override the global setting.

setLog(log)

If log is True, enable logging of command output and error, otherwise disable it.

class Interpreter(cmd)

The actual Interpreter class.

This implementation uses a core.async_subprocess.AsyncPopen instance.

__init__(cmd)

class LineWaiter(count)

Wait for count lines of output.

__call__(out, err)

__init__(count)

class RegexpWaiter(regexp, where)

Wait for a match to a given regexp, passed either compiled or as a string.

__call__(out, err)

__init__(regexp, where)

class StringWaiter(string, where)

Wait for a specific string in the where stream.

__call__(out, err)

__init__(string, where)

class Timer(timeout=0, retries=0, interval=0.1, quantum=0.01)

A collaborative timer class. Support a polling mechanism by keeping track of the amount of time to wait before the next attempt, according to different policies.

__init__(timeout=0, retries=0, interval=0.1, quantum=0.01)

Specify an overall timeout, a number of retries and/or an interval between them. The next attempt will not take place before a quantum has passed. Timings are expressed in seconds. If a timeout is specified it will take precedence over the other arguments; in that case the number of retries will take precedence over the interval. If neither a timeout nor a number of retries are specified the overall timer will never expire.

expired()

Indicate whether the current timer expired. Use as polling loop control condition.

getInterval()

Return the next wait interval. Call after each attempt in order to know how long to wait for.

reset()

Reset the timer.

waitError(out, err)

Wait for any error.

waitOutput(out, err)

Wait for any output.

option - Describe complex command lines

Function argument to command line option conversion. Provides means to describe commands with complicated syntaxes, which often combine sub-commands, options and arguments. Typical examples include subversion and ftp.

class Config(prefix='--', separator=' ', bool_opts=(), value_opts=(), iterable_opts=(), format_opts={}, mapped_opts={}, opposite_opts={})

Command option definitions. Provides a single definition point for all the options supported by a command.

__init__(prefix='--', separator=' ', bool_opts=(), value_opts=(), iterable_opts=(), format_opts={}, mapped_opts={}, opposite_opts={})

Constructor. Its arguments are used to specify all the valid options. Each option is prefixed by prefix. When an option takes multiple arguments these are separated by a separator. bool_opts must be specified on the command line when they are True. value_opts take a single argument; iterable_opts take multiple arguments; format_opts have their syntax specified by means of a format string; mapped_opts require some form of translation, usually because they are not valid Python identifiers; opposite_opts must be specified on the command line when they are False.

exception InvalidOptionError

Raised when an option is not supported.

class Parser(config, command, arguments, options, **defaults)

Constructs a complex command line from the provided command and its options and arguments. Uses a Config instance, config, to provide means to check conditions on the supplied options. Other constraints on how options should be used may be expressed and verified by means of the check methods.

__init__(config, command, arguments, options, **defaults)

Takes an instance of Config, a command to execute, an iterable of arguments and a mapping of options and their actual values. The remaining keyword arguments indicate the options supported by command with their default values.

checkExactlyOneOption(*options)

Checks that one and only one in a set of mutually exclusive options has been specified.

checkExclusiveOptions(*options)

Checks that at most one in a set of mutually exclusive options has been specified.

checkMandatoryOptions(*options)

Checks that all compulsory options have been specified.

checkNotBothOptsAndArgs(*options)

Checks that options incompatible with arguments haven’t been specified if any argument is present.

checkOneBetweenOptsAndArgs(*options)

Checks that either at least one in a set of options or some arguments have been specified, but not both.

getCommandLine()

Returns the command line to be executed.