Usage

Understand configaro

configaro provides a config object loaded from a defaults config module in the config package and an optional locals config module in the config package or other directory.

A config package is the name of a Python package to search for defaults and locals config modules.

A config module is a Python module containing config data in a dict module attribute named config. Values found in a locals config module will override those found in the defaults config module.

A config object is a dot-addressable dict containing config data loaded from a defaults and optional locals config modules. The config object is built by calling the configaro.init() API. After initialization the config object, or any portion of it, may be queried with the configaro.get() API or modified with the configaro.put() API.

A config property is a string identifying a config object or config config value in a dot-addressable format, such as inner.prop.

A config value is a scalar value of some type, typically None, bool, float, int or str type, accessed by config property.

Add configaro to your project

configaro must be added to your project before use.

Add the package dependency using pipenv:

$ cd ~/projects/demo_prj
$ pipenv install configaro

Alternatively, add it to your requirements.txt file and pip3 install it into your Python environment:

$ pip3 install -r requirements.txt

Add defaults config module

If a demo_prj project contains a demo_pkg package, create a demo_prj/demo_pkg/config config package directory:

$ mkdir demo_pkg/config

Create a demo_pkgr/config/defaults.py config module in that directory:

$ cat >> demo_pkg/config/defaults.py << EOF
config = {
    'greeting': 'hello',
    'subject': {
        'first_name': 'Joe',
        'last_name': 'World'
    }
}
EOF

Initialize the library

In your code, initialize the configaro library with the configaro.init() API and the name of your config package:

import configaro
configaro.init('demo_pkg.config')

Query configuration

Query the config object with the configaro.get() API:

config = configaro.get()
print(f'{config.greeting}, {config.subject}!')

Note

Config properties are dot-addressable. This is more convenient than using dict-style data['prop'] access, however that works as well.

You can grab a specific sub-configuration by passing in the name of a specific property to query:

greeting = configaro.get('greeting')
subject = configaro.get('subject')
print(f'{greeting}, {subject}!')

You can query multiple specific properties at one time:

greeting, subject = configaro.get('greeting', 'subject')
print(f'{greeting}, {subject}!')

You can grab the entire subject config data by its property name:

configaro.get('subject')

You can grab a nested config value with its dot-addressed property name:

configaro.get('subject.first_name')

Modify configuration

Modify the config object with the configaro.put() api:

configaro.put('subject.first_name=Jane')

If you are not modifying hierarchical config data, you can use the keyword args invocation:

configaro.put(greeting='Aloha')

Note

This will not work with hierarchical config data as the dot, or ., character is not valid in keyword args as key names must be valid Python names.

The hyphen, or -, character is similarly not allowed in keyword args. Save yourself some pain and use the underscore, or _, character instead.

Add locals config module

The config data found in the defaults config module can be overridden with config data found in the locals config module. The locals config module can be loaded from one of three sources, in precedence order from highest to lowest:

  • a locals config module path passed to configaro.init() API
  • a locals config module path specified by environment variable name passed to configaro.init() API
  • a locals config module path found in the config package passed to configaro.init() API

If no locals config module is found, the config object will contain only the defaults config module’s config data.

Warning

If you use a locals.py config module in the config package directory, ensure that you add its file path to your .gitignore file, otherwise it will always be found, effectively becoming a second defaults config module.