formats

The following formats are included within cincoconfig. There should not be a reason to directly reference these classes. Instead, to save or load a configuration in the JSON format, for example, use:

config.save('config.json', format='json')

This will automatically create the cincoconfig.formats.json.JsonConfigFormat.

class cincoconfig.formats.BsonConfigFormat

BSON configuration file format. This format is only available when the bson package is installed.

This class should not be directly referenced. Instead, use the config load() and save() methods, passing format=’bson’.

config.save('filename.bson', format='bson')
# or
config.load('filename.bson', format='bson')
dumps(config, tree)

Serialize the basic value tree to BSON bytes document.

Parameters

  • config (Config) – current config

  • tree (dict) – basic value tree

Return type

bytes

loads(config, content)

Deserialize the content (a bytes instance containing a BSON document) to a Python basic value tree.

Parameters

  • config (Config) – current config

  • content (bytes) – content to serialize

Return type

dict

Returns

the deserialized basic value tree

class cincoconfig.formats.JsonConfigFormat(pretty=True)

JSON configuration file format.

This class should not be directly referenced. Instead, use the config load() and save() methods, passing format=’json’.

config.save('filename.json', format='json')
# or
config.load('filename.json', format='json')
Parameters

pretty (bool) – pretty-print the JSON document in the call to json.dumps()

dumps(config, tree)

Deserialize the content (a bytes instance containing a JSON document) to a Python basic value tree.

Parameters

  • config (Config) – current config

  • content – content to serialize

Return type

bytes

Returns

the deserialized basic value tree

loads(config, content)

Serialize the basic value tree to JSON bytes document.

Parameters

  • config (Config) – current config

  • tree – basic value tree

Return type

dict

class cincoconfig.formats.PickleConfigFormat

Python pickle configuration file format. This format uses the pickle module to serialize and deserialize the configuration basic value tree.

This class should not be directly referenced. Instead, use the config load() and save() methods, passing format=’pickle’.

config.save('filename.cfg', format='pickle')
# or
config.load('filename.cfg', format='pickle')
dumps(config, tree)

Deserialize the content (a bytes instance containing a Pickled object) to a Python basic value tree.

Parameters

  • config (Config) – current config

  • content – content to serialize

Return type

bytes

Returns

the deserialized basic value tree

loads(config, content)

Serialize the basic value tree to PIckle bytes document.

Parameters

  • config (Config) – current config

  • tree – basic value tree

Return type

dict

class cincoconfig.formats.XmlConfigFormat(root_tag='config')

XML configuration file format.

This class should not be directly referenced. Instead, use the config load() and save() methods, passing format=’xml’.

config.save('filename.xml', format='xml')
# or
config.load('filename.xml', format='xml')

To handle dynamic configurations, the Python type for each XML element is stored in the type attribute.

<x type="int">1024</x>

When the configuration file is loaded, the formatter will attempt to parse the original Python type. If the parsing fails then the original string value is stored in the basic value tree.

Parameters

root_tag (str) – root configuration tag name

_to_element(key, value)

Convert the key/value pair to an XML element.

Parameters

  • key (str) – the field key (becomes the tag name)

  • value (Any) – the field valid

Return type

Element

Returns

the element containing the XML encoded key/value pair

_from_element(ele, py_type=None)

Parse the XML element to the original Python type. This method will attempt to convert any basic types to their original Python type and, if conversion fails, will use the original string value. For example:

<x type="int">blah</x>

This method will attempt to parse the value, blah, as a int, which will fail. Then, the method will store the original string value in the basic value tree:

tree = {
    'x': 'blah'
}
Parameters

  • ele (Element) – the XML element to convert

  • py_type (Optional[str]) – force the Python type attribute rather than reading the Python type from the type attribute

Return type

Any

Returns

the parsed Python value

_prettify(ele)

Pretty print the XML element.

Parameters

ele (Element) – XML element to pretty print

Return type

bytes

Returns

the pretty printed XML element

dumps(config, tree)

Serialize the basic value tree to an XML bytes document. The returned XML document will contain a single top-level tag named root_key that all other values are stored under.

Parameters

  • config (Config) – current config

  • tree (dict) – basic value tree

Return type

bytes

Returns

the serialized basic value tree

loads(config, content)

Deserialize the content (a bytes instance containing an XML document) to a Python basic value tree. The returned basic value tree will be scoped to root_tag, if it exists in the deserialized dict.

Parameters

  • config (Config) – current config

  • content (bytes) – content to deserialize

Return type

dict

Returns

deserialized basic value tree

class cincoconfig.formats.YamlConfigFormat(root_key=None)

YAML configuration file format. This format is only available when the PyYAML package is installed.

This class should not be directly referenced. Instead, use the config load() and save() methods, passing format=’yaml’.

config.save('filename.yml', format='yaml')
# or
config.load('filename.yml', format='yaml')

By default, the basic value tree is serialized to YAML document as-is, where top-level configuration values are placed at the top level of the config file. For example:

>>> # assume tree = {'x': 1, 'y': 2}
>>> print(config.dumps(format='yaml'))
x: 1
y: 2

The root_key argument can be specified to store all configuration values under a single top-level key:

>>> # assume tree = {'x': 1, 'y': 2}
>>> print(config.dumps(format='yaml', root_key='CONFIG'))
CONFIG:
    x: 1
    y: 2

The root_key argument affects both how loads() and dumps() behave.

Parameters

root_key (Optional[str]) – the root config key that the configuration values should be stored under

dumps(config, tree)

Serialize the basic value tree to YAML bytes document. If root_key was specified, the returned YAML document will contain a single top-level field named root_key that all other values are stored under.

Parameters

  • config (Config) – current config

  • tree (dict) – basic value tree

Return type

bytes

Returns

the serialized basic value tree

loads(config, content)

Deserialize the content (a bytes instance containing a YAML document) to a Python basic value tree. If root_key was specified, the returned basic value tree will be scoped to root_key, if it exists in the deserialized dict. This is equivalent to:

tree = yaml.load(content)
return tree[self.root_key]
Parameters

  • config (Config) – current config

  • content (bytes) – content to deserialize

Return type

dict

Returns

deserialized basic value tree

Base Classes

All configuration file formats must inherit from and implement all abstract methods in the cincoconfig.abc.ConfigFormat class.

class cincoconfig.ConfigFormat

The base class for all configuration file formats.

dumps(config, tree)

Convert the configuration value tree to a bytes object. This method is called to serialize the configuration to a buffer and eventually write to a file.

Parameters

  • config (Config) – current configuration

  • tree (dict) – basic value tree, as returned by the Config to_tree() method.

Return type

bytes

Returns

the serialized configuration

classmethod get(name, **kwargs)

Get a registered configuration format.

Parameters

  • name (str) – config format name

  • kwargs – keyword arguments to pass into the config format __init__() method

Return type

ConfigFormat

Returns

the config format instance

classmethod initialize_registry()

Initialize the format registry for built-in formats.

Return type

None

loads(config, content)

Parse the serialized configuration to a basic value tree that can be parsed by the Config load_tree() method.

Parameters

  • config (Config) – current config

  • content (bytes) – serialized content

Return type

dict

Returns

the parsed basic value tree

classmethod register(name, format_cls)

Register a new configuration format.

Parameters

  • name (str) – format name

  • format_cls (Type[ConfigFormat]) – ConfigFormat subclass to register

Return type

None