ymlconfig is a small convenience library for working with .yml configuration files. It has two features not present in the stock PyYAML library.
- !format custom tag support for doing string.format style substitution
- dict objects are converted to Bunch objects before return.
Having configuration metadata in a single human-readable file which users can easily customize to their particular circumstances makes things like project build and deployment work more smoothly and consistenly.
I find YAML files to be very easily readable, but capable of handling sophisticated use-cases like nested structures. The alternatives seem weaker:
- .ini: Too simple a format, no nested structure support.
- json: Lack of comments and too many brackets are not human-friendly.
- xml: You're kidding, right?
With configuration files the code often knows what keys it is going to access. I find reading and writing:
SetDb(config.dbSettings.serverurl)
easier than:
SetDb(config["dbSettings"]["serverurl"])
One thing missing in YAML is support for doing value substitution string formatting. The !format custom tag adds that. For example
url: &mainurl 'example.com'
searchSettings:
# override this if you don't run search on the main server
serviceUrl: !format
format: 'https://{url}/search'
url: *mainurl
With this simple fabric task.
from fabric.api import task
import ymlconfig
@task
def DoSomething(configPath = '~/project/config.yml', **kwargs):
config = ymlconfig.load_file(configPath)
print("Doing: {action} {target}.".format(config.somethingToDo))
And ~/project/config.yml containing:
mainactivity: &defaultActivity 'buy food'
where: &target 'supermarket'
somethingToDo:
action: !format
format: '{reason} so {what}'
reason: 'I'm hungry'
what: *defaultActivity
target: !format
format: '{operator} {target}'
operator: 'at'
target: *target
$ fab DoSomething
Doing: I'm hungry so buy food at supermarket.
$ fab DoSomething:reason='broke',what='get money',target='the bank')
Doing: I'm broke so get money at the bank.
The !format custom YAML tag provides two extensions to standard PyYAML parsing. The contents of the node must be a mapping, and must contain a format member, which must be a string. It operates as follows.
First, any optional kwargs that were passed to the load function are substituted for any matching items in the node.
Second, python string.format is called on the format member string passing all the members of the node object as named arguments.
For example with the following data:
username: &name 'Fred'
value: !format
format: '{name} likes {food}.'
name: *name
food: 'chocolate'
print(ymlconfig.load_data(data).value)
>>> Fred likes chocolate.
print(ymlconfig.load_data(data, food='carrots').value)
>>> Fred likes carrots.
yml_data: yml data to be parsed returns: Bunch() object con
In addition to the standard PyYAML parsing, the !format custom tag is supported.
A thin wrapper around ymlconfig.load, that opens the file at path and passes it's data to ymlconfig.load.