augur.argparse_ module

Custom helpers for the argparse standard library.

class augur.argparse_.CustomArgumentGroup(container, title=None, description=None, **kwargs)

Bases: _ArgumentGroup

Custom class to support the cli_only parameter on added arguments.

add_argument(*args, cli_only=False, **kwargs)

This method supports the same args as ArgumentParser.add_argument(..) as well as the additional args below.

Keyword Arguments:

  • env_var -- If set, the value of this environment variable will override any config file or default values for this arg (but can itself be overridden on the commandline). Also, if auto_env_var_prefix is set in the constructor, this env var name will be used instead of the automatic name.

  • is_config_file_arg -- If True, this arg is treated as a config file path This provides an alternative way to specify config files in place of the ArgumentParser(fromfile_prefix_chars=..) mechanism. Default: False

  • is_write_out_config_file_arg -- If True, this arg will be treated as a config file path, and, when it is specified on the command line, will cause configargparse to write all current commandline args to this file as config options and then exit. It can only be set on the command line: a config file key that names it is an error, and it can’t be combined with env_var, nor be a positional arg, since a config file value would be indistinguishable from a path the user typed and could overwrite an arbitrary file. Default: False

Returns:

the new argparse action

Return type:

argparse.Action

add_mutually_exclusive_group(**kwargs)
class augur.argparse_.CustomArgumentParser(*args, **kwargs)

Bases: ArgumentParser

Custom argument parser for ConfigArgParse.

add_argument(*args, cli_only=False, **kwargs)

This method supports the same args as ArgumentParser.add_argument(..) as well as the additional args below.

Keyword Arguments:

  • env_var -- If set, the value of this environment variable will override any config file or default values for this arg (but can itself be overridden on the commandline). Also, if auto_env_var_prefix is set in the constructor, this env var name will be used instead of the automatic name.

  • is_config_file_arg -- If True, this arg is treated as a config file path This provides an alternative way to specify config files in place of the ArgumentParser(fromfile_prefix_chars=..) mechanism. Default: False

  • is_write_out_config_file_arg -- If True, this arg will be treated as a config file path, and, when it is specified on the command line, will cause configargparse to write all current commandline args to this file as config options and then exit. It can only be set on the command line: a config file key that names it is an error, and it can’t be combined with env_var, nor be a positional arg, since a config file value would be indistinguishable from a path the user typed and could overwrite an arbitrary file. Default: False

Returns:

the new argparse action

Return type:

argparse.Action

add_argument_group(*args, **kwargs)
add_mutually_exclusive_group(**kwargs)
convert_item_to_command_line_arg(action, key, value)

This method converts a config file entry into CLI arguments.

It is called in ConfigArgParse’s parse_known_args().

error_only(message)

An alternative to self.error, without the usage message.

format_help()
get_possible_config_keys(action)

This method decides which actions can be set in a config file and what their keys will be. It returns a list of 0 or more keys which can be used in a config YAML file.

parse_known_args(args, namespace=None, **kwargs)

This method is defined by:

  1. argparse, to parse command line options into an argparse Namespace.

  2. ConfigArgParse, to inject values from the config file into the args namespace.

  3. Augur (us), to validate the config file. We do this before calling ConfigArgParse’s parse_known_args() to prevent synthesized CLI args from being shown in argparse errors.

class augur.argparse_.CustomMutuallyExclusiveGroup(container, required=False)

Bases: _MutuallyExclusiveGroup

Custom class to support the cli_only parameter on added arguments.

add_argument(*args, cli_only=False, **kwargs)

This method supports the same args as ArgumentParser.add_argument(..) as well as the additional args below.

Keyword Arguments:

  • env_var -- If set, the value of this environment variable will override any config file or default values for this arg (but can itself be overridden on the commandline). Also, if auto_env_var_prefix is set in the constructor, this env var name will be used instead of the automatic name.

  • is_config_file_arg -- If True, this arg is treated as a config file path This provides an alternative way to specify config files in place of the ArgumentParser(fromfile_prefix_chars=..) mechanism. Default: False

  • is_write_out_config_file_arg -- If True, this arg will be treated as a config file path, and, when it is specified on the command line, will cause configargparse to write all current commandline args to this file as config options and then exit. It can only be set on the command line: a config file key that names it is an error, and it can’t be combined with env_var, nor be a positional arg, since a config file value would be indistinguishable from a path the user typed and could overwrite an arbitrary file. Default: False

Returns:

the new argparse action

Return type:

argparse.Action

class augur.argparse_.ExtendOverwriteDefault(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Bases: Action

Similar to the core argparse extend action, but overwrites the argument default, if any, instead of appending to it.

Thus, the default value is not included when the option is given and may be a non-list value if desired.

class augur.argparse_.HelpFormatter(prog, indent_increment=2, max_help_position=24, width=None)

Bases: ArgumentDefaultsHelpFormatter

add_arguments(actions)
class augur.argparse_.HideAsFalseAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Bases: Action

Custom argparse Action that stores False for arguments passed as --hide* and stores True for all other argument patterns.

augur.argparse_.InputFile(path)

Custom type for argparse representing an input file path.

A relative path is converted to an absolute path by searching in:

  1. AUGUR_SEARCH_PATHS (if set)

  2. parent directory of config file (if set)

  3. current working directory

Return type:

str

class augur.argparse_.YAMLConfigFileParser

Bases: YAMLConfigFileParser

Parses YAML config files.

The default parser uses PyYAML which has a longstanding bug¹ of silently dropping duplicate keys in a file (not good). ruamel.yaml correctly errors instead. # ¹ <https://github.com/yaml/pyyaml/issues/165>

parse(stream)

Parses the keys and values from a config file.

NOTE: For keys that were specified to configargparse as action=”store_true” or “store_false”, the config file value must be one of: “yes”, “no”, “on”, “off”, “true”, “false”. Otherwise an error will be raised.

Parameters:

stream (io.IOBase) -- A config file input stream (such as an open file object).

Returns:

Items where the keys are strings and the values are either strings or lists (eg. to support config file formats like YAML which allow lists).

Return type:

OrderedDict

augur.argparse_.add_command_subparsers(subparsers, commands, command_attribute='__command__')

Add subparsers for each command module.

Parameters:

  • subparsers (argparse._SubParsersAction) -- The special subparsers action object created by the parent parser via parser.add_subparsers().

  • commands (list[types.ModuleType]) -- A list of modules that are commands that require their own subparser. Each module is required to have a register_parser function to add its own subparser and arguments.

  • command_attribute (str, optional) -- Optional attribute name for the commands. The default is __command__, which allows top level augur to run commands directly via args.__command__.run().

augur.argparse_.add_default_command(parser)

Sets the default command to run when none is provided.

augur.argparse_.add_subparser(parent_subparsers, *args, **kwargs)

Add a subparser to a parent subparser.

Return type:

CustomArgumentParser

augur.argparse_.add_validation_arguments(parser)

Add arguments to configure validation mode of node data JSON files.

augur.argparse_.config_key_to_cli_option(key)
Return type:

str

augur.argparse_.get_config_file_path(args)

Return the path to the config file from CLI arguments, or None if no config file is provided.

Return type:

str | None

augur.argparse_.walk_commands(parser, command=None)
Return type:

Iterable[Tuple[Tuple[str, ...], CustomArgumentParser]]