bcftbx.cmdparse

Provides a CommandParser class for handling command lines of the form:

PROG COMMAND OPTION ARGS

where different sets of options can be defined based on the initial command.

The CommandParser can support arbitrary ‘subparser backends’ which are created to parse the ARGS list for each defined COMMAND. The default subparser is the ‘argparse.ArgumentParser’ class, but this can be swapped for arbitrary subparser when the CommandParser is created.

In addition to the core CommandParser class, there are a number of supporting functions that can be used with any argparse-based parser instance, to add the following ‘standard’ options:

• –nprocessors

• –runner

• –no-save

• –dry-run

• –debug

class bcftbx.cmdparse.CommandParser(description=None, version=None, subparser=None)

Class defining multiple command line parsers

This parser can process command lines of the form

PROG CMD OPTIONS ARGS

where different sets of options can be defined based on the major command (‘CMD’) supplied at the start of the line.

Usage:

Create a simple CommandParser which uses argparse.ArgumentParser as the default subparser backend using:

>>> p = CommandParser()

Alternatively, specify argparse.ArgumentParser as the subparser using:

>>> p = CommandParser(subparser=argparser.ArgumentParser)

Add a ‘setup’ command:

>>> p.add_command('setup',usage='%prog setup OPTIONS ARGS')

Add options to the ‘setup’ command using the appropriate methods of the subparser (e.g. ‘add_argument’ for an ArgumentParser instance).

For example:

>>> p.parser_for('info').add_argument('-f',...)

To process a command line, use the ‘parse_args’ method, for example for an OptionParser-based subparser:

>>> cmd,options,args = p.parse_args()

Note that the exact form of the returned values depends on on the subparser instance; it will be the same as that returned by the ‘parse_args’ method of the subparser.

add_command(cmd, help=None, **args)

Add a major command to the CommandParser

Adds a command, and creates and returns an initial subparser instance for it.

Parameters:

• cmd – the command to be added

• help – (optional) help text for the command

Other arguments are passed to the subparser instance when it is created i.e. ‘usage’, ‘version’, ‘description’.

If ‘version’ isn’t specified then the version supplied to the CommandParser object will be used.

Returns:

Subparser instance object for the command.

error(message)

Exit with error message

handle_generic_commands(cmd)

Process ‘generic’ commands e.g. ‘help’

list_commands()

Return the list of commands

parse_args(argv=None)

Process a command line

Parses a command line (either those supplied to the calling subprogram e.g. via the Python interpreter, or as a list).

Once the command is identified from the first argument, the remainder of the arguments are passed to the ‘parse_args’ method of the appropriate subparser for that command.

This method returns a tuple, with the first value being the command, and the rest of the values being those returned from the ‘parse_args’ method of the subparser.

Parameters:

argv – (optional) a list consisting of a command line. If not supplied then defaults to sys.argv[1:].

Returns:

A tuple of (cmd,…), where ‘cmd’ is the command, and ‘…’ represents the values returned from the ‘parse_args’ method of the subparser. For example, using the default OptionParser backend returns (cmd,options,arguments), where ‘options’ and ‘arguments’ are the options and arguments as returned by OptionParser.parse_args; using ArgumentParser as a backend returns (cmd,arguments).

parser_for(cmd)

Return OptionParser for specified command

Returns:

The OptionParser object for the specified command.

print_available_commands()

Pretty-print available commands

Returns a ‘pretty-printed’ string for all options and commands, with standard whitespace formatting.

print_command(cmd, message=None)

Print a line for a single command

Returns a ‘pretty-printed’ line for the specified command and text, with standard whitespace formatting.

bcftbx.cmdparse.add_arg(p, *args, **kwds)

Add an argument or option to a parser

Given an arbitrary parser instance, adds a new option or argument using the appropriate method call and passing the supplied arguments and keywords.

For example, if the parser is an instance of argparse.ArgumentParser, then the ‘add_argument’ method will be invoked to add a new argument to the parser.

Parameters:

• p (Object) – parser instance

• args (List) – list of argument values to pass directly to the argument-addition method

• kwds (mapping) – keyword-value mapping to pass directly to the argument-addition method

bcftbx.cmdparse.add_debug_option(parser)

Add a ‘–debug’ option to a parser

Given a parser instance ‘parser’ (either OptionParser or ArgumentParser), add a ‘–debug’ option.

The value of this option can be accessed via the ‘debug’ attribute of the parser options.

Returns the input parser object.

bcftbx.cmdparse.add_dry_run_option(parser)

Add a ‘–dry-run’ option to a parser

Given a parser instance ‘parser’ (either OptionParser or ArgumentParser), add a ‘–dry-run’ option.

The value of this option can be accessed via the ‘dry_run’ attribute of the parser options.

Returns the input parser object.

bcftbx.cmdparse.add_no_save_option(parser)

Add a ‘–no-save’ option to a parser

Given a parser instance ‘parser’ (either OptionParser or ArgumentParser), add a ‘–no-save’ option.

The value of this option can be accessed via the ‘no_save’ attribute of the parser options.

Returns the input parser object.

bcftbx.cmdparse.add_nprocessors_option(parser, default_nprocessors, default_display=None)

Add a ‘–nprocessors’ option to a parser

Given a parser instance ‘parser’ (either OptionParser or ArgumentParser), add a ‘–nprocessors’ option.

The value of this option can be accessed via the ‘nprocessors’ attribute of the parser options.

If ‘default_display’ is not None then this value will be shown in the help text, rather than the value supplied for the default.

Returns the input parser object.

bcftbx.cmdparse.add_runner_option(parser)

Add a ‘–runner’ option to a parser

Given a parser instance ‘parser’ (either OptionParser or ArgumentParser), add a ‘–runner’ option.

The value of this option can be accessed via the ‘runner’ attribute of the parser options (use the ‘fetch_runner’ function to return a JobRunner object from the supplied value).

Returns the input parser object.