Quickstart

To install the library, go for:

pip install configurator[yaml,toml]

Here’s how you would handle a layered set of defaults, system-wide config and then optional per-user config:

from configurator import Config

defaults = Config({
    'cache': {
        'location': '/tmp/my_app',
        'max_files': 100,
    },
    'banner': 'default banner',
    'threads': 1,
})
system = Config.from_path('/etc/my_app/config.yaml')
user = Config.from_path('~/.my_app.yaml', optional=True)
config = defaults + system + user

Now, if we wanted configuration from the environment and command line arguments to override those provided in configuration files, we could do so as follows:

import os
from argparse import ArgumentParser
from configurator import convert, target, required

config.merge(os.environ, {
    convert('MYAPP_THREADS', int): 'threads',
    required('MYAPP_CACHE_DIRECTORY'): 'cache.location',
})

parser = ArgumentParser()
parser.add_argument('--threads', type=int)
parser.add_argument('--max-files', type=int)
args = parser.parse_args()

config.merge(args, {
    'threads': 'threads',
    'max_files': 'cache.max_files',
})

To check the configuration we’ve accumulated is sensible we can use a data validation library such as Voluptuous:

from os.path import exists
from voluptuous import Schema, All, Required, PathExists

schema = Schema({
    'cache': {'location': All(str, PathExists()), 'max_files': int},
    'banner': Required(str),
    'threads': Required(int),
    })

schema(config.data)

So, with all of the above, we could use the following sources of configuration:

>>> import os, sys
>>> print(open('/etc/my_app/config.yaml').read())
cache:
  location: /var/my_app/
<BLANKLINE>
>>> os.environ['MYAPP_THREADS']
'2'
>>> os.environ['MYAPP_CACHE_DIRECTORY']
'/var/logs/myapp/'
>>> sys.argv
['myapp.py', '--threads', '3', '--max-files', '200']

With the above sources of configuration, we’d end up with a configuration store that we can use as follows:

>>> config.cache.location
'/var/logs/myapp/'
>>> config.cache.max_files
200
>>> config.banner
'default banner'
>>> config.threads
3