Quickstart

This guide will walk you through the basics of reading configurations.

Loading configuration files

Central supports JSON, TOML, YAML and INI files.

from central.config.file import FileConfig

config = FileConfig('./config.json')
config.load()

TOML and YAML require an external library

Loading multiple configurations

Central supports composition of configurations with ordered hierarchy.

from central.config import ChainConfig, EnvironmentConfig
from central.config.file import FileConfig

config = ChainConfig(EnvironmentConfig(), FileConfig('config.json'))
config.load()

The last configuration added overrides the keys from the previous configurations.

Reloading a configuration file

Central also supports auto reloading of configuration while running.
That means you don't longer need to restart your application to have a config take effect.

from central.config.file import FileConfig

config = FileConfig('config.json').reload_every(3600)  # 1 hour in seconds
config.load()

Not only FileConfig supports reloading, any kind of configuration can have this ability.

reload_every returns a new RealodConfig object.

Getting values from a configuration

Once you have your configuration loaded you can get the values from them.

from central.config.file import FileConfig

config = FileConfig('config.json')
config.load()

timeout = config.get('timeout')

If a key is not found in the configuration, None is returned.

Central allows you to specify a default value for when a key is not found in the configuration.

timeout = config.get('timeout', default=10)

Central, by default returns the value as it was read, that means if it was read as an int, an int is returned.
You can specify what is data type you are expecting to receive by calling get_bool, get_int, get_float, get_str, get_dict, get_list

timeout = config.get_int('timeout')

If Central cannot convert the data to the type that you are expecting an exception is raised.

Accessing nested keys

The accessor methods also accept formatted paths to deeply nested keys. For example, if the following JSON file is loaded:

{
    "host": {
        "address": "localhost",
        "port": 1234
    }
}

Central can access a nested field by passing a.delimited path of keys:

config.get('host.address')  # returns 'localhost'

Central can also access a subtree.

config.get('host')  # returns {"address": "localhost", "port": 1234}

Setting values into a configuration

Central is meant to be a read only library but it is possible to add/set values using a memory configuration.

from central.config import MemoryConfig

config = MemoryConfig()
config.set('timeout', 100)

You can also use a MemoryConfig to hold default values.

from central.config import ChainConfig, MemoryConfig
from central.config.file import FileConfig

defaults = MemoryConfig()
defaults.set('timeout', 100)

config = ChainConfig(defaults, FileConfig('config.json'))
config.load()

timeout = config.get('timeout')

In the example above, if the key timeout isn't in the json file, the value is returned from the memory configuration.

Case insensitive

Central configuration keys are case insensitive, if your configuration has duplicate keys the last one wins.

# main.py

from central.config import MemoryConfig

config = MemoryConfig()
config.set('timeout', 100)
config.set('Timeout', 200)

print(config.get('timeout))

python main.py
>> 200