taucmdr.cli.arguments module

TAU Commander command line interface (CLI).

Extensions to argparse to support the TAU Commander command line interface.

class taucmdr.cli.arguments.Action(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]

Bases: argparse._AttributeHolder

Information about how to convert command line strings to Python objects.

Action objects are used by an ArgumentParser to represent the information needed to parse a single argument from one or more strings from the command line. The keyword arguments to the Action constructor are also all attributes of Action instances.

Keyword Arguments:
 
  • option_strings -- A list of command-line option strings which (-) – should be associated with this action.
  • dest -- The name of the attribute to hold the created object (-) –
  • nargs -- The number of command-line arguments that should be (-) –

    consumed. By default, one argument will be consumed and a single value will be produced. Other values include:

    • N (an integer) consumes N arguments (and produces a list)
    • ’?’ consumes zero or one arguments
    • ’*’ consumes zero or more arguments (and produces a list)
    • ’+’ consumes one or more arguments (and produces a list)

    Note that the difference between the default and nargs=1 is that with the default, a single value will be produced, while with nargs=1, a list containing a single value will be produced.

  • const -- The value to be produced if the option is specified and the (-) – option uses an action that takes no values.
  • default -- The value to be produced if the option is not specified. (-) –
  • type -- A callable that accepts a single string argument, and (-) – returns the converted value. The standard Python types str, int, float, and complex are useful examples of such callables. If None, str is used.
  • choices -- A container of values that should be allowed. If not None, (-) – after a command-line argument has been converted to the appropriate type, an exception will be raised if it is not a member of this collection.
  • required -- True if the action must always be specified at the (-) – command line. This is only meaningful for optional command-line arguments.
  • help -- The help string describing the argument. (-) –
  • metavar -- The name to be used for the option's argument with the (-) – help string. If None, the ‘dest’ value will be used as the name.
exception taucmdr.cli.arguments.ArgumentError(argument, message)[source]

Bases: Exception

An error from creating or using an argument (optional or positional).

The string value of this exception is the message, augmented with information about the argument that caused it.

taucmdr.cli.arguments.ArgumentsNamespace

alias of argparse.Namespace

class taucmdr.cli.arguments.ConsoleHelpFormatter(prog, indent_increment=2, max_help_position=30, width=None)[source]

Bases: taucmdr.cli.arguments.HelpFormatter

Custom help string formatter for console output.

add_argument(action)[source]
start_section(heading)[source]
class taucmdr.cli.arguments.HelpFormatter(prog, indent_increment=2, max_help_position=30, width=None)[source]

Bases: argparse.RawDescriptionHelpFormatter

Custom help string formatter for argument parser.

Provide proper help message alignment, line width, and formatting. Uses console line width (logger.LINE_WIDTH) to format help messages appropriately so they don’t wrap in strange ways.

Parameters:
  • prog (str) – Name of the program.
  • indent_increment (int) – Number of spaces to indent wrapped lines.
  • max_help_position (int) – Column on which to begin subsequent lines of wrapped help strings.
  • width (int) – Maximum help message length before wrapping.
class taucmdr.cli.arguments.MarkdownHelpFormatter(prog, indent_increment=2, max_help_position=30, width=74)[source]

Bases: taucmdr.cli.arguments.HelpFormatter

Custom help string formatter for markdown output.

first_col_width = 30
class taucmdr.cli.arguments.MutableArgumentGroup(*args, **kwargs)[source]

Bases: argparse._ArgumentGroup

Argument group that allows its actions to be modified after creation.

class taucmdr.cli.arguments.MutableArgumentGroupParser(*args, **kwargs)[source]

Bases: argparse.ArgumentParser

Argument parser with mutable groups and better help formatting.

argparse.ArgumentParser doesn’t allow groups to change once set and generates “scruffy” looking help, so we fix this problems in this subclass.

_format_help_console()[source]

Format command line help string.

_format_help_markdown()[source]

Format command line help string.

_sorted_groups()[source]

Iterate over action groups.

add_argument_group(*args, **kwargs)[source]

Returns an argument group.

If the group doesn’t exist it will be created.

Parameters:
  • *args – Positional arguments to pass to ArgumentParser.add_argument_group
  • **kwargs – Keyword arguments to pass to ArgumentParser.add_argument_group
Returns:

An argument group object.
format_help()[source]
merge(parser, group_title=None, include_positional=False, include_optional=True, include_storage=False, exclude_groups=None, exclude_arguments=None)[source]

Merge arguments from a parser into this parser.

Modify this parser by adding additional arguments copied from the supplied parser.

Parameters:
  • parser (MutableArgumentGroupParser) – Parser to pull arguments from.
  • group_title (str) – Optional group title for merged arguments.
  • include_positional (bool) – If True, include positional arguments.
  • include_optional (bool) – If True, include optional arguments.
  • include_storage (bool) – If True, include the storage level argument, see STORAGE_LEVEL_FLAG.
  • exclude_groups (list) – Strings identifying argument groups that should be excluded.
  • exclude_arguments (list) – Strings identifying arguments that should be excluded.
class taucmdr.cli.arguments.ParseBooleanAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]

Bases: argparse.Action

Argument parser action for boolean values.

Essentially a wrapper around taucmdr.util.parse_bool.

__call__(parser, namespace, value, unused_option_string=None)[source]

Sets the self.dest attribute in namespace to the parsed value of value.

If value parses to a boolean via taucmdr.util.parse_bool then the attribute value is that boolean value.

Parameters:
  • parser (str) – Argument parser object this group belongs to.
  • namespace (object) – Namespace to receive parsed value via setattr.
  • value (str) – Value parsed from the command line/
class taucmdr.cli.arguments.ParsePackagePathAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]

Bases: argparse.Action

Argument parser action for software package paths.

This action checks that an argument’s value is one of these cases: 1) The path to an existing software package installation. 2) The path to an archive file containing the software package. 3) A URL to an archive file containing the software package. 4) The magic word “download” or value that parses to True via taucmdr.util.parse_bool. 5) A value that parses to False via parse_bool.

__call__(parser, namespace, value, unused_option_string=None)[source]

Sets the self.dest attribute in namespace to the parsed value of value.

If value parses to a boolean True value then the attribute value is ‘download’. If value parses to a boolean False value then the attribute value is None. Otherwise the attribute value is the value of value.

Parameters:
  • parser (str) – Argument parser object this group belongs to.
  • namespace (object) – Namespace to receive parsed value via setattr.
  • value (str) – Value parsed from the command line.
taucmdr.cli.arguments.REMAINDER = '...'

All the remaining command-line arguments are gathered into a list.

taucmdr.cli.arguments.STORAGE_LEVEL_FLAG = '@'

Command line flag that indicates storage level.

taucmdr.cli.arguments.SUPPRESS = '==SUPPRESS=='

Suppress attribute creation in parsed argument namespace.

taucmdr.cli.arguments.add_storage_flag(parser, action, object_name, plural=False, exclusive=True)[source]

Add flag to indicate target storage container.

Parameters:
  • parser (MutableArgumentGroupParser) – The parser to modify.
  • action (str) – The action that will be taken by the command, e.g. “delete” or “list”
  • object_name (str) – The type of object that will be manipulated, e.g. “application” or “measurement”
  • plural (bool) – Pluralize help message if True.
  • exclusive (bool) – Only one storage level may be specified if True.
taucmdr.cli.arguments.get_parser(prog=None, usage=None, description=None, epilog=None)[source]

Builds an argument parser.

The returned argument parser accepts no arguments. Use argparse.ArgumentParser.add_argument to add arguments.

Parameters:
  • prog (str) – Name of the program.
  • usage (str) – Description of the program’s usage.
  • description (str) – Text to display before the argument help.
  • epilog (str) – Text to display after the argument help.
Returns:

The customized argument parser object.
Return type:

MutableArgumentGroupParser
taucmdr.cli.arguments.get_parser_from_model(model, use_defaults=True, prog=None, usage=None, description=None, epilog=None)[source]

Builds an argument parser from a model’s attributes.

The returned argument parser will accept arguments as defined by the model’s argparse attribute properties, where the arguments to argparse.ArgumentParser.add_argument are specified as keyword arguments.

Examples

Given this model attribute:

'openmp': {
    'type': 'boolean',
    'description': 'application uses OpenMP',
    'default': False,
    'argparse': {'flags': ('--openmp',),
                 'metavar': 'T/F',
                 'nargs': '?',
                 'const': True,
                 'action': ParseBooleanAction},
}

The returned parser will accept the --openmp flag accepting zero or one arguments with ‘T/F’ as the metavar. If --openmp is omitted the default value of False will be used. If --openmp is provided with zero arguments, the const value of True will be used. If --openmp is provided with one argument then the provided argument will be passed to a ParseBooleanAction instance to generate a boolean value. The argument’s help description will appear as “application uses OpenMP” if the --help argument is given.

Parameters:
  • model (Model) – Model to construct arguments from.
  • use_defaults (bool) – If True, use the model attribute’s default value as the argument’s value if argument is not specified.
  • prog (str) – Name of the program.
  • usage (str) – Description of the program’s usage.
  • description (str) – Text to display before the argument help.
  • epilog (str) – Text to display after the argument help.
Returns:

The customized argument parser object.
Return type:

MutableArgumentGroupParser
taucmdr.cli.arguments.parse_storage_flag(args)[source]