ConfigArgParse Documentation

ConfigArgParse supports special syntax in config files and environment variables to represent complex types:

• Booleans: Setting key = true is treated as if the flag --key was passed on the command line. The corresponding argument in your Python code must be defined with an action like action='store_true'.
• Lists: Setting key = [value1, value2, ...] is treated as if --key value1 --key value2 ... was passed. The corresponding argument must be defined with action='append' or similar list-based actions.

ConfigArgParse allows you to define settings through multiple sources. If a value is specified in more than one way, the library follows a strict precedence order to resolve the final value:

1. Command line arguments (Highest priority)
2. Environment variables
3. Config file values
4. Defaults (Lowest priority)

This allows users to provide a base configuration in a file, override specific settings via environment variables in a container/CI environment, and provide final overrides via the command line.

To configure different modules within a single application, use configargparse.get_argument_parser(name). This works similarly to logging.getLogger(name), allowing different modules to define and retrieve their own command-line arguments globally.

# utils.py
import configargparse
p = configargparse.get_argument_parser()
p.add_argument("--utils-setting", help="Config-file-settable option for utils")

# main.py
import configargparse
import utils
p = configargparse.get_argument_parser()
p.add_argument("-x", help="Main module setting")
options = p.parse_known_args() # Use parse_known_args() to avoid errors from other modules

ConfigArgParse extends Python's standard argparse to support config files and environment variables. It supports all standard argparse functionality and can serve as a drop-in replacement.

To use it, import configargparse and use configargparse.ArgParser instead of argparse.ArgumentParser.

import configargparse

p = configargparse.ArgParser(default_config_files=['/etc/app/conf.d/*.conf', '~/.my_settings'])
p.add('--genome', required=True, help='path to genome file')
# ... add other arguments

options = p.parse_args()

To install the ConfigArgParse library, use the standard Python package manager:

pip install ConfigArgParse

The CompositeConfigParser tries multiple parsers in sequence. If you want to support both TOML and INI, you must place the TomlConfigParser first in the list, as the INI parser is more permissive and might consume TOML files incorrectly.

import configargparse

my_tool_sections = ['tool.my_super_tool', 'tool:my_super_tool', 'my_super_tool']

parser = configargparse.ArgParser(
         default_config_files=['setup.cfg', 'my_super_tool.ini'],
         config_file_parser_class=configargparse.CompositeConfigParser([
             configargparse.TomlConfigParser(my_tool_sections),
             configargparse.IniConfigParser(my_tool_sections, split_ml_text_to_list=True)
         ]),
     )

When using ConfigparserConfigFileParser, multi-line dictionary syntax in the config file is converted to single-line strings. You can then use yaml.safe_load as the type in add_argument to reconstruct the Python dictionary.

# inside your config file (e.g. config.ini)
[section1]
system1_settings: { 'a':True, 'b':[2, 4, 8, 16], 'c':{'start':0, 'stop':1000}, 'd':'experiment 32' }

# in your configargparse setup
import configargparse
import yaml

parser = configargparse.ArgParser(
    config_file_parser_class=configargparse.ConfigparserConfigFileParser
)
parser.add_argument('--system1_settings', type=yaml.safe_load)

args = parser.parse_args() # args.system1_settings is now a valid python dict

The TomlConfigParser allows you to integrate with pyproject.toml files by specifying the relevant section table.

# inside pyproject.toml
[tool.my-software]
format-string = "restructuredtext"
repeatable-option = ["https://docs.python.org/3/objects.inv"]

import configargparse
parser = configargparse.ArgParser(
         default_config_files=['pyproject.toml'],
         config_file_parser_class=configargparse.TomlConfigParser(['tool.my-software']),
     )

The IniConfigParser supports sections and can be used to integrate with setup.cfg. It can be initialized with a list of allowed sections.

Key features:

• Does not convert multiline strings to single lines.
• split_ml_text_to_list=True: Converts multiline text into a list.
• Supports quoting strings to preserve whitespace or prevent list conversion.

import configargparse
parser = configargparse.ArgParser(
         default_config_files=['setup.cfg', 'my_super_tool.ini'],
         config_file_parser_class=configargparse.IniConfigParser(['tool:my_super_tool', 'my_super_tool']),
     )

To display default values in the help message and disable automatic line-wrapping, use ArgumentDefaultsRawHelpFormatter when initializing the parser.

import configargparse
parser = configargparse.ArgParser(formatter_class=configargparse.ArgumentDefaultsRawHelpFormatter)

When adding arguments, you can specify an env_var to allow configuration via environment variables. Additionally, any argument starting with -- can be set within a configuration file.

To enable a specific argument to be used as a config file path, use is_config_file=True.

import configargparse

p = configargparse.ArgParser()

# Define a config file path argument
p.add('-c', '--my-config', required=True, is_config_file=True, help='config file path')

# Define an option that can be set via environment variable 'DBSNP_PATH'
p.add('-d', '--dbsnp', help='known variants .vcf', env_var='DBSNP_PATH')

# Define an option that can be set in a config file (because it starts with '--')
p.add('--genome', required=True, help='path to genome file')

options = p.parse_args()