konf 1.1.2a0

Konf is a Python package which designed to simplify the use of variables in configuration files. json and yaml supported out of the box.

Konf

Designed to simplify the use of variables in configuration files. Import variables to Python must be easy and reliable!

Installation:

pip install konf

Running tests:

nosetests

Features:

• Easy to use

• JSON and YAML support out of the box

• Require typing or validation of all input data for human factor prevention

• Python 2.7, 3+ compatible

• Unit-tested

• Custom format of configuration files can be used

For Python data structures validation can be used one of these excellent libs:

• alecthomas/voluptuous

• kolypto/py-good (by default)

For YAML parsing is used a great lib of Kirill Simonov PyYAML

Quick start

Just look at the code.

from konf import Konf

# Filling of variables from config file fruits.yml in k_ object
k_ = Konf('fruits.yml')

# Getting variables from k_. 1st arg is a name of variable (specified in config),
# 2nd can be a type or validator
APPLE = k_('APPLE', basestring)
ORANGE = k_('ORANGE', basestring)

# In the next example is using validator: list, that must contain only objects with
# basestring type (str or unicode)
BASKET_OF_MANDARINS = k_('BASKET', [basestring])

# And dict with two required keys with appropriate types
NAMED_BANANAS = k_('BANANAS', {'yellow': basestring, 'banana2': basestring})

# Other example with grades.json file
k2_ = Konf('grades.json')

DAVID_GRADE = k2_('DAVID', int)
MARIA_GRADE = k2_('MARIA', int)

You can find more details and advanced examples about natural validation on voluptuous or good pages.

Default values

Do you need to use a value if any variable is not contained in a config file? You can use default value.

from konf import Konf

k_ = Konf('extra.yml')

# 3rd arg is a default. If variable STRICT is not contained in config file,
# USE_STRICT will be False
USE_STRICT = k_('STRICT', bool, False)

# You can also use None as default value
WINNER = k_('WINNER', int, None)

# Default values will never be validated, because you forcibly declaring it.
# So, the next example is legit.
SHIFT_TIME = k_('SHIFT', int, complex(42, 42))

Checking not involved variables

Sometimes you want to be sure that all of the variables in a config file are involved and you haven’t forgotten anything. In this situation the check_involved() method can be helpful.

from konf import Konf

k_ = Konf('required.yml')

IMPORTANT_1 = k_('IMPORTANT_1', int)

IMPORTANT_2 = k_('IMPORTANT_2', int)

# If config file contains anything except IMPORTANT_1 and IMPORTANT_2,
# RedundantConfigError will be raised after call of this method!
k_.check_involved()

Default values and check_involved() also working fine together.

from konf import Konf

k_ = Konf('foo.yml')

X = k_('X', int, 0)

Y = k_('Y', int, 0)

# If X and Y doesn't contained in the config file, RedundantConfigError will not be raised,
# just X == 0 and Y == 0
k_.check_involved()

List of supporting Exceptions

ValidationError:

Raises when data from config file doesn’t match to the type_or_validator arg

IncompleteConfigError:

Raises after trying to get variable that not contained in a config file

ReadError:

Raises when config file can’t be read

ParseError:

Raises if third-party parser can’t parse configuration file

ReassignmentError:

Raises if variable loaded not for the first time

FileExtensionError:

Raises if extension of the config is not .yml or .json, and parse_callback arg is not specified

RedundantConfigError:

Raises after check_involved() call if any of variables in config file is not involved in the program