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, deprecated=False)

Bases: _AttributeHolder

Action base class.

_get_kwargs()

format_usage()

exception taucmdr.cli.arguments.ArgumentError(argument, message)

Bases: Exception

Argument error exception base class.

taucmdr.cli.arguments.ArgumentsNamespace

Generic container for parsed arguments.

class taucmdr.cli.arguments.ConsoleHelpFormatter(prog, indent_increment=2, max_help_position=30, width=None, show_defaults=True)

Bases: HelpFormatter

Custom help string formatter for console output.

_format_action(action)

_format_optional(argstr)

_format_optional_arg(argstr)

_format_positional(argstr)

_format_requred_arg(argstr)

add_argument(action)

start_section(heading)

class taucmdr.cli.arguments.HelpFormatter(prog, indent_increment=2, max_help_position=30, width=None, show_defaults=True)

Bases: 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.

• show_defaults (bool) – If False, don’t show each argument’s default value.

_format_action_invocation(action)

_format_args(action, default_metavar)

_format_meta_arg(argstr)

_format_optional(argstr)

_format_optional_arg(argstr)

_format_positional(argstr)

_format_requred_arg(argstr)

_get_help_string(action)

_split_lines(text, width)

class taucmdr.cli.arguments.MutableArgumentGroup(*args, **kwargs)

Bases: _ArgumentGroup

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

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

Bases: 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.

_sorted_groups()

Iterate over action groups.

add_argument_group(*args, **kwargs)

Returns an argument group.

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

Parameters:

• *args – Positional arguments to pass to argparse.ArgumentParser.add_argument_group()

• **kwargs – Keyword arguments to pass to argparse.ArgumentParser.add_argument_group()

Returns:

An argument group object.

format_help(formatter=None)

Format command line help string.

merge(parser, group_title=None, include_positional=False, include_optional=True, include_storage=False, exclude_groups=None, exclude_arguments=None)

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, deprecated=False)

Bases: Action

Argument parser action for boolean values.

Essentially a wrapper around taucmdr.util.parse_bool.

__call__(parser, namespace, value, unused_option_string=None)

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: list[str], dest: str, rejected: dict[str, str] | None = None, **kwargs)

Bases: 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.

Parameters:

rejected (dict) – Optional mapping of lower-case values that must not be accepted, e.g. keywords an earlier release understood, to the reason they are rejected. The reason follows the quoted value in the error message, so it should read “is no longer supported. …”.

__call__(parser, namespace, value, unused_option_string=None)

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.

Raises:

argparse.ArgumentError – value is listed in rejected, or is not a keyword, path, or URL.

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)

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)

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)

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)