Organizing your config.yaml

Location of config.yaml

The base yamjam config file is located ~/.yamjam/config.yaml

• on windows:

  c:\documents and settings\[username]\.yamjam\config.yaml

• on unix:

  ~/.yamjam/config.yaml

Then yamjam looks for possible overrides/additions in the current working directory of the APP for a file named config.yaml (if it exists) This would be the project config.yaml

You can override the config file(s) when you call the function by specifying a different one explicitly. i.e.

cfg = yamjam('/path/to/file/file')

By default YamJam looks for two config.yaml files, the base and then a project specific one. You may specify one or more files. Each file path listed should be separated by semi-colons(;) NOTE: if you specify files, YamJam then only looks for them and not the default base and project files.

cfg = yamjam('/path/to/file/file1;/other/path/file2')

Base config only

The vast majority of use cases can be accomplished with just a base config located at ~/.yamjam/config.yaml be hesitant to implement a project level config.yaml until you hit an edge case that requires it. This is the primary way of using YamJam. The project level config.yaml and user specified locations cause as many problems as the solve and or only applicable to a small set of edge cases. You will be best served by not straying from the KISS principle.

Structure of config.yaml

config.yaml is a straight up yaml file. See http://pyyaml.org/ and http://www.yaml.org/ for advanced usage. However, if you write python you know what you need to write decent yaml. White space is relevant and that is a good thing! What makes Python a joy to read is the same for yaml.

Example

if you edit your ~/.yamjam/config.yaml file to include

myproject:
    key1: value
    key2: 42

It is returned from yamjam() as a dictionary.

{'myproject':
    {'key1': 'value',
     'key2': 42
    }
}

to get the value of key2, under myproject

>>> yamjam()['myproject']['key2']
42

Ok, now you know how to set up a dictionary in yaml, here is how you set up a list for a value.

edit config.yaml

myproject:
    key1: value
    key2: [42, 21, 7]

Now the value of key2 will return a list with 3 integers.

>>> yamjam()['myproject']['key2']
[42, 21, 7]

Now you are truly dangerous. You can create a dictionary of dictionaries that can contain more dictionaries, lists, integers, floats, strings, etc.

In fact yaml and pyyaml can do some wonderfully advanced stuff. But, always tend to the simplest form that will get the job done, think DRY KISS.

Logical Alignment

Since your config.yaml can store settings for more than one project and it almost always will, the standard use case is to create a section named for the project that uses it. i.e. If you have a Django project named ‘myproject’ then create a section in your config.yaml named myproject.

myproject:
    django-secret-key: my-secret-key

Ok, now you will need database connection information. So let’s add it.

myproject:
    django-secret-key: my-secret-key
    database:
        engine: django.db.backends.postgresql_psycopg2
        name: mydatabase
        user: mydatabaseuser
        password: mypassword
        host: 127.0.0.1
        port: 5432

Now let’s create config settings for our next-project

myproject:
    django-secret-key: my-secret-key
    database:
        engine: django.db.backends.postgresql_psycopg2
        name: mydatabase
        user: mydatabaseuser
        password: mypassword
        host: 127.0.0.1
        port: 5432

next-project:
    django-secret-key: next-project-secret-key
    database:
        engine: django.db.backends.postgresql_psycopg2
        name: mynextdatabase
        user: mynextdatabaseuser
        password: mynextpassword
        host: 127.0.0.1
        port: 5432

Ok, let’s access the django-secret-key for next-project

>>> yamjam()['next-project']['django-secret-key']
next-project-secret-key

So, now you can start factoring out your sensitive data from your app. One more thing, in case it is not obvious, you can reduce your typing by caching just the config information you need to access.

>>> cfg = yamjam()['next-project']
>>> cfg['django-secret-key']
next-project-secret-key

That will keep your code looking clean and also, you just cached the results of the yamjam() call. Further accesses to cfg now happen at break-neck python speed.

Each time your call yamjam() it re-reads the config files. Sometimes this is desired, sometimes not but as a programmer you have complete and simple control over how things happen.

Merging Config Data

When more than one config.yaml is processed, base and project are merged using the following 2 rules.

If the value being merged is not a dictionary then the base value is replaced by the project.

{‘key1’: val1} merged with {‘key1’: val2} results in {‘key1’: val2}

If the value being merged is a dictionary, then it is merged.

{‘key1’: {‘foo’: 2}} merged with {‘key1’: {‘bar’: 3}} results in {‘key1’: {‘foo’: 2, ‘bar’: 3}}

and

{‘key1’: {‘foo’: 2}} merged with {} results in {‘key1’: {‘foo’: 2}}

This way the project config only specified overrides and additions to the base config. See the tests for test_merge.py for more examples. But the net result of the merge should not surprise you and allow for you to supply the minimal amount of project config data needed to modify the base config.