twelvefactor¶

twelvefactor is a library that provides utilities for creating a 12 factor application, at present it allows you to parse the processes environment variables into a configuration dictionary.

Getting Started¶

Installation¶

An install can be performed with the following:

pip install twelvefactor

Quickstart Guide¶

# settings.py
from twelvefactor import config

globals().update(config({
    'DEBUG': {
        'type': bool,
        'default': False,
    },
    'SECRET_KEY': str
}))

The above will create two variables, the first named DEBUG a boolean defaulting to False, and the second named SECRET_KEY a string which will throw an exception if not set. Both variables will be populated from the processes environment variables.

Schema¶

Example¶

{
    'DEBUG': {
        'type': bool,
        'default': False,
    },
    'SECRET_KEY': str,
    'DATABASE': {
        'key': 'DATABASE_URL',
        'mapper': dj_database_url.parse
    },
    'SOME_SET': {
        'type': set,
        'subtype': int
    }
}

Properties¶

key¶

The name of the environment variable to look up, this allows you map map values in the environment to differently named configuration variables, it defaults to the name of the configuration variable.

default¶

A value to use should no environment variable be found, if no default is provided then an error will be thrown.

type¶

A function to convert the string value to the correct type, this can be the type itself or a factory method to convert the value to the desired type.

When list, tuple, or set are provided then the value will be interpreted as a comma separated list and interpreted based on the subtype setting.

If no subtype is set then str is assumed.

subtype¶

A function to convert the string sub-value to the correct type, like with type this can be the type itself or a factory method.

If no type is set then str is assumed.

mapper¶

A method to post process the value after it has been converted to the correct type, it is the last transformation to be applied and should take the value and transform it into a more suitable configuration value.

A mapper should not be used to instantiate complex classes such as database adapters, these should be instantiated outside of the configuration code.

If no mapper is provided then the value is returned as is.

Shorthand¶

When only a type is required you can specify a callable instead of a dictionary defining the config value.

The following two examples are identical

{
    'DEBUG': bool
}

{
    'DEBUG': {
        'type': bool
    }
}

Reference¶

API¶

class twelvefactor.Config(environ=None)¶

Bases: object

Config environment parser.

This class allows chosen configuration values to be extracted from the processes environment variables and converted into the relevant types.

parser = Config()

config = parser({
    'DEBUG': {
        'type': bool,
        'default': False,
    },
    'SECRET_KEY': str,
})

The above will populate the config variable with two values, DEBUG will be populated with a bool from the environment variable of the same name, throwing an exception on invalid values and defaulting to False when none is provided, and SECRET_KEY will be a str and throw a ConfigError when no value is found in the environment.

An optional environ param can be passed in order to override the environment.

Parameters:	environ (dict) – environment dictionary, defaults to `os.environ`

__call__(schema)¶

Parse the environment according to a schema.

Parameters:	schema (dict) – the schema to parse
Returns:	a dictionary of config values
Return type:	dict

get(key, default=<object object>, type_=<class 'str'>, subtype=<class 'str'>, mapper=None)¶

Parse a value from an environment variable.

>>> os.environ['FOO']
<<< '12345'
>>>
>>> os.environ['BAR']
<<< '1,2,3,4'
>>>
>>> 'BAZ' in os.environ
<<< False
>>>
>>> parser = Config()
>>> parser.get('FOO', type_=int)
<<< 12345
>>>
>>> parser.get('BAR', type_=list, subtype=int)
<<< [1, 2, 3, 4]
>>>
>>> parser.get('BAZ', default='abc123')
<<< 'abc123'
>>>
>>> parser.get('FOO', type_=int, mapper=lambda x: x*10)
<<< 123450

Parameters:	key (str) – the key to look up the value under default (object) – default value to return when when no value is present type_ (type) – the type to return or factory function subtype (type) – subtype for iterator types mapper (callable) – a function to post-process the value with
Returns:	the parsed config value
Return type:	object

parse(value, type_=<class 'str'>, subtype=<class 'str'>)¶

Parse value from string.

Convert value to

>>> parser = Config()
>>> parser.parse('12345', type_=int)
<<< 12345
>>>
>>> parser.parse('1,2,3,4', type_=list, subtype=int)
<<< [1, 2, 3, 4]

Parameters:	value (str) – string type_ (type) – the type to return or factory function subtype (str) – subtype for iterator types
Returns:	the parsed config value
Return type:	object

class twelvefactor.ConfigError¶

Bases: Exception

Exception to throw on configuration errors.

twelvefactor.config¶

Additional Notes¶

Change Log¶

Here you can see the full list of changes.

Version 0.1.2¶

Released on 2016-08-11

First public preview release.

License¶

twelvefactor is licensed under the MIT license. Basically, you can do whatever you want as long as you include the original copyright and license notice in any copy of the software/source.

MIT License¶

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.