configparse

Summary

configparse is a drop-in-place replacement for python's argparse module which reads configuration files in addition to command line arguments.

Features

If the configuration directory exists, all of files in <config_directory>/<prog>/ are read. All files matching ~/.<prog>* are read.

Files are treated according to their extension: config.json will be parsed as JSON, myconf.yml will be parsed as YAML.

If a file does not have an extension, it will be parsed according to the default file format. This is preset to JSON, but can be changed by applications.

Configuration Directory

On Windows, the configuration directory looked up in %AppData%. On any other OS, it is looked up from $XDG_CONFIG_HOME. If the variable is not present (on any OS), files are read from ~/.config.

Supported Formats

The following file formats are currently supported:

• JSON (.json)
• YAML (.yml)
• INI (.ini)
• TOML (.toml)

Feel free to submit a pull request adding more formats. See CONTRIBUTING.md for an overview, if you already have a parser it should be very simple.

Using configparse

As a library

If you are an application developer who wants to use the library, there is one entry point: the ConfigParser class, which is also aliased to Parser for convenience. You can treat a ConfigParser instance exactly as you would an ArgumentParser instance (as long as you pass prog to the constructor).

Note that this means that parse_args will parse sys.argv in addition to parsing configuration files. If you don't want this behavior, pass an empty list to parse_args like this: args = parser.parse_args([]).

If you want to change the default file format (e.g. for files named ~/.myprog without an extension), use parser.set_default_ext(ext), where 'ext' is the file extension for your format.

Differences from argparse

The only API differences are as follows:

• the name of the parser is ConfigParser, not ArgumentParser
• the prog keyword is required for initializing ConfigParser (so that it knows where to look for configuration files)

That's it. Everything else is done automatically.

Example

from configparse import Parser

parser = Parser(prog='myprogram')
parser.add_argument('--short', '-s', help='use short format')
args = parser.parse_args()

As an end user

You can put a configuration file in any of the following locations:

• ~/.config/<prog>/
• ~/.<prog>*

See Features for a full overview.

Example

Assume that the program basic takes the arguments '--short' and '--long'.

$ cat ~/.config/basic/config.yml
short: true
$ basic
You chose the 'short' option.
$ rm ~/.config/basic/config.yml
$ echo 'long: true' > ~/.basic.yml
$ basic
You chose the 'long' option.

Limitations

• Only long options will be applied. If a short option is present in a config file, it will be treated as if it were a long option, i.e. not looked up. For example, assuming some backend returns the dictionary {'s': 'some value'}:

from configparse import Parser

p = Parser(prog='myprog')
p.add_argument('-s', '--short')
args = p.parse_args()
assert args.short is None
assert args.s == 'some value'