Usage¶
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 to your project¶
Add a defaults config module to your config package directory:
# mypkg/config/defaults.py
config = {
'inner': {
'prop': 'some_value'
}
}
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.