configargparse.ArgumentParser

class documentation

class ArgumentParser(argparse.ArgumentParser): (source)

Constructor: ArgumentParser(*args, **kwargs)

Drop-in replacement for argparse.ArgumentParser that adds support for environment variables and .ini or .yaml-style config files.

Method	`__init__`	Supports args of the `argparse.ArgumentParser` constructor as **kwargs, as well as the following additional args.
Method	`convert_item_to_command_line_arg`	Converts a config file or env var key + value to a list of commandline args to append to the commandline.
Method	`format_help`	Undocumented
Method	`format_values`	Returns a string with all args and settings and where they came from (eg. commandline, config file, environment variable or default)
Method	`get_command_line_key_for_unknown_config_file_setting`	Compute a commandline arg key to be used for a config file setting that doesn't correspond to any defined configargparse arg (and so doesn't have a user-specified commandline arg key).
Method	`get_items_for_config_file_output`	Converts the given settings back to a dictionary that can be passed to ConfigFormatParser.serialize(..).
Method	`get_possible_config_keys`	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 config keys that can be used to set the given action's value in a config file.
Method	`get_source_to_settings_dict`	If called after `parse_args()` or `parse_known_args()`, returns a dict that contains up to 4 keys corresponding to where a given option's value is coming from: - "command_line" - "environment_variables" - "config_file" - "defaults" Each such key, will be mapped to another dictionary containing the options set via that method...
Method	`parse_args`	Supports all the same args as the `argparse.ArgumentParser.parse_args()`, as well as the following additional args.
Method	`parse_known_args`	Supports all the same args as the `argparse.ArgumentParser.parse_args()`, as well as the following additional args.
Method	`print_values`	Prints the format_values() string (to sys.stdout or another file).
Method	`write_config_file`	Write the given settings to output files.
Method	`_open_config_files`	Tries to parse config file path(s) from within command_line_args. Returns a list of opened config files, including files specified on the commandline as well as any default_config_files specified in the constructor that are present on disk.
Instance Variable	`_add_config_file_help`	Undocumented
Instance Variable	`_add_env_var_help`	Undocumented
Instance Variable	`_auto_env_var_prefix`	Undocumented
Instance Variable	`_config_file_open_func`	Undocumented
Instance Variable	`_config_file_parser`	Undocumented
Instance Variable	`_default_config_files`	Undocumented
Instance Variable	`_ignore_unknown_config_file_keys`	Undocumented
Instance Variable	`_source_to_settings`	Undocumented

Inherited from ArgumentParser:

Method	`add_subparsers`	Undocumented
Method	`convert_arg_line_to_args`	Undocumented
Method	`error`	error(message: string)
Method	`exit`	Undocumented
Method	`format_usage`	Undocumented
Method	`parse_intermixed_args`	Undocumented
Method	`parse_known_intermixed_args`	Undocumented
Method	`print_help`	Undocumented
Method	`print_usage`	Undocumented
Instance Variable	`add_help`	Undocumented
Instance Variable	`allow_abbrev`	Undocumented
Instance Variable	`epilog`	Undocumented
Instance Variable	`exit_on_error`	Undocumented
Instance Variable	`formatter_class`	Undocumented
Instance Variable	`fromfile_prefix_chars`	Undocumented
Instance Variable	`prog`	Undocumented
Instance Variable	`usage`	Undocumented
Method	`_add_action`	Undocumented
Method	`_check_value`	Undocumented
Method	`_get_formatter`	Undocumented
Method	`_get_kwargs`	Undocumented
Method	`_get_nargs_pattern`	Undocumented
Method	`_get_option_tuples`	Undocumented
Method	`_get_optional_actions`	Undocumented
Method	`_get_positional_actions`	Undocumented
Method	`_get_value`	Undocumented
Method	`_get_values`	Undocumented
Method	`_match_argument`	Undocumented
Method	`_match_arguments_partial`	Undocumented
Method	`_parse_known_args`	Undocumented
Method	`_parse_optional`	Undocumented
Method	`_print_message`	Undocumented
Method	`_read_args_from_files`	Undocumented
Instance Variable	`_optionals`	Undocumented
Instance Variable	`_positionals`	Undocumented
Instance Variable	`_subparsers`	Undocumented

Inherited from _AttributeHolder (via ArgumentParser):

Method	`__repr__`	Undocumented
Method	`_get_args`	Undocumented

Inherited from _ActionsContainer (via ArgumentParser, _AttributeHolder):

Method	`add_argument`	add_argument(dest, ..., name=value, ...) add_argument(option_string, option_string, ..., name=value, ...)
Method	`add_argument_group`	Undocumented
Method	`add_mutually_exclusive_group`	Undocumented
Method	`get_default`	Undocumented
Method	`register`	Undocumented
Method	`set_defaults`	Undocumented
Instance Variable	`argument_default`	Undocumented
Instance Variable	`conflict_handler`	Undocumented
Instance Variable	`description`	Undocumented
Instance Variable	`prefix_chars`	Undocumented
Method	`_add_container_actions`	Undocumented
Method	`_check_conflict`	Undocumented
Method	`_get_handler`	Undocumented
Method	`_get_optional_kwargs`	Undocumented
Method	`_get_positional_kwargs`	Undocumented
Method	`_handle_conflict_error`	Undocumented
Method	`_handle_conflict_resolve`	Undocumented
Method	`_pop_action_class`	Undocumented
Method	`_registry_get`	Undocumented
Method	`_remove_action`	Undocumented
Instance Variable	`_action_groups`	Undocumented
Instance Variable	`_actions`	Undocumented
Instance Variable	`_defaults`	Undocumented
Instance Variable	`_has_negative_number_optionals`	Undocumented
Instance Variable	`_mutually_exclusive_groups`	Undocumented
Instance Variable	`_negative_number_matcher`	Undocumented
Instance Variable	`_option_string_actions`	Undocumented
Instance Variable	`_registries`	Undocumented

def __init__(self, *args, **kwargs): (source) ¶

overrides argparse.ArgumentParser.__init__

Supports args of the argparse.ArgumentParser constructor as **kwargs, as well as the following additional args.

Parameters
*args	Undocumented
**kwargs	Undocumented
add_config_file_help	Whether to add a description of config file syntax to the help message.
add_env_var_help	Whether to add something to the help message for args that can be set through environment variables.
auto_env_var_prefix	If set to a string instead of None, all config- file-settable options will become also settable via environment variables whose names are this prefix followed by the config file key, all in upper case. (eg. setting this to `foo_` will allow an arg like `--my-arg` to also be set via the FOO_MY_ARG environment variable)
default_config_files	When specified, this list of config files will be parsed in order, with the values from each config file taking precedence over previous ones. This allows an application to look for config files in multiple standard locations such as the install directory, home directory, and current directory. Also, shell * syntax can be used to specify all conf files in a directory. For example: ["/etc/conf/app_config.ini", "/etc/conf/conf-enabled/*.ini", "~/.my_app_config.ini", "./app_config.txt"]
ignore_unknown_config_file_keys	If true, settings that are found in a config file but don't correspond to any defined configargparse args will be ignored. If false, they will be processed and appended to the commandline like other args, and can be retrieved using parse_known_args() instead of parse_args()
config_file_open_func	function used to open a config file for reading or writing. Needs to return a file-like object.
config_file_parser_class	configargparse.ConfigFileParser subclass which determines the config file format. configargparse comes with DefaultConfigFileParser and YAMLConfigFileParser.
args_for_setting_config_path	A list of one or more command line args to be used for specifying the config file path (eg. ["-c", "--config-file"]). Default: []
config_arg_is_required	When args_for_setting_config_path is set, set this to True to always require users to provide a config path.
config_arg_help_message	the help message to use for the args listed in args_for_setting_config_path.
args_for_writing_out_config_file	A list of one or more command line args to use for specifying a config file output path. If provided, these args cause configargparse to write out a config file with settings based on the other provided commandline args, environment variants and defaults, and then to exit. (eg. ["-w", "--write-out-config-file"]). Default: []
write_out_config_file_arg_help_message	The help message to use for the args in args_for_writing_out_config_file.

def convert_item_to_command_line_arg(self, action, key, value): (source) ¶

Converts a config file or env var key + value to a list of commandline args to append to the commandline.

Parameters
action	The argparse Action object for this setting, or None if this config file setting doesn't correspond to any defined configargparse arg.
key	string (config file key or env var name)
value	parsed value of type string or list
Returns
`list[str]`	args

def format_help(self): (source) ¶

overrides argparse.ArgumentParser.format_help

Undocumented

def format_values(self): (source) ¶

Returns a string with all args and settings and where they came from (eg. commandline, config file, environment variable or default)

Returns
`str`	source to settings string

def get_command_line_key_for_unknown_config_file_setting(self, key): (source) ¶

Compute a commandline arg key to be used for a config file setting that doesn't correspond to any defined configargparse arg (and so doesn't have a user-specified commandline arg key).

Parameters
key	The config file key that was being set.
Returns
`str`	command line key

def get_items_for_config_file_output(self, source_to_settings, parsed_namespace): (source) ¶

Converts the given settings back to a dictionary that can be passed to ConfigFormatParser.serialize(..).

Parameters
source_to_settings	the dictionary described in parse_known_args()
parsed_namespace	namespace object created within parse_known_args()
Returns
`OrderedDict`	where keys are strings and values are either strings or lists

def get_possible_config_keys(self, action): (source) ¶

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 config keys that can be used to set the given action's value in a config file.

Returns
`list[str]`	keys

def get_source_to_settings_dict(self): (source) ¶

If called after parse_args() or parse_known_args(), returns a dict that contains up to 4 keys corresponding to where a given option's value is coming from: - "command_line" - "environment_variables" - "config_file" - "defaults" Each such key, will be mapped to another dictionary containing the options set via that method. Here the key will be the option name, and the value will be a 2-tuple of the form (argparse.Action obj, str value).

Returns
`dict[str`, `dict[str`, `tuple[argparse.Action`, `str]]]`	source to settings dict

def parse_args(self, args=None, namespace=None, config_file_contents=None, env_vars=os.environ): (source) ¶

overrides argparse.ArgumentParser.parse_args

Supports all the same args as the argparse.ArgumentParser.parse_args(), as well as the following additional args.

Parameters
args	a list of args as in argparse, or a string (eg. "-x -y bla")
namespace	Undocumented
config_file_contents	String. Used for testing.
env_vars	Dictionary. Used for testing.
Returns
`argparse.Namespace`	namespace

def parse_known_args(self, args=None, namespace=None, config_file_contents=None, env_vars=os.environ, ignore_help_args=False): (source) ¶

overrides argparse.ArgumentParser.parse_known_args

Supports all the same args as the argparse.ArgumentParser.parse_args(), as well as the following additional args.

Parameters
args	a list of args as in argparse, or a string (eg. "-x -y bla")
namespace	Undocumented
config_file_contents:`str`
env_vars:`dict`
ignore_help_args:`bool`	This flag determines behavior when user specifies `--help` or `-h`. If False, it will have the default behavior - printing help and exiting. If True, it won't do either.
Returns
`tuple[argparse.Namespace`, `list[str]]`	tuple namescpace, unknown_args

def print_values(self, file=sys.stdout): (source) ¶

Prints the format_values() string (to sys.stdout or another file).

def write_config_file(self, parsed_namespace, output_file_paths, exit_after=False): (source) ¶

Write the given settings to output files.

Parameters
parsed_namespace	namespace object created within parse_known_args()
output_file_paths	any number of file paths to write the config to
exit_after	whether to exit the program after writing the config files

def _open_config_files(self, command_line_args): (source) ¶

Tries to parse config file path(s) from within command_line_args. Returns a list of opened config files, including files specified on the commandline as well as any default_config_files specified in the constructor that are present on disk.

Parameters
command_line_args	List of all args
Returns
`list[IO]`	open config files

_add_config_file_help: bool = (source) ¶

Undocumented

_add_env_var_help: bool = (source) ¶

Undocumented

_auto_env_var_prefix = (source) ¶

Undocumented

_config_file_open_func = (source) ¶

Undocumented

_config_file_parser = (source) ¶

Undocumented

_default_config_files = (source) ¶

Undocumented

_ignore_unknown_config_file_keys = (source) ¶

Undocumented

_source_to_settings = (source) ¶

Undocumented