configviper Package

configviper Module

class configviper.configviper.ConfigViper

backup_filename

The full path and file name for the backup. See is_make_backups and save().

config_filename

The full path and file name this instance is using. See attributes pathname and filename.

static configure(pathname='', filename='', separator='.', auto_save=True, encoding='utf-8', ignore_encoding=False, **kwargs)

Set parameters that will be used by all instances of ConfigViper. This method is intended to be called only once, when the host application is preparing everything up to be ran.

Parameters:

• pathname – The full directory path where the configuration file should be placed. If not set, defaults to user’s home directory at ~/.configviper.
• filename – The configuration file name (usually) with .json extension. If not set, defaults to configviper.json.
• separator – The config-path separator. Defaults to ..
• auto_save – When a value is set (set() method) or when stabilize() method is called the configuration file will be automatically saved. Defaults to True.
• encoding – String. Encoding which is to be used for the file. Defaults to "UTF-8".
• ignore_encoding – Boolean. If ignore encoding the JSON file will be opened with the Python’s built-in open function. Otherwise, the file will be opened with the codecs.open, wich is the default behavior.

exists(path)

Test if given config-path already exists.

filename

The configuration file name this instance is using. The path where the file is placed is determined by pathname attribute. See attribute config_filename.

get(path)

Get value for the given config-path.

get_converter(path)

Get converter for the given config-path or a DEFAULT_CONVERTER if there’s none.

get_unique_backup_filename()

get_unique_dir_name()

get_unique_temp_filename()

is_auto_save

Indicates whether or not the configuration file should be saved immediately before set() method is called. This flag is also considered when stabilize() method is called.

is_keep_backups

Indicate whether the backup file should be kept when the save() method completes, even if an error occurs. See is_make_backups.

is_make_backups

Indicates whether a backup should be made right before actual save operation. The save() method is capable of doing a backup and restore from that backup if the actual save operation fails. See is_keep_backups. The backup file will have the same name as the original configuration file with .backup appended.

path_separator

The config-path separator this instance is using.

pathname

The path name where configuration file should be saved by this instance. File name is determined by filename attribute. See attribute config_filename.

register(path, converter)

This method (re)associate a converter instance with a config-path. If the config-path already exists then their current value: (1) will be got with the current converter; (2) the new converter is set and; (3) the value is settled again with the new converter in place.

save()

Save configurations formatted as JSON to a file. This method attempts to be as safe as possible, using a strategy based on a temporary directory that is created in the same directory as the configuration file itself. During the save process, the directory will looks like:

~/.configviper/configviper.json
~/.configviper/configviper-4b1b7b5f4a594926ac82de8ecaa439c4/c8c.backup
~/.configviper/configviper-4b1b7b5f4a594926ac82de8ecaa439c4/c8c.temp

Where the configviper.json is the actual configuration file. The configviper-4b1b7b5f4a594926ac82de8ecaa439c4 is a temporary directory name that is unique to the current process. The file c8c.backup is a copy of configviper.json and the file c8c.temp is the file where the configuration data was actually saved. With all that in place, the .temp file will be copied back to the original configuration file. If everything goes ok, the temporary directory will be wiped out and the save is done. If not, the backup file will be restored and the temporary directory will be wiped out.

set(path, value)

Set value for the given config-path. Be careful to not overrun an existing config-path that points to a value that’s not a dictionary or a PathOverrun exception will be raised.

set_auto_save()

Save configurations on every call to set() so you do not have to call save() yourself. This is the default behavior.

stabilize(values)

This method will merge existing config-paths with config-paths and values and converters you determine. The values argument should be a tuple of tuples. Each sub-tuple should have three values where the first value is the config-path; second is their default value and third the converter instance for that config-path:

from datetime import datetime
from configviper import ConfigViper
from configviper.converters import DATETIME_CONVERTER

values = (
    ('path.to.config', 1, None),
    ('path.to.another', datetime.now(), DATETIME_CONVERTER),)

The first sub-tuple sets config-path "path.to.config", their default value which is 1, and None as their converter, meaning that that config-path does not need a special converter. Second sub-tuple sets config-path "path.to.another", their default value which is current date and time and a built-in converter for datetime objects. Then you call stabilization in a ConfigViper instance:

conf = ConfigViper()
conf.stabilize(values)

When you instantiate a ConfigViper class the configuration file is automatically loaded. In the stabilization process, existing config-paths are preserved with their current values, but the converters are always set. So if you write your own converter be aware to write a converter that can handle older formats of previous versions.

stop_saving()

Stop saving on every set(). This is particularly useful when you need to set various configurations at once, to avoid the overburden of save on every set. The next call to save() will restore the normal operation according to is_auto_save. The pattern is:

conf = ConfigViper()
conf.stop_saving()
conf.set('spam.ham.eggs', 'sausage')
conf.set('foo.bar', 'baz')
..
conf.save()

exception configviper.configviper.PathOverrun(value)

This exception will be raised by set() method when a config-path overrun an existing config-path that points to a value other than a dict (or object in JSON lingo). For example, consider the following Python dictionary:

>>> d = { 'a': { 'b': 1 } } # "a.b" = 1 (int)

If you try to overrun “b” with an aditional “c”, you’ll got a PathOverrun exception, like this:

>>> conf = ConfigViper()
>>> conf.set('a.b', 1)
>>> conf.get('a.b')
1
>>> conf.set('a.b.c', 2)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "configviper.py", line 137, in set
    'value.' % path)
configviper.PathOverrun: '"a.b.c" config-path segment overrun an existing value.'

class configviper.configviper.ProxyProperty(proxy_map, path, configviper_instance)

A proxy support for access configuration paths as object attributes.

path

The config-path until current proxy instance.

converters Module

class configviper.converters.Converter

Base class for configuration value converters.

to_json(value)

Convert from Python data type to a type that JSON can handle.

to_python(value)

Convert a JSON value to a Python data type.

configviper.converters.DATETIME_CONVERTER = <configviper.converters.DatetimeConverter object at 0x974ddcc>

A DatetimeConverter instance.

configviper.converters.DATE_CONVERTER = <configviper.converters.DateConverter object at 0x974dc8c>

A DateConverter instance.

configviper.converters.DECIMAL_CONVERTER = <configviper.converters.DecimalConverter object at 0x974dcec>

A DecimalConverter instance.

configviper.converters.DEFAULT_CONVERTER = <configviper.converters.Converter object at 0x974d6ac>

A Converter instance.

class configviper.converters.DateConverter

A converter for datetime.date configuration value objects. When converted from Python, the result string will be formated as yyyy-mm-dd.

to_json(value)

Convert datetime.date objects to an understandable string representation.

to_python(value)

Convert a string to a datetime.date object, as if it’s formatted like yyyy-mm-dd.

class configviper.converters.DatetimeConverter

A converter for datetime.datetime configuration value objects. When converted from Python, the result string will be formated as yyyy-mm-dd hh:MM:ss.

to_json(value)

Convert datetime.datetime objects to an understandable string representation.

to_python(value)

Convert a string to a datetime.datetime object, as if it’s formatted like yyyy-mm-dd hh:MM:ss.

class configviper.converters.DecimalConverter

A converter for decimal.Decimal configuration value objects. This converter should be used for simple values that’s expected to behave in a predictable manner, like money values, since this converter simple convert from Python using str and to Python using decimal.Decimal constructor on a string value.

to_json(value)

Convert decimal.Decimal objects to a string representation.

to_python(value)

Convert a string to a decimal.Decimal object.

configviper.converters.TIME_CONVERTER = <configviper.converters.TimeConverter object at 0x974dcac>

A TimeConverter instance.

class configviper.converters.TimeConverter

A converter for datetime.time configuration value objects. When converted from Python, the result string will be formated as hh:MM:ss.

to_json(value)

Convert datetime.time objects to an understandable string representation.

to_python(value)

Convert a string to a datetime.time object, as if it’s formatted like hh:MM:ss.