Usage — configaro 0.9.8 documentation

# 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.