Using confmodel

Defining your configuration

A config specification is a subclass of Config with some field attributes.

from confmodel import Config
from confmodel.fields import ConfigInt, ConfigText

class MyConfig(Config):
    """
    This is a demo config specification.

    It's important to write a docstring for the class and to put helpful
    information into the mandatory ``doc`` parameter in each field.
    """

    incantation = ConfigText("The incantation to recite.", required=True)
    magic_number = ConfigInt("A magic number.", default=42)

As a bonus, confmodel generates ReST docstrings for your config classes, suitable both for runtime introspection and inclusion in Sphinx documentation.

>>> print MyConfig.__doc__
This is a demo config specification.

It's important to write a docstring for the class and to put helpful
information into the mandatory ``doc`` parameter in each field.

Configuration options:

:param str incantation:

    The incantation to recite.

:param int magic_number:

    A magic number.

Example rendered documentation:

class MyConfig

This is a demo config specification.

It’s important to write a docstring for the class and to put helpful information into the mandatory doc parameter in each field.

Configuration options:

Parameters:

• incantation (str) – The incantation to recite.
• magic_number (int) – A magic number.

Accessing config data

Once the specification has been defined, it can be used to access configuration data acquired from some arbitrary source. A config specification class can be instantiated with a dict [1] containing keys that match the field attributes.

>>> config = MyConfig({'incantation': 'Open sesame!'})
>>> config.incantation
'Open sesame!'
>>> config.magic_number
42

The data is validated when the config object is instantiated, so you’ll know immediately if something is wrong.

>>> config = MyConfig({})  # No configuration data.
Traceback (most recent call last):
    ...
ConfigError: Missing required config field 'incantation'

>>> config = MyConfig({'incantation': 'Open sesame!', 'magic_number': 'six'})
Traceback (most recent call last):
    ...
ConfigError: Field 'magic_number' could not be converted to int.

Further information

Sometimes it’s necessary for a config field to refer to other fields to find or construct its value, particularly as systems evolve over time. See Field fallbacks for ways to do this.

Footnotes

[1]	More generally, any IConfigData provider can be used. A dict is just the simplest and most convenient for many cases.