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